Merge pull request #68 from afk11/README-and-examples

build examples as part of tests, don't want them going stale

Author: afk11

.travis.yml

@@ -18,6 +18,7 @@ script:
   - php vendor/bin/phpunit
   - vendor/bin/phpstan analyze -l 4 src tests examples
   - php vendor/bin/phpcs -n --standard=PSR1,PSR2 --report=full src/ tests/ examples/
+  - ./validate_examples.sh
 
 after_success:
   - wget https://scrutinizer-ci.com/ocular.phar

README.md

@@ -23,83 +23,26 @@ This library provides a `Buffer` and `Parser` class to make dealing with binary
 ## Examples 
 
  Buffer's are immutable classes to store binary data. 
- BufferHex will convert the provided data to binary, as will BufferInt. 
+ Buffer::hex can be used to initialize from hex
+ Buffer::int can be used to initialize from a positive decimal integer (int|string)
+   
  Buffer's main methods are:
   - getBinary()
   - getHex()
   - getInt()
-  
+
  Parser will read Buffers. 
  Parser's main methods are: 
   - readBytes()
-  - getArray()
-  - getVarInt()
-  - getString()
   - writeBytes()
+  - readArray()
+  - writeArray()
 
  In most cases, the interface offered by Parser should not be used directly. 
  Instead, Templates expose read/write access to larger serialized structures.
 
- ### Using Parser to read binary data:
-```php
-    use BitWasp\Buffertools\Buffer;
-    use BitWasp\Buffertools\Parser;
-    
-    // Parsers read Buffers
-    $buffer = new Buffer('abc');
-    $parser = new Parser($buffer);
-    
-    // Call readBytes to unpack the data
-    /** @var Buffer[] $set */
-    $set = [
-        $parser->readBytes(1),
-        $parser->readBytes(1),
-        $parser->readBytes(1)
-    ];
-    
-    foreach ($set as $item) {
-        echo $item->getBinary() . PHP_EOL;
-    }
-```
-
-### Using Templates
-```php
-    
-use BitWasp\Buffertools\Buffer;
-use BitWasp\Buffertools\Parser;
-use BitWasp\Buffertools\TemplateFactory;
-
-$structure = (object) [
-    'hash' => hash('sha256', 'abc'),
-    'message_id' => 9123,
-    'message' => "Hi there! What's up?"
-];
-
-// Templates are read/write
-$template = (new TemplateFactory)
-    ->bytestring(32)
-    ->uint32()
-    ->varstring()
-    ->getTemplate();
-
-// Write the structure
-$binary = $template->write([
-    Buffer::hex($structure->hash),
-    $structure->message_id,
-    new Buffer($structure->message)
-]);
-
-echo $binary->getHex() . "\n";
-
-// Use the template to read resulting Buffer
-$parsed = $template->parse(new Parser($binary));
-
-$p = (object) [
-    'hash' => $parsed[0]->getHex(),
-    'message_id' => $parsed[1],
-    'message' => $parsed[2]->getBinary()
-];
-
-print_r($p);
-```
-
+ - [Example 1: Using buffer to wrap binary data](./examples/usingBuffer.php) 
+ - [Example 2: Using parser to extract binary data](./examples/usingParser.php) 
+ - [Example 3: Using templates to read multiple elements from a parser](./examples/usingTemplates.php) 
+ - [Example 4: Using templates to read/write structured messages](./examples/usingTemplates2.php) 
+  

examples/usingBuffer.php

@@ -1,21 +1,26 @@
 <?php
 
-require "../vendor/autoload.php";
+require __DIR__ . "/../vendor/autoload.php";
 
 use BitWasp\Buffertools\Buffer;
 
 // Binary data and ASCII can be passed directly to a Buffer
 $binary = new Buffer('hello world');
-echo $binary->getBinary() . PHP_EOL;
-echo $binary->getHex() . PHP_EOL;
+echo "Buffer 1: binary  : " . $binary->getBinary() . PHP_EOL;
+echo "Buffer 1: hex     : " . $binary->getHex() . PHP_EOL;
+echo PHP_EOL;
 
-// BufferHex and BufferInt convert data to binary
+// Buffer::hex and Buffer::int convert data to binary
 $hex = Buffer::hex('68656c6c6f20776f726c64');
-echo $binary->getBinary() . PHP_EOL;
-echo $hex->getHex() . PHP_EOL;
+echo "Buffer 2: binary  : " . $hex->getBinary() . PHP_EOL;
+echo "Buffer 2: hex     : " . $hex->getHex() . PHP_EOL;
+$first = $hex->slice(0, 1);
+echo "Buffer 2: 1st char: " . $first->getHex() . PHP_EOL;
+echo PHP_EOL;
 
 // All Buffers expose getBinary(), getInt(), getHex()
 $int = Buffer::int(65);
-echo $int->getBinary() . PHP_EOL;
-echo $int->getInt() . PHP_EOL;
-echo $int->getHex() . PHP_EOL;
+echo "Buffer 3: binary: " . $int->getBinary() . PHP_EOL;
+echo "Buffer 3: int   : " . $int->getInt() . PHP_EOL;
+echo "Buffer 3: hex   : " . $int->getHex() . PHP_EOL;
+echo PHP_EOL;

examples/usingParser.php

@@ -1,12 +1,12 @@
 <?php
 
-require "../vendor/autoload.php";
+require __DIR__ . "/../vendor/autoload.php";
 
 use BitWasp\Buffertools\Buffer;
 use BitWasp\Buffertools\Parser;
 
 // Parsers read Buffers
-$buffer = new Buffer('abc');
+$buffer = new Buffer('abcd01020304');
 $parser = new Parser($buffer);
 
 // Call readBytes to unpack the data
@@ -15,7 +15,8 @@
 $set = [
     $parser->readBytes(1),
     $parser->readBytes(1),
-    $parser->readBytes(1)
+    $parser->readBytes(1),
+    $parser->readBytes(4)
 ];
 
 foreach ($set as $item) {

examples/usingTemplates.php

@@ -1,6 +1,6 @@
 <?php
 
-require "../vendor/autoload.php";
+require __DIR__ . "/../vendor/autoload.php";
 
 use BitWasp\Buffertools\Buffer;
 use BitWasp\Buffertools\Parser;

examples/usingTemplates2.php

@@ -1,6 +1,6 @@
 <?php
 
-require "../vendor/autoload.php";
+require __DIR__ . "/../vendor/autoload.php";
 
 use BitWasp\Buffertools\Buffer;
 use BitWasp\Buffertools\Parser;

validate_examples.sh

@@ -0,0 +1,8 @@
+#!/bin/bash
+for i in examples/*.php; do
+    php $i > /dev/null
+    if [ $? -ne 0 ]; then
+        echo "Error running example code: $i";
+        exit -1
+    fi;
+done