Supports the special syntax '@<attribute>' and '@'.

Used for setting attributes and text content when adding elements using an array. * [~] ->appendChild() supports '@<attribute>' and '@' special syntax. * [~] ->appendSibling() supports '@<attribute>' and '@' special syntax. * [~] ->prependSibling() supports '@<attribute>' and '@' special syntax.
servo-php · Jan 7, 2016 · fec6991 · fec6991
1 parent b73bd75
commit fec6991
Show file tree

Hide file tree

Showing 8 changed files with 177 additions and 103 deletions.
diff --git a/documents/APIs.md b/documents/APIs.md
@@ -62,6 +62,8 @@ __construct($root?, array $options?);
 
 ->length();     // Available after a query or a node insertion with context switch.
 
+->dom();
+
 ->xml($strip = false);
 ```
 

diff --git a/documents/Changelog.txt b/documents/Changelog.txt
@@ -1,7 +1,16 @@
 [+]: new   [~]: changed   [-]: removed   [#]: fixed   [@]: internal
 
 
-1.10: (2016-01-06)
+1.11: (2016-01-07)
+supports the special syntax '@<attribute>' and '@' for setting attributes and
+text content when adding elements using an array.
+
+    * [~] ->appendChild() supports '@<attribute>' and '@' special syntax.
+    * [~] ->appendSibling() supports '@<attribute>' and '@' special syntax.
+    * [~] ->prependSibling() supports '@<attribute>' and '@' special syntax.
+
+
+1.10:
 introduces the '->each()' method and the '->setCdata()'/'->cdata()' twins
 methods together with an internal refactoring.
 

diff --git a/documents/Examples.php b/documents/Examples.php
@@ -102,18 +102,16 @@
 $food->add([ ['egg'], ['egg'], ['egg'] ], ['price' => '0.25']);
 
 // Complex array structures are supported too.
-$food->add([ 'fridge' => [
-                 'firstFloor' => [
-                     'omelette' => 'with potato' ],
-                 'secondFloor' => [
-                     'soupe' => 'with mashrooms' ]
-             ],
-             'freezer' => [
-                 'firstFloor' => [
-                     'meat' => 'beef' ],
-                 'secondFloor' => [
-                     'fish' => 'tuna' ],
-             ] ]);
+$food->add([ 'menu' => [
+                 'pasta' => [
+                     'spaghetti' => [
+                         '@id'      => '123',
+                         '@country' => 'Italy',
+                         '@'        => 'Spaghetti are an Italian dish...',
+
+                         'variants' => [
+                             'tomato' => [ '@type' => 'vegan' ],
+                             'egg'    => [ '@type' => 'vegetarian' ] ]]]]]);
 
 echo $food->xml();
 echo "————————————————————————————————————————————————————————————————————————————————\n";

diff --git a/documents/Getting-Started.md b/documents/Getting-Started.md
@@ -239,69 +239,71 @@ of a node contextually to its creation.
 
 > Extended syntax
 > ```php
-> $food->appendChild('fruit', 'apple', [ 'price' => 'expensive',
->                                        'color' => 'red' ]);
->
-> // which is identical to
->
+> $food->appendChild('fruit', 'apple', ['color' => 'red']);
+> ```
+> Concise syntax
+> ```php
+> $food->add('fruit', 'apple', ['color' => 'red']);
+> ```
+
+Which is identical to
+
+> Extended syntax
+> ```php
 > $food->appendChild('fruit', 'apple', true)        // Remember, passing 'true' returns the created node.
->          ->setAttribute([ 'price' => 'expensive',
->                           'color' => 'red' ]);
->
-> // The advantage comes when multiple nodes have the same attributes.
->
-> // A bunch of eggs all with the same price.
-> $food->appendChild([ ['egg'], ['egg'], ['egg'] ], ['price' => '0.25']);
+>          ->setAttribute([ 'color' => 'red' ]);
 > ```
 > Concise syntax
 > ```php
-> $food->add('fruit', 'apple', [ 'price'=> 'expensive',
->                                'color' => 'red' ]);
->
-> // which is identical to
->
 > $food->add('fruit', 'apple', true)        // Remember, passing 'true' returns the created node.
->          ->attr([ 'price' => 'expensive',
->                   'color' => 'red' ]);
+>          ->attr([ 'color' => 'red' ]);
+> ```
+
+The advantage comes when multiple nodes have the same attributes.
+
+> Extended syntax
+> ```php
+> $food->appendChild([ ['egg'], ['egg'] ], ['price' => '0.25']);
 >
-> // The advantage comes when multiple nodes have the same attributes.
+> // A bunch of eggs all with the same price.
+> ```
+> Concise syntax
+> ```php
+> $food->add([ ['egg'], ['egg'] ], ['price' => '0.25']);
 >
 > // A bunch of eggs all with the same price.
-> $food->add([ ['egg'], ['egg'], ['egg'] ], ['price' => '0.25']);
 > ```
 
-Creating arbitrarily complex structures is possible too nesting arrays.
+Creating arbitrarily complex structures is possible too nesting arrays and using<br/>
+the `@` special syntax. An array key starting with an '@' is interpreted as an attribute<br/>
+identifier and an array key equel to '@' is interpreted as the text content.
 
 > Extended syntax
 > ```php
-> $food->appendChild([ 'fridge' => [
->                          'firstFloor' => [
->                              'omelette' => 'with potato' ],
->                          'secondFloor' => [
->                              'soupe' => 'with mashrooms' ]
->                      ],
->                      'freezer' => [
->                          'firstFloor' => [
->                              'meat' => 'beef' ],
->                          'secondFloor' => [
->                              'fish' => 'tuna' ],
->                      ] ]);
+> $food->appendChild([ 'menu' => [
+>                         'pasta' => [
+>                             'spaghetti' => [
+>                                 '@id'      => '123',
+>                                 '@country' => 'Italy',
+>                                 '@'        => 'Spaghetti are an Italian dish...',
+>
+>                                 'variants' => [
+>                                     'tomato' => [ '@type' => 'vegan' ],
+>                                     'egg'    => [ '@type' => 'vegetarian' ] ]]]]]);
 > ```
 > Concise syntax
 > ```php
-> $food->add([ 'fridge' => [
->                  'firstFloor' => [
->                      'omelette' => 'with potato' ],
->                  'secondFloor' => [
->                      'soupe' => 'with mashrooms' ]
->              ],
->              'freezer' => [
->                  'firstFloor' => [
->                      'meat' => 'beef' ],
->                  'secondFloor' => [
->                      'fish' => 'tuna' ],
->              ] ]);
-> ```
+> $food->add([ 'menu' => [
+>                  'pasta' => [
+>                      'spaghetti' => [
+>                          '@id'      => '123',
+>                          '@country' => 'Italy',
+>                          '@'        => 'Spaghetti are an Italian dish...',
+>
+>                          'variants' => [
+>                              'tomato' => [ '@type' => 'vegan' ],
+>                              'egg'    => [ '@type' => 'vegetarian' ] ]]]]]);
+```
 
 ```php
 echo $food->xml();
@@ -312,30 +314,24 @@ echo $food->xml();
 <food>
   <fruit/>
   <fruit>orange</fruit>
-  <fruit price="expensive" color="red">apple</fruit>
   <cake>Tiramisu</cake>
   <pizza>Margherita</pizza>
   <pasta>Carbonara</pasta>
   <pasta>Matriciana</pasta>
+  <fruit color="red">apple</fruit>
   <egg price="0.25"/>
   <egg price="0.25"/>
-  <egg price="0.25"/>
-  <fridge>
-    <firstFloor>
-      <omelette>with potato</omelette>
-    </firstFloor>
-    <secondFloor>
-      <soupe>with mashrooms</soupe>
-    </secondFloor>
-  </fridge>
-  <freezer>
-    <firstFloor>
-      <meat>beef</meat>
-    </firstFloor>
-    <secondFloor>
-      <fish>tuna</fish>
-    </secondFloor>
-  </freezer>
+  <menu>
+      <pasta>
+        <spaghetti id="123" country="Italy">
+            Spaghetti are an Italian dish...
+            <variants>
+                <tomato type="vegan"/>
+                <egg type="vegetarian"/>
+            </variants>
+        </spaghetti>
+      </pasta>
+    </menu>
 </food>
 ```
 
@@ -399,7 +395,13 @@ flexibility.
 
 ## Exporting The Document
 
-The document can be exported as XML string.
+The document can be exported as `DOMDocument`.
+
+```php
+$dom = $book->dom();
+```
+
+Or as XML string.
 
 ```php
 $xml = $book->xml();

diff --git a/documents/ReadMe.md b/documents/ReadMe.md
@@ -17,7 +17,12 @@
 [![Donate][donate-button]][donate-link] [![Build Status][travis-badge]][travis]
 
 ## Changelog
-- **1.10**: _(2016-01-06)_
+- **1.11**: _(2016-01-07)_
+    * [~] `->appendChild()`, `->prependSibling()` and `->appendSibling()` support<br/>
+    the `@<attribute>` and `@` special syntax.
+
+
+- **1.10**:
     * [+] `->each()`, `->setCdata()` and `->cdata()` are part of the family.
 
 
@@ -129,7 +134,7 @@ XML
 );
 ```
 
-Creating **structured documents** is so easy that you will not believe.
+Creating **XML from Arrays** is so easy that you will not believe.
 
 ```php
 $food = fluidxml();
@@ -139,9 +144,16 @@ $food->add([ 'cake'  => 'tiramisu',
 
 $food->add([ ['egg'], ['egg'] ], ['price' => '0.25']);
 
-$food->add([ 'vegetarian' => [
-                    'pasta' => [
-                        'spaghetti' => 'with tomato' ]]);
+$food->add([ 'menu' => [
+                'pasta' => [
+                    'spaghetti' => [
+                        '@id'      => '123',
+                        '@country' => 'Italy',
+                        '@'        => 'Spaghetti are an Italian dish...',
+
+                        'variants' => [
+                            'tomato' => [ '@type' => 'vegan' ],
+                            'egg'    => [ '@type' => 'vegetarian' ] ]]]]]);
 ```
 
 Everything is fluid, even **iterations**.