new methods in Shortcode, udpated README with usage examples

Author: thunderer

README.md

@@ -49,31 +49,61 @@ and run `composer install` or `composer update` afterwards. If you're not using
 
 ## Usage
 
-Create `Shortcode` class instance, register required shortcodes handlers and pass your strings to be parsed.
+**Replacement**
+
+Create `Processor` class instance, register required shortcodes handlers and use `process()` method to dynamically replace found matches using registered callbacks:
 
 ```php
+use Thunder\Shortcode\Extractor;
 use Thunder\Shortcode\Parser;
+use Thunder\Shortcode\Processor;
 use Thunder\Shortcode\Shortcode;
+use Thunder\Shortcode\Serializer\JsonSerializer;
 
-$parser = new Parser();
-$parser->addCode('sample', function(Shortcode $s) {
-    return json_encode(array(
-        'name' => $s->getName(),
-        'args' => $s->getParameters(),
-        'content' => $s->getContent(),
-        ));
+$processor = new Processor(new Extractor(), new Parser());
+$processor->addHandler('sample', function(Shortcode $s) {    
+    return (new JsonSerializer())->serialize($s);
     });
 
 // this will produce JSON encoded parsed data of given shortcode, eg.:
-// {"name":"sample","args":{"argument":"value"},"content":"content"}
-echo $parser->parse('[sample argument=value]content[/sample]');
+// something {"name":"sample","args":{"argument":"value"},"content":"content"} other
+echo $parser->parse('something [sample argument=value]content[/sample] other');
+```
+
+**Extraction**
+
+Create instance of class `Extractor` and use its `extract()` method to get array of shortcode matches:
+
+```php
+use Thunder\Shortcode\Extractor;
+
+$extractor = new Extractor();
+$matches = $extractor->extract('something [x] other [random]sth[/random] other');
+
+// array will contain two instances of class Match with match offsets and exact 
+// strings, like [10, '[x]'] and [20, '[random]sth[/random]']
+var_dump($matches);
+```
+
+**Parsing**
+
+Create instance of `Parser` class and use its `parse()` method to parse single shortcode string match into `Shortcode` instance with easy access to its name, parameters, and content (null if none present):
+
+```php
+use Thunder\Shortcode\Parser;
+
+$parser = new Parser();
+$shortcode = $parser->parse('[code arg=value]something[/code]');
+
+// will contain name "code", one argument and "something" as content.
+var_dump($shortcode);
 ```
 
-Edge cases:
+## Edge cases
 
 * unsupported shortcodes (no registered handler) will be ignored and left as they are,
-* mismatching closing shortcode (`[code]content[/codex]`) will be ignored, opening will be interpreted as self-closing shortcode,
-* overlapping shortcodes (`[code]content[inner][/code]content[/inner]`) are not supported and will be interpreted as self-closing, ending fragment will be ignored.
+* mismatching closing shortcode (`[code]content[/codex]`) will be ignored, opening tag will be interpreted as self-closing shortcode,
+* overlapping shortcodes (`[code]content[inner][/code]content[/inner]`) are not supported and will be interpreted as self-closing, closing tag will be ignored.
 
 ## Ideas
 

src/Shortcode.php

@@ -32,6 +32,26 @@ public function getParameters()
         return $this->parameters;
         }
 
+    public function hasParameter($name)
+        {
+        return array_key_exists($name, $this->parameters);
+        }
+
+    public function getParameter($name, $default = null)
+        {
+        if($this->hasParameter($name))
+            {
+            return $this->parameters[$name];
+            }
+        if(null !== $default)
+            {
+            return $default;
+            }
+
+        $msg = 'Shortcode parameter %s not found and no default value was set!';
+        throw new \RuntimeException(sprintf($msg, $name));
+        }
+
     public function getContent()
         {
         return $this->content;

tests/ShortcodeTest.php

@@ -17,7 +17,7 @@ final class ShortcodeTest extends \PHPUnit_Framework_TestCase
      *
      * @dataProvider provideShortcodes
      */
-    public function testObject($expected, $name, array $args, $content)
+    public function testShortcode($expected, $name, array $args, $content)
         {
         $s = new Shortcode($name, $args, $content);
         $textSerializer = new TextSerializer();
@@ -37,4 +37,26 @@ public function provideShortcodes()
             array('[x arg="val val"]inner[/x]', 'x', array('arg' => 'val val'), 'inner'),
             );
         }
+
+    public function testObject()
+        {
+        $shortcode = new Shortcode('random', array(
+            'arg' => 'value',
+            'none' => null,
+            ), 'something');
+
+        $this->assertTrue($shortcode->hasParameter('arg'));
+        $this->assertFalse($shortcode->hasParameter('invalid'));
+        $this->assertSame(null, $shortcode->getParameter('none'));
+        $this->assertSame('value', $shortcode->getParameter('arg'));
+        $this->assertSame('', $shortcode->getParameter('invalid', ''));
+        $this->assertSame(42, $shortcode->getParameter('invalid', 42));
+        }
+
+    public function testExceptionOnMissingParameterWithNoDefaultValue()
+        {
+        $shortcode = new Shortcode('name', array(), null);
+        $this->setExpectedException('RuntimeException');
+        $shortcode->getParameter('invalid');
+        }
     }