Fix/cleanup

.gitignore

@@ -7,3 +7,4 @@
 # JIRA plugin
 atlassian-ide-plugin.xml
 
+config.json

README.md

@@ -1,18 +1,29 @@
-# PHP-Drafter
+# PHPDraft
 This is a parser for API Blueprint files in PHP.
 
 ## Usage
 For direct usage you can run:
 ```bash
-$ ./php-drafter.phar blueprint-file.apib > blueprint-webpage.html
+$ ./phpdraft.phar blueprint-file.apib > blueprint-webpage.html
 ```
 You can also install it first:
 ```bash
-$ cp php-drafter.phar /usr/bin/php-drafter
-$ chmod +x /usr/bin/php-drafter
-$ php-drafter blueprint-file.apib > blueprint-webpage.html
+$ cp phpdraft.phar /usr/bin/phpdraft
+$ chmod +x /usr/bin/phpdraft
+$ phpdraft blueprint-file.apib > blueprint-webpage.html
 ```
 
+## Including Files
+It is possible to include other files in your blueprint by using a special include directive with a path to the included file relative to the current file's directory. Included files can be written in API Blueprint, Markdown or HTML (or JSON for response examples). Included files can include other files, so be careful of circular references.
+
+```markdown
+<!-- include(filename.md) -->
+```
+
+For tools that do not support this include directive it will just render out as an HTML comment. API Blueprint may support its own mechanism of including files in the future, and this syntax was chosen to not interfere with the [external documents proposal](https://github.com/apiaryio/api-blueprint/issues/20) while allowing `PHPDraft` users to include documents today.
+
+_Thanks to [aglio](https://github.com/danielgtaylor/aglio) for the idea._
+
 ## Writing API documentation
 
 For writing API documentation using [API Blueprint](http://apiblueprint.org/) syntax. You can read about its [specification](https://github.com/apiaryio/api-blueprint/blob/master/API%20Blueprint%20Specification.md).
@@ -65,7 +76,7 @@ Return the information for the Person
 
 
 ## Dependencies
-PHP-Drafter requires [drafter](https://github.com/apiaryio/drafter) to be installed. Refer to the drafter page for the installation details.
+PHPDraft requires [drafter](https://github.com/apiaryio/drafter) to be installed. Refer to the drafter page for the installation details.
 
 ## Libraries
 This app usage the following libraries:

config.json

@@ -1,3 +1,4 @@
 {
-  "tmpdir": "/tmp/drafter"
+  "tmpdir": "/tmp/drafter",
+  "logo": "/home/smillernl/Documents/5acf473a9e6a3deb8e98a2b6373d0a83.png"
 }

config.json.sample

@@ -0,0 +1,4 @@
+{
+  "tmpdir": "/tmp/drafter",
+  "logo": "/path/to/some/logo.png"
+}

index.php

@@ -1,13 +1,27 @@
 <?php
+/**
+ * Set up include path for source handling
+ */
 set_include_path(get_include_path().":".__DIR__.'/src/');
 $config = json_decode(file_get_contents(__DIR__."/config.json"));
+
+/**
+ * Set up required classes (with the autoloader)
+ */
 require_once 'PHPDraft/Core/Autoloader.php';
 use PHPDraft\In\ApibFileParser;
 use PHPDraft\Parse\ApibToJson;
 use PHPDraft\Parse\JsonToHTML;
+
+if($argc < 1)
+{
+    file_put_contents('php://stderr', "Missing file to parse\n");
+    exit(2);
+}
+
 $apib = new ApibFileParser($argv[1]);
 $json = new ApibToJson($apib);
 $json->parseToJson();
 $html = new JsonToHTML($json);
-echo $html->get_html();
+$html->get_html();
 ?>

src/PHPDraft/In/ApibFileParser.php

@@ -10,8 +10,16 @@
 
 class ApibFileParser
 {
-    protected $out_string;
+    /**
+     * Complete API Blueprint
+     * @var string
+     */
+    protected $full_apib;
 
+    /**
+     * Location of the API Blueprint to parse
+     * @var string
+     */
     protected $location;
 
     /**
@@ -21,8 +29,8 @@ class ApibFileParser
      */
     public function __construct($filename = 'index.apib')
     {
-        $this->location   = pathinfo($filename, PATHINFO_DIRNAME) . '/';
-        $this->out_string = $this->get_apib($filename);
+        $this->location  = pathinfo($filename, PATHINFO_DIRNAME) . '/';
+        $this->full_apib = $this->get_apib($filename);
     }
 
     /**
@@ -52,7 +60,7 @@ function get_apib($filename)
      */
     function __toString()
     {
-        return $this->out_string;
+        return $this->full_apib;
     }
 
 }

src/PHPDraft/Model/APIBlueprintElement.php

@@ -41,7 +41,7 @@ abstract class APIBlueprintElement
     protected $parent = NULL;
 
     /**
-     * Parse an object to an element
+     * Parse a JSON object to an element
      *
      * @param \stdClass $object an object to parse
      *

src/PHPDraft/Model/Category.php

@@ -2,7 +2,7 @@
 /**
  * This file contains the Category.php
  *
- * @package php-drafter\SOMETHING
+ * @package PHPDraft\Model
  * @author  Sean Molenaar<sean@seanmolenaar.eu>
  */
 
@@ -17,25 +17,11 @@ class Category extends APIBlueprintElement
     public $structures = [];
 
     /**
-     * Add a struct dependency
+     * Fill class values based on JSON object
      *
-     * @param string $object Name of the struct to add
+     * @param \stdClass $object JSON object
      *
-     * @internal param string $name Name of the type
-     */
-    public function add_struct($object)
-    {
-        echo "<pre>";
-        var_dump($object);
-        echo "</pre>";
-    }
-
-    /**
-     * Parse the category
-     *
-     * @param \stdClass $object
-     *
-     * @return $this
+     * @return $this self-reference
      */
     function parse($object)
     {

src/PHPDraft/Model/DataStructureElement.php

@@ -2,7 +2,7 @@
 /**
  * This file contains the DataStructureElement.php
  *
- * @package php-drafter\SOMETHING
+ * @package PHPDraft\Model
  * @author  Sean Molenaar<sean@seanmolenaar.eu>
  */
 
@@ -15,26 +15,31 @@ class DataStructureElement
      * @var string
      */
     public $key;
+
     /**
      * Object JSON type
      * @var string
      */
     public $type;
+
     /**
      * Object description
      * @var string
      */
     public $description;
+
     /**
      * Type of element
      * @var string
      */
     public $element = NULL;
+
     /**
      * Object value
      * @var mixed|DataStructureElement[]
      */
     public $value = NULL;
+
     /**
      * Object status (required|optional)
      * @var string
@@ -48,7 +53,7 @@ class DataStructureElement
     public $deps;
 
     /**
-     * Unreported datatypes
+     * Default datatypes
      * @var array
      */
     protected $defaults = ['boolean', 'string', 'number', 'object', 'array'];

src/PHPDraft/Model/RequestBodyElement.php → src/PHPDraft/Model/Elements/RequestBodyElement.php

@@ -6,8 +6,9 @@
  * @author  Sean Molenaar<sean@seanmolenaar.eu>
  */
 
-namespace PHPDraft\Model;
+namespace PHPDraft\Model\Elements;
 
+use PHPDraft\Model\DataStructureElement;
 
 class RequestBodyElement extends DataStructureElement
 {
@@ -62,6 +63,13 @@ public function parse($object, &$dependencies)
         return $this;
     }
 
+    /**
+     * Print the request body as a string
+     *
+     * @param string $type The type of request
+     *
+     * @return string Request body
+     */
     public function print_request($type = 'application/x-www-form-urlencoded')
     {
         if (is_array($this->value))

src/PHPDraft/Model/HTTPRequest.php

@@ -8,6 +8,8 @@
 
 namespace PHPDraft\Model;
 
+use PHPDraft\Model\Elements\RequestBodyElement;
+
 class HTTPRequest
 {
     /**
@@ -32,14 +34,25 @@ class HTTPRequest
      * Body of the request (if POST or PUT)
      * @var RequestBodyElement[]
      */
-    public $body;
+    public $body = [];
 
+    /**
+     * HTTPRequest constructor.
+     *
+     * @param Transition $parent Parent entity
+     */
     public function __construct(&$parent)
     {
         $this->parent = &$parent;
-        //TODO: Parse body
     }
 
+    /**
+     * Fill class values based on JSON object
+     *
+     * @param \stdClass $object JSON object
+     *
+     * @return $this self-reference
+     */
     public function parse($object)
     {
         $this->method = $object->attributes->method;
@@ -67,6 +80,11 @@ public function parse($object)
         return $this;
     }
 
+    /**
+     * Parse the objects into a request body
+     *
+     * @param \stdClass[] $objects JSON objects
+     */
     private function parse_structure($objects)
     {
         foreach ($objects as $object)
@@ -80,6 +98,13 @@ private function parse_structure($objects)
         }
     }
 
+    /**
+     * Generate a cURL command for the HTTP request
+     *
+     * @param string $base_url URL to the base server
+     *
+     * @return string An executable cURL command
+     */
     public function get_curl_command($base_url)
     {
         $options = [];
@@ -96,7 +121,7 @@ public function get_curl_command($base_url)
             $options[] = '-H "'.$header.': '.$value. '"';
         }
         $options[] = '-v';
-        return htmlspecialchars('curl '.join(' ', $options). ' "'.$base_url.$this->parent->build_url().'"');
+        return htmlspecialchars('curl '.join(' ', $options). ' "'.$this->parent->build_url($base_url).'"');
     }
 
 

src/PHPDraft/Model/HTTPResponse.php

@@ -11,7 +11,7 @@
 class HTTPResponse
 {
     /**
-     * Description
+     * HTTP Status code
      * @var int
      */
     public $statuscode;
@@ -45,6 +45,13 @@ public function __construct($parent)
         $this->parent = &$parent;
     }
 
+    /**
+     * Fill class values based on JSON object
+     *
+     * @param \stdClass $object JSON object
+     *
+     * @return $this self-reference
+     */
     public function parse($object)
     {
         $this->statuscode = intval($object->attributes->statusCode);

src/PHPDraft/Model/Resource.php

@@ -2,7 +2,7 @@
 /**
  * This file contains the Resource.php
  *
- * @package php-drafter\SOMETHING
+ * @package PHPDraft\Model
  * @author Sean Molenaar<sean@seanmolenaar.eu>
  */
 
@@ -27,6 +27,13 @@ public function __construct(&$parent)
         $this->parent = $parent;
     }
 
+    /**
+     * Fill class values based on JSON object
+     *
+     * @param \stdClass $object JSON object
+     *
+     * @return $this self-reference
+     */
     function parse($object)
     {
         parent::parse($object);
@@ -37,7 +44,7 @@ function parse($object)
         {
             if ($item->element === 'copy') continue;
             $transition = new Transition($this);
-            array_push($this->children, $transition->parse($item));
+            $this->children[] = $transition->parse($item);
         }
 
         return $this;