Introduces the '->times()' method.

* [+] ->times() is part of the family.
servo-php · Jan 8, 2016 · ae8dd7c · ae8dd7c
1 parent dfb84f4
commit ae8dd7c
Show file tree

Hide file tree

Showing 5 changed files with 254 additions and 144 deletions.
diff --git a/documents/Changelog.txt b/documents/Changelog.txt
@@ -1,7 +1,13 @@
 [+]: new   [~]: changed   [-]: removed   [#]: fixed   [@]: internal
 
 
-1.11: (2016-01-07)
+1.12: (2016-01-08)
+introduces the '->times()' method.
+
+    * [+] ->times() is part of the family.
+
+
+1.11:
 supports the special syntax '@<attribute>' and '@' for setting attributes and
 text content when adding elements using an array.
 

diff --git a/documents/Getting-Started.md b/documents/Getting-Started.md
@@ -393,68 +393,35 @@ flexibility.
 > ```
 
 
-## Exporting The Document
+## Iterating
 
-The document can be exported as `DOMDocument`.
+Iterations can be performed without interrupting the fluid flow.
 
-```php
-$dom = $book->dom();
-```
-
-Or as XML string.
+`->each()` iterates the results of a query or of an insertion method.
 
 ```php
-$xml = $book->xml();
-```
-
-```xml
-<?xml version="1.0" encoding="UTF-8"?>
-<book>
-  <title>The Theory Of Everything</title>
-  <author>S. Hawking</author>
-  <description/>
-  <chapters>
-    <chapter>Ideas About The Universe</chapter>
-    <chapter>The Expanding Universe</chapter>
-  </chapters>
-  <cover>
-    <h1>The Theory Of Everything</h1>
-    <img src="http://goo.gl/kO3Iov"/>
-  </cover>
-</book>
-```
-
-The XML declaration can be removed from the output string too.
-```php
-$xml = $book->xml(true);
-```
+$book->query('//chapter')
+     ->each(function($chapter, $domnode, $index) {
+            $chapter->attr('id', $index + 1);
 
-```xml
-<book>
-  <title>The Theory Of Everything</title>
-  <author>S. Hawking</author>
-  <description/>
-  <chapters>
-    <chapter>Ideas About The Universe</chapter>
-    <chapter>The Expanding Universe</chapter>
-  </chapters>
-  <cover>
-    <h1>The Theory Of Everything</h1>
-    <img src="http://goo.gl/kO3Iov"/>
-  </cover>
-</book>
+            echo $domnode->nodeValue;
+     });
 ```
 
-Not only the entire document but even only specific nodes (with their content)<br/>
-can be exported.
+`->times($n)` repeats the following method call `$n` times. If a callable is<br/>
+passed as second argument, the callable is called `$n` times.
 
 ```php
-$xml = $book->query('//chapter')->xml();
+$book->query('//chapters')
+        ->times(2)
+            ->add('chapter');
 ```
 
-```xml
-<chapter>Ideas About The Universe</chapter>
-<chapter>The Expanding Universe</chapter>
+```php
+$book->query('//chapters')
+        ->times(2, function($chapters, $index) {
+            $chapters->add('chapter', [ 'id' => $index + 5 ]);
+        });
 ```
 
 
@@ -465,15 +432,6 @@ what is already convenient to use.
 
 To access the node content after a query we can use the DOMNode own methods.
 
-```php
-$book->query('//chapter')
-     ->each(function($fluid, $domnode, $index) {
-            $fluid->attr('uuid', random_uuid());
-
-            echo $domnode->nodeValue;
-     });
-```
-
 Accessing the query result as array or iterating it returns the DOMNode unwrapped.
 
 ```php
@@ -553,19 +511,8 @@ echo $book->xml();
 
 ```xml
 <?xml version="1.0" encoding="UTF-8"?>
-<book type="science">
-  <title lang="en">The Theory Of Everything</title>
-  <author>S. Hawking</author>
-  <chapters lang="en">
-    <chapter id="123" first="" lang="en">Ideas About The Universe</chapter>
-    <chapter id="321" lang="en">The Expanding Universe</chapter>
-    <chapter id="432" lang="en">Black Holes</chapter>
-    <chapter id="234" lang="en" last="">Black Holes Ain't So Black</chapter>
-  </chapters>
-  <cover>
-    <h1>The Theory Of Everything</h1>
-    <img src="http://goo.gl/kO3Iov"/>
-  </cover>
+<book>
+  ...
   <xhtml:h1 xmlns:xhtml="http://www.w3.org/1999/xhtml">
     <svg:shape xmlns:svg="http://www.w3.org/2000/svg"/>
   </xhtml:h1>
@@ -612,7 +559,7 @@ Which is the same of
 $food->query('//egg')->remove();        // Removes all the eggs.
 ```
 
-Quering and removing with relative XPath can be used too.
+Querying and removing with relative XPath can be done too.
 
 ```php
 $food->query('/doc')->remove('egg');    // Removes all the eggs.
@@ -626,6 +573,52 @@ $food->query('/doc')->remove('egg');    // Removes all the eggs.
 > ```
 
 
+## Exporting The Document
+
+The document can be exported as `DOMDocument`.
+
+```php
+$dom = $book->dom();
+```
+
+Or as XML string.
+
+```php
+$xml = $book->xml();
+```
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<book>
+  ...
+</book>
+```
+
+The XML declaration can be removed from the output string too.
+
+```php
+$xml = $book->xml(true);
+```
+
+```xml
+<book>
+  ...
+</book>
+```
+
+Not only the entire document but even only specific nodes (with their content)<br/>
+can be exported.
+
+```php
+$xml = $book->query('//chapter')->xml();
+```
+
+```xml
+<chapter lang="en" first="">Ideas About The Universe</chapter>
+<chapter lang="en" last="">The Expanding Universe</chapter>
+```
+
+
 ## Importing Existing Documents
 
 FluidXML provides an easy way to import existing XML documents from a variety of formats.
@@ -700,13 +693,12 @@ $doc->add($dom)                     // A DOMDocument/DOMNode/DOMNodeList instanc
     ->add($fluidxml->query('//p')); // A FluidXml query instance.
 ```
 
-Crazy things are possible too and I will not stop you from doing them.
+Crazy things are possible too using arrays and I will not stop you from doing them.
 
 ```php
-$doc->add([ 'aNode',
-            'domDoc' => $dom,
-            'file'   => fluidify('path/to/file.xml'),
-            'simple' => $simplexml ]);
+$doc->add([ 'dom'    => $dom,
+            'simple' => $simplexml,
+            'file'   => fluidify('path/to/file.xml') ]);
 ```