Merge branch 'release/0.2.0'

.travis.install

@@ -16,6 +16,7 @@ if ($token = getenv('ARCHER_TOKEN')) {
         'github.com' => $token
     );
     $composerFlags = '--prefer-dist';
+    passthru('curl -s -i -H "Authorization: token $ARCHER_TOKEN" https://api.github.com | grep "^X-RateLimit"');
 } else {
     $composerFlags = '--prefer-source';
 }

.travis.yml

@@ -8,10 +8,7 @@
 #
 language: php
 
-php:
-  - 5.3
-  - 5.4
-  - 5.5
+php: ["5.3", "5.4", "5.5"]
 
 env:
   global:
@@ -22,8 +19,3 @@ install:
   - ./.travis.install
 script:
   - ./vendor/bin/archer travis:build
-
-matrix:
-  # PHP 5.5 is still in alpha, so ignore build failures.
-  allow_failures:
-    - php: 5.5

CHANGELOG.md

@@ -1,5 +1,10 @@
 # Duct Changelog
 
-### 0.1.0
+### 0.2.0 (2013-07-08)
+
+* **[NEW]** Added `EventedParser`, a SAX-JS/Clarinet-like event-based JSON parser
+* **[BC]** Moved `Lexer` and `TokenStreamParser` into `Detail` namespace - these classes a no longer part of the public API
+
+### 0.1.0 (2013-05-02)
 
 * Initial release

README.md

@@ -1,18 +1,39 @@
 # Duct
 
-[![Build Status]](http://travis-ci.org/IcecaveStudios/duct)
-[![Test Coverage]](http://icecave.com.au/duct/artifacts/tests/coverage)
+[![Build Status]](https://travis-ci.org/IcecaveStudios/duct)
+[![Test Coverage]](https://coveralls.io/r/IcecaveStudios/duct?branch=develop)
+[![SemVer]](http://semver.org)
 
-**Duct** is a PHP library for parsing continuous streams of JSON values.
+**Duct** is a PHP library for incrementally parsing continuous streams of JSON values.
 
-## Installation
+**Duct** is designed to parse sequential JSON values from data streams, without framing or demarcation outside of the
+JSON specification.
 
-* [Composer](http://getcomposer.org) package [icecave/duct](https://packagist.org/packages/icecave/duct)
+* Install via [Composer](http://getcomposer.org) package [icecave/duct](https://packagist.org/packages/icecave/duct)
+* Read the [API documentation](http://icecavestudios.github.io/duct/artifacts/documentation/api/)
 
-## Example
+## Examples
+
+### Simple parsing
+
+**Duct** can be used to parse multiple JSON documents in a single call to `Parser::parse()`.
+The JSON string given must contain complete values.
+
+```php
+use Icecave\Duct\Parser;
+
+$parser = new Parser;
+$values = $parser->parse('[ 1, 2, 3 ] [ 4, 5, 6 ]');
+
+assert($values[0] === array(1, 2, 3));
+assert($values[1] === array(4, 5, 6));
+```
+
+### Incremental parsing
+
+Asynchronous, incremental parsing is also possible using the `Parser::feed()`, `values()` and `finalize()` methods.
 
 ```php
-<?php
 use Icecave\Duct\Parser;
 
 $parser = new Parser;
@@ -21,36 +42,58 @@ $parser = new Parser;
 $parser->feed('[ 1, ');
 
 // Completed values can be retreived using the values() method, which returns an
-// Icecave\Collections\Vector of values.
-//
-// At this point no complete object has been parsed so the vector is empty.
+// Icecave\Collections\Vector of values. At this point no complete object has
+// been parsed so the vector is empty.
 $values = $parser->values();
 assert($values->isEmpty());
 
 // As more data is fed to the parser, we now have one value available, an array
 // of elements 1, 2, 3.
-//
-// Note that calling values() is destructive, in that any complete objects are
-// removed from the parser and will not be returned by future calls to values().
 $parser->feed('2, 3 ][ 4, 5');
 $values = $parser->values();
 assert($values->size() === 1);
 assert($values[0] == array(1, 2, 3));
 
+// Note that calling values() is destructive, in that any complete objects are
+// removed from the parser and will not be returned by future calls to values().
+$values = $parser->values();
+assert($values->size() === 0);
+
 // Finally we feed the remaining part of the second object to the parser and the
 // second value becomes available.
 $parser->feed(', 6 ]');
 $values = $parser->values();
 assert($values->size() === 1);
 assert($values[0] == array(4, 5, 6));
+
+// At the end of the JSON stream, finalize is called to parse any data remaining
+// in the buffer. An exception is if thrown the buffer contains an incomplete
+// value.
+$parser->finalize();
+
+// In this case there were no additional values.
+$values = $parser->values();
+assert($values->isEmpty());
 ```
 
-## Notes
+### Event-based parsing
 
-Please note that **Duct** does not provide an evented (SAX-like) JSON parser, instead it allows incremental parsing of
-sequential JSON strings, for example when streaming JSON over a network connection.
+**Duct** also provides `EventedParser`, an event-based incremental parser similar to the [Clarinet](https://github.com/dscape/clarinet)
+library for JavaScript. Event management is provided by [Evenement](https://github.com/igorw/evenement/tree/v1.0.0), a
+popular PHP event library.
 
-<!-- references -->
-[Build Status]: https://raw.github.com/IcecaveStudios/duct/gh-pages/artifacts/images/icecave/regular/build-status.png
-[Test Coverage]: https://raw.github.com/IcecaveStudios/duct/gh-pages/artifacts/images/icecave/regular/coverage.png
+As per the example above the `feed()` and `finalize()` methods are used, however there is no `values()` method. Instead,
+the following events are emitted as the buffer is parsed.
+
+ * **array-open**: emitted when an array open bracket is encountered
+ * **array-close**: emitted when an array closing bracket is encountered
+ * **object-open**: emitted when an object open brace is encountered
+ * **object-close**: emitted when an object closing brace is encountered
+ * **object-key** (string $key): emitted when an object key is encountered
+ * **value** (mixed $value): emitted whenever a scalar or null is encountered, including inside objects and arrays
+ * **document** (mixed $value): emitted after an entire JSON document has been parsed
 
+<!-- references -->
+[Build Status]: https://travis-ci.org/IcecaveStudios/duct.png?branch=develop
+[Test Coverage]: https://coveralls.io/repos/IcecaveStudios/duct/badge.png?branch=develop
+[SemVer]: http://calm-shore-6115.herokuapp.com/?label=semver&value=0.2.0&color=yellow

composer.json

@@ -1,6 +1,6 @@
 {
     "name": "icecave/duct",
-    "description": "Parse continuous streams of JSON objects.",
+    "description": "An incremental streaming JSON parser.",
     "keywords": ["json", "parse", "parser", "stream"],
     "homepage": "https://github.com/IcecaveStudios/duct",
     "license": "MIT",
@@ -13,15 +13,24 @@
     "require": {
         "php": ">=5.3",
         "eloquent/enumeration": "~3",
-        "icecave/collections": "~0.6"
+        "icecave/collections": "~0.6",
+        "evenement/evenement": "~1"
     },
     "require-dev": {
-        "icecave/archer": "~0.3"
+        "eloquent/typhoon": "~0.9",
+        "icecave/archer": "1.0.0-alpha.1"
     },
     "autoload": {
         "psr-0": {
             "Icecave\\Duct": "lib",
             "Icecave\\Duct\\TypeCheck": "lib-typhoon"
         }
+    },
+    "extra": {
+        "typhoon": {
+            "output-path": "lib-typhoon",
+            "validator-namespace": "Icecave\\Duct\\TypeCheck",
+            "use-native-callable": false
+        }
     }
 }