Merge pull request #1 from hendrikmaus/drafter-refract-release

[BC] Switch to drafter v1.0.0

README.md

@@ -1,28 +1,25 @@
 # Drafter PHP Binding
-PHP wrapper for [Drafter](https://github.com/apiaryio/drafter) API Blueprint Parser **v0.1.9**.
+PHP wrapper for [Drafter](https://github.com/apiaryio/drafter) API Blueprint Parser harness **v1.x**.
 
 [![Minimum PHP Version](https://img.shields.io/badge/php-%3E%3D%205.4-8892BF.svg)](https://php.net/)
 [![Build Status](https://travis-ci.org/hendrikmaus/drafter-php.svg?branch=master)](https://travis-ci.org/hendrikmaus/drafter-php)
 [![codecov.io](http://codecov.io/github/hendrikmaus/drafter-php/coverage.svg?branch=master)](http://codecov.io/github/hendrikmaus/drafter-php?branch=master)
 [![Dependency Status](https://www.versioneye.com/user/projects/55e7ed98211c6b00190007d2/badge.svg?style=flat)](https://www.versioneye.com/user/projects/55e7ed98211c6b00190007d2) 
 [![Code Climate](https://img.shields.io/codeclimate/github/kabisaict/flow.svg)](https://codeclimate.com/github/hendrikmaus/drafter-php)
 
-> This project hasn't reached v1.0.0 yet; the API is subject to change.
-> There will be upgrade guides for all future changes.
-
 ## What is Drafter-php?
-Drafter-php allows you to use use the [drafter](https://github.com/apiaryio/drafter) API Blueprint Parser
+Drafter-php allows you to use use the [drafter](https://github.com/apiaryio/drafter) API Blueprint Parser harness
 with your PHP application.
 
 In a nutshell: you can convert [API Blueprint](http://apiblueprint.org/) files to 
-Abstract Syntax Trees in JSON or YAML format.
+[refract] Abstract Syntax Trees in JSON or YAML format.
 
 [API Blueprint](http://apiblueprint.org/) is a webservice documentation language built on top of 
 [Markdown](https://en.wikipedia.org/wiki/Markdown).
 
 ## Requirements
 * PHP 5.4 or greater
-* Drafter v0.1.9 [command line tool](https://github.com/apiaryio/drafter#drafter-command-line-tool)
+* Drafter v1.x [command line tool](https://github.com/apiaryio/drafter#drafter-command-line-tool)
 
 ## What Is What
 **Drafter** is a C++ tool to parse API Blueprint.  
@@ -48,7 +45,7 @@ If you do not already have, add a `scripts` section to your root composer.json:
 "scripts": {
     "post-install-cmd": [
         "if ! [[ -d ext/drafter ]]; then echo \"### Installing drafter to ./ext; drafter bin to ./vendor/bin/ ###\"; fi",
-        "if ! [[ -d ext/drafter ]]; then git clone --branch v0.1.9 --recursive https://github.com/apiaryio/drafter.git ext/drafter; fi",
+        "if ! [[ -d ext/drafter ]]; then git clone --branch v1.0.0 --recursive https://github.com/apiaryio/drafter.git ext/drafter; fi",
         "if ! [[ -d vendor/bin ]]; then mkdir -p vendor/bin; fi",
         "if ! [[ -f vendor/bin/drafter ]]; then cd ext/drafter && ./configure && make drafter; fi",
         "if ! [[ -f vendor/bin/drafter ]]; then cd vendor/bin && ln -s ../../ext/drafter/bin/drafter drafter; fi"
@@ -87,11 +84,107 @@ Given this api blueprint source:
         Hello World!
 ```
 
-This abstract syntax tree will be the result (json format):
+This refract element will be the result (json format):
 
 ```json
 {
-  "_version": "3.0",
+  "element": "category",
+  "meta": {
+    "classes": [
+      "api"
+    ],
+    "title": ""
+  },
+  "content": [
+    {
+      "element": "category",
+      "meta": {
+        "classes": [
+          "resourceGroup"
+        ],
+        "title": ""
+      },
+      "content": [
+        {
+          "element": "resource",
+          "meta": {
+            "title": ""
+          },
+          "attributes": {
+            "href": "/message"
+          },
+          "content": [
+            {
+              "element": "transition",
+              "meta": {
+                "title": ""
+              },
+              "content": [
+                {
+                  "element": "httpTransaction",
+                  "content": [
+                    {
+                      "element": "httpRequest",
+                      "attributes": {
+                        "method": "GET"
+                      },
+                      "content": []
+                    },
+                    {
+                      "element": "httpResponse",
+                      "attributes": {
+                        "statusCode": "200",
+                        "headers": {
+                          "element": "httpHeaders",
+                          "content": [
+                            {
+                              "element": "member",
+                              "content": {
+                                "key": {
+                                  "element": "string",
+                                  "content": "Content-Type"
+                                },
+                                "value": {
+                                  "element": "string",
+                                  "content": "text/plain"
+                                }
+                              }
+                            }
+                          ]
+                        }
+                      },
+                      "content": [
+                        {
+                          "element": "asset",
+                          "meta": {
+                            "classes": "messageBody"
+                          },
+                          "attributes": {
+                            "contentType": "text/plain"
+                          },
+                          "content": "Hello World!\n"
+                        }
+                      ]
+                    }
+                  ]
+                }
+              ]
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}
+```
+
+Setting the type option to 'ast', results in this abstract syntax tree:
+
+> type 'refract' is the default since since drafter v1.0.0
+
+```json
+{
+  "_version": "4.0",
   "metadata": [],
   "name": "",
   "description": "",
@@ -233,13 +326,25 @@ $version = $drafter
 // Reset options on the command
 $drafter->resetOptions();
 ```
-`$version` should now contain a string like `v0.1.9`.
+`$version` should now contain a string like `v1.0.0`.
  If something is wrong, an exception will have been thrown most likely.
 
  > Keep in mind that Drafter-php is designed to keep its state,
  > run `\DrafterPhp\DrafterInterface::resetOptions` to get rid of the version option you just set
  > for the next call on the instance.
 
+#### Parse your-service.apib into your-service.refract.json
+Make sure your input path is correct and readable, and your output path is writable.
+
+```php
+$drafter
+    ->input('your-service.apib')
+    ->format('json')
+    ->type('refract')
+    ->output('your-service.refract.json')
+    ->run();
+```
+
 #### Parse your-service.apib into your-service.ast.json
 Make sure your input path is correct and readable, and your output path is writable.
 
@@ -254,13 +359,13 @@ $drafter
 #### Parse your-service.apib into a PHP data structure
 
 ```php
-$ast = $drafter
+$refract = $drafter
     ->input('your-service.apib')
     ->format('json')
     ->run();
     
-$phpObj = json_decode($ast);
-$phpArr = json_decode($ast, true);
+$phpObj = json_decode($refract);
+$phpArr = json_decode($refract, true);
 ```
 
 #### Parse your-service.apib into YAML format
@@ -279,7 +384,7 @@ $drafter
 $process = $drafter
     ->input('your-service.apib')
     ->format('json')
-    ->output('your-service.ast.json')
+    ->output('your-service.refract.json')
     ->build();
 
 // do stuff with the process
@@ -291,7 +396,7 @@ $drafter
 ## Feature Roadmap
 Do not hesitate to [contribute](https://github.com/hendrikmaus/drafter-php/blob/master/CONTRIBUTING.md).
 
-* [] support passing raw api blueprint code into `\DrafterPhp\DrafterInterface::input`, rather than always a file path
+* [ ] support passing raw api blueprint code into `\DrafterPhp\DrafterInterface::input`, rather than always a file path
 
 ## License
 Drafter-php is licensed under the MIT License - see the 

composer.json

@@ -32,7 +32,7 @@
         "clean": "rm -rf vendor/ ext/ composer.lock",
         "post-install-cmd": [
             "if ! [[ -d ext/drafter ]]; then echo \"### Installing drafter to ./ext; drafter bin to ./vendor/bin/ ###\"; fi",
-            "if ! [[ -d ext/drafter ]]; then git clone --branch v0.1.9 --recursive https://github.com/apiaryio/drafter.git ext/drafter; fi",
+            "if ! [[ -d ext/drafter ]]; then git clone --branch v1.0.0 --recursive https://github.com/apiaryio/drafter.git ext/drafter; fi",
             "if ! [[ -d vendor/bin ]]; then mkdir -p vendor/bin; fi",
             "if ! [[ -f vendor/bin/drafter ]]; then cd ext/drafter && ./configure && make drafter; fi",
             "if ! [[ -f vendor/bin/drafter ]]; then cd vendor/bin && ln -s ../../ext/drafter/bin/drafter drafter; fi"

src/Drafter.php

@@ -29,7 +29,8 @@
  *
  * options:
  * -o, --output          save output AST into file (string [=])
- * -f, --format          output AST format (string [=yaml])
+ * -f, --format          output format of the AST (yaml|json) (string [=yaml])
+ * -t, --type            type of the AST (refract|ast) (string [=refract])
  * -s, --sourcemap       export sourcemap AST into file (string [=])
  * -h, --help            display this help message
  * -v, --version         print Drafter version
@@ -108,6 +109,13 @@ public function format($format)
         return $this;
     }
 
+    public function type($type)
+    {
+        $this->options['--type'] = $type;
+
+        return $this;
+    }
+
     public function sourcemap($path)
     {
         $this->options['--sourcemap'] = $path;

src/DrafterInterface.php

@@ -50,6 +50,21 @@ public function output($path);
      */
     public function format($format);
 
+    /**
+     * Set type option.
+     *
+     * Available types:
+     *   * refract (default)
+     *   * ast
+     *
+     * Help:
+     *   -t, --type            type of the AST (refract|ast) (string [=refract])
+     *
+     * @param string $type type to retrieve, e.g. refract or ast
+     * @return $this
+     */
+    public function type($type);
+
     /**
      * Set sourcemap argument.
      *

tests/DrafterTest.php

@@ -79,18 +79,18 @@ public function testGetVersion()
         $version = trim($version);
 
         // Assert the fixed version of drafter that this package currently supports
-        $this->assertEquals('v0.1.9', $version);
-        $this->assertRegExp('/v\d+\.\d+\.\d+/', $version);
+        $this->assertRegExp('/v1\.\d+\.\d+/', $version);
     }
 
     /**
      * Parse a simple example to json ast.
      */
-    public function testParseSimplestExampleToJson()
+    public function testParseSimplestAstExampleToJson()
     {
         $result = $this
             ->drafter
             ->input($this->fixturePath . 'simplest-example.apib')
+            ->type('ast')
             ->format('json')
             ->run();
 
@@ -103,11 +103,32 @@ public function testParseSimplestExampleToJson()
         return $this->drafter;
     }
 
+    /**
+     * Parse a simple example to json ast.
+     */
+    public function testParseSimplestRefractExampleToJson()
+    {
+        $result = $this
+            ->drafter
+            ->input($this->fixturePath . 'simplest-example.apib')
+            ->type('refract')
+            ->format('json')
+            ->run();
+
+        $this->assertNotNull($result);
+        $this->assertJsonStringEqualsJsonFile(
+            $this->fixturePath . 'simplest-example-refract.json',
+            $result
+        );
+
+        return $this->drafter;
+    }
+
     /**
      * The drafter instance will hold its state; we can invoke `run` again for the same result.
      *
      * @param Drafter $drafter
-     * @depends testParseSimplestExampleToJson
+     * @depends testParseSimplestAstExampleToJson
      */
     public function testRunningDrafterAgainWithoutReset(Drafter $drafter)
     {
@@ -126,6 +147,7 @@ public function testBuildProcessAndPassItToRunMethod()
             ->drafter
             ->input($this->fixturePath . 'simplest-example.apib')
             ->format('json')
+            ->type('ast')
             ->build();
 
         $this->assertInstanceOf('\Symfony\Component\Process\Process', $process);
@@ -149,6 +171,7 @@ public function testTurnDrafterResultIntoPhpDataStructure()
             ->drafter
             ->input($this->fixturePath . 'simplest-example.apib')
             ->format('json')
+            ->type('ast')
             ->run();
 
         $astFixture = file_get_contents($this->fixturePath . 'simplest-example-ast.json');

tests/fixtures/simplest-example-ast.json

@@ -1,5 +1,5 @@
 {
-  "_version": "3.0",
+  "_version": "4.0",
   "metadata": [
     {
       "name": "FORMAT",