More documentation examples.

eloquent · Jul 1, 2014 · b879780 · b879780
1 parent 53de73a
commit b879780
Show file tree

Hide file tree

Showing 2 changed files with 149 additions and 0 deletions.
diff --git a/README.md b/README.md
@@ -171,6 +171,82 @@ class ClassA
 }
 ```
 
+## Finding the shortest reference to a symbol
+
+*Cosmos* can determine the shortest symbol reference that will resolve to a
+given qualified symbol relative to a context:
+
+```php
+use Eloquent\Cosmos\Resolution\Context\ResolutionContext;
+use Eloquent\Cosmos\Symbol\Symbol;
+use Eloquent\Cosmos\UseStatement\UseStatement;
+
+$context = new ResolutionContext(
+    Symbol::fromString('\NamespaceA\NamespaceB'),
+    array(
+        // basic use statement
+        UseStatement::create(Symbol::fromString('\NamespaceC\SymbolA')),
+
+        // use statement with alias
+        UseStatement::create(
+            Symbol::fromString('\NamespaceD\SymbolB'),
+            Symbol::fromString('SymbolC')
+        ),
+    )
+);
+
+$symbol = Symbol::fromString('\NamespaceA\NamespaceB\SymbolD');
+echo $symbol->relativeToContext($context); // outputs 'SymbolD'
+
+$symbol = Symbol::fromString('\NamespaceC\SymbolA');
+echo $symbol->relativeToContext($context); // outputs 'SymbolA'
+
+$symbol = Symbol::fromString('\NamespaceD\SymbolB');
+echo $symbol->relativeToContext($context); // outputs 'SymbolC'
+
+$symbol = Symbol::fromString('\NamespaceD\SymbolB\SymbolD');
+echo $symbol->relativeToContext($context); // outputs 'SymbolB\SymbolD'
+
+$symbol = Symbol::fromString('\NamespaceA\NamespaceB\SymbolA');
+echo $symbol->relativeToContext($context); // outputs 'namespace\SymbolA'
+
+$symbol = Symbol::fromString('\NamespaceA\NamespaceE\SymbolD');
+echo $symbol->relativeToContext($context); // outputs '\NamespaceA\NamespaceE\SymbolD'
+```
+
+## Generating an optimal resolution context for a set of symbols
+
+*Cosmos* can generate an optimal resolution context for a given set of symbols
+to be used:
+
+```php
+use Eloquent\Cosmos\Resolution\Context\Generator\ResolutionContextGenerator;
+use Eloquent\Cosmos\Symbol\Symbol;
+
+$generator = new ResolutionContextGenerator;
+$context = $generator->generate(
+    Symbol::fromString('\NamespaceA\NamespaceB'),
+    array(
+        Symbol::fromString('\NamespaceA\NamespaceB\ClassA'),
+        Symbol::fromString('\NamespaceA\NamespaceB\NamespaceC\ClassB'),
+        Symbol::fromString('\NamespaceD\NamespaceE\ClassC'),
+        Symbol::fromString('\NamespaceD\NamespaceF\ClassC'),
+        Symbol::fromString('\ClassD'),
+    )
+);
+```
+
+The generated context is then equivalent to:
+
+```php
+namespace NamespaceA\NamespaceB;
+
+use ClassD;
+use NamespaceA\NamespaceB\NamespaceC\ClassB;
+use NamespaceD\NamespaceE\ClassC as NamespaceEClassC;
+use NamespaceD\NamespaceF\ClassC as NamespaceFClassC;
+```
+
 ## What is a symbol?
 
 In *Cosmos*, a *symbol* is a generic object used to represent class, interface,

diff --git a/test/suite/DocumentationTest.php b/test/suite/DocumentationTest.php
@@ -11,7 +11,9 @@
 
 namespace Eloquent\Cosmos;
 
+use Eloquent\Cosmos\Resolution\Context\Generator\ResolutionContextGenerator;
 use Eloquent\Cosmos\Resolution\Context\Parser\ParserPosition;
+use Eloquent\Cosmos\Resolution\Context\Renderer\ResolutionContextRenderer;
 use Eloquent\Cosmos\Resolution\Context\ResolutionContext;
 use Eloquent\Cosmos\Symbol\Symbol;
 use Eloquent\Cosmos\Symbol\SymbolType;
@@ -152,4 +154,75 @@ public function testFixedResolverExample()
         $this->expectOutputString('\NamespaceB\SymbolA');
         $object->methodA();
     }
+
+    public function testRelativeToContext()
+    {
+        $this->expectOutputString(
+            'SymbolD' .
+            'SymbolA' .
+            'SymbolC' .
+            'SymbolC\SymbolD' .
+            'namespace\SymbolA' .
+            '\NamespaceA\NamespaceE\SymbolD'
+        );
+
+$context = new ResolutionContext(
+    Symbol::fromString('\NamespaceA\NamespaceB'),
+    array(
+        // basic use statement
+        UseStatement::create(Symbol::fromString('\NamespaceC\SymbolA')),
+
+        // use statement with alias
+        UseStatement::create(
+            Symbol::fromString('\NamespaceD\SymbolB'),
+            Symbol::fromString('SymbolC')
+        ),
+    )
+);
+
+$symbol = Symbol::fromString('\NamespaceA\NamespaceB\SymbolD');
+echo $symbol->relativeToContext($context); // outputs 'SymbolD'
+
+$symbol = Symbol::fromString('\NamespaceC\SymbolA');
+echo $symbol->relativeToContext($context); // outputs 'SymbolA'
+
+$symbol = Symbol::fromString('\NamespaceD\SymbolB');
+echo $symbol->relativeToContext($context); // outputs 'SymbolC'
+
+$symbol = Symbol::fromString('\NamespaceD\SymbolB\SymbolD');
+echo $symbol->relativeToContext($context); // outputs 'SymbolC\SymbolD'
+
+$symbol = Symbol::fromString('\NamespaceA\NamespaceB\SymbolA');
+echo $symbol->relativeToContext($context); // outputs 'namespace\SymbolA'
+
+$symbol = Symbol::fromString('\NamespaceA\NamespaceE\SymbolD');
+echo $symbol->relativeToContext($context); // outputs '\NamespaceA\NamespaceE\SymbolD'
+    }
+
+    public function testContextGeneration()
+    {
+$generator = new ResolutionContextGenerator;
+$context = $generator->generate(
+    Symbol::fromString('\NamespaceA\NamespaceB'),
+    array(
+        Symbol::fromString('\NamespaceA\NamespaceB\ClassA'),
+        Symbol::fromString('\NamespaceA\NamespaceB\NamespaceC\ClassB'),
+        Symbol::fromString('\NamespaceD\NamespaceE\ClassC'),
+        Symbol::fromString('\NamespaceD\NamespaceF\ClassC'),
+        Symbol::fromString('\ClassD'),
+    )
+);
+
+        $expected = <<<'EOD'
+namespace NamespaceA\NamespaceB;
+
+use ClassD;
+use NamespaceA\NamespaceB\NamespaceC\ClassB;
+use NamespaceD\NamespaceE\ClassC as NamespaceEClassC;
+use NamespaceD\NamespaceF\ClassC as NamespaceFClassC;
+
+EOD;
+
+        $this->assertSame($expected, ResolutionContextRenderer::instance()->renderContext($context));
+    }
 }