1 files changed, 110 insertions, 0 deletions
diff --git a/lib/fabpot-yaml/doc/01-Usage.markdown b/lib/fabpot-yaml/doc/01-Usage.markdown
new file mode 100644
index 0000000..644cf11
--- /dev/null
+++ b/lib/fabpot-yaml/doc/01-Usage.markdown
@@ -0,0 +1,110 @@
+Using Symfony YAML
+==================
+
+The Symfony YAML library is very simple and consists of two main classes: one
+to parse YAML strings (`sfYamlParser`), and the other to dump a PHP array to
+a YAML string (`sfYamlDumper`).
+
+On top of these two core classes, the main `sfYaml` class acts as a thin
+wrapper and simplifies common uses.
+
+Reading YAML Files
+------------------
+
+The `sfYamlParser::parse()` method parses a YAML string and converts it to a
+PHP array:
+
+    [php]
+    $yaml = new sfYamlParser();
+    $value = $yaml->parse(file_get_contents('/path/to/file.yaml'));
+
+If an error occurs during parsing, the parser throws an exception indicating
+the error type and the line in the original YAML string where the error
+occurred:
+
+    [php]
+    try
+    {
+      $value = $yaml->parse(file_get_contents('/path/to/file.yaml'));
+    }
+    catch (InvalidArgumentException $e)
+    {
+      // an error occurred during parsing
+      echo "Unable to parse the YAML string: ".$e->getMessage();
+    }
+
+>**TIP**
+>As the parser is reentrant, you can use the same parser object to load
+>different YAML strings.
+
+When loading a YAML file, it is sometimes better to use the `sfYaml::load()`
+wrapper method:
+
+    [php]
+    $loader = sfYaml::load('/path/to/file.yml');
+
+The `sfYaml::load()` static method takes a YAML string or a file containing
+YAML. Internally, it calls the `sfYamlParser::parse()` method, but with some
+added bonuses:
+
+  * It executes the YAML file as if it was a PHP file, so that you can embed
+    PHP commands in YAML files;
+
+  * When a file cannot be parsed, it automatically adds the file name to the
+    error message, simplifying debugging when your application is loading
+    several YAML files.
+
+Writing YAML Files
+------------------
+
+The `sfYamlDumper` dumps any PHP array to its YAML representation:
+
+    [php]
+    $array = array('foo' => 'bar', 'bar' => array('foo' => 'bar', 'bar' => 'baz'));
+
+    $dumper = new sfYamlDumper();
+    $yaml = $dumper->dump($array);
+    file_put_contents('/path/to/file.yaml', $yaml);
+
+>**NOTE**
+>Of course, the Symfony YAML dumper is not able to dump resources. Also,
+>even if the dumper is able to dump PHP objects, it is to be considered
+>an alpha feature.
+
+If you only need to dump one array, you can use the `sfYaml::dump()` static
+method shortcut:
+
+    [php]
+    $yaml = sfYaml::dump($array, $inline);
+
+The YAML format supports two kind of representation for arrays, the expanded
+one, and the inline one. By default, the dumper uses the inline
+representation:
+
+    [yml]
+    { foo: bar, bar: { foo: bar, bar: baz } }
+
+The second argument of the `dump()` method customizes the level at which the
+output switches from the expanded representation to the inline one:
+
+    [php]
+    echo $dumper->dump($array, 1);
+
+-
+
+    [yml]
+    foo: bar
+    bar: { foo: bar, bar: baz }
+
+-
+
+    [php]
+    echo $dumper->dump($array, 2);
+
+-
+
+    [yml]
+    foo: bar
+    bar:
+      foo: bar
+      bar: baz