/[web]/fidd/lib/fabpot-yaml/doc/01-Usage.markdown
ViewVC logotype

Contents of /fidd/lib/fabpot-yaml/doc/01-Usage.markdown

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1081 - (show annotations) (download)
Mon May 14 09:16:32 2012 UTC (11 years, 10 months ago) by rda
File size: 2939 byte(s)
add library and var dir
1 Using Symfony YAML
2 ==================
3
4 The Symfony YAML library is very simple and consists of two main classes: one
5 to parse YAML strings (`sfYamlParser`), and the other to dump a PHP array to
6 a YAML string (`sfYamlDumper`).
7
8 On top of these two core classes, the main `sfYaml` class acts as a thin
9 wrapper and simplifies common uses.
10
11 Reading YAML Files
12 ------------------
13
14 The `sfYamlParser::parse()` method parses a YAML string and converts it to a
15 PHP array:
16
17 [php]
18 $yaml = new sfYamlParser();
19 $value = $yaml->parse(file_get_contents('/path/to/file.yaml'));
20
21 If an error occurs during parsing, the parser throws an exception indicating
22 the error type and the line in the original YAML string where the error
23 occurred:
24
25 [php]
26 try
27 {
28 $value = $yaml->parse(file_get_contents('/path/to/file.yaml'));
29 }
30 catch (InvalidArgumentException $e)
31 {
32 // an error occurred during parsing
33 echo "Unable to parse the YAML string: ".$e->getMessage();
34 }
35
36 >**TIP**
37 >As the parser is reentrant, you can use the same parser object to load
38 >different YAML strings.
39
40 When loading a YAML file, it is sometimes better to use the `sfYaml::load()`
41 wrapper method:
42
43 [php]
44 $loader = sfYaml::load('/path/to/file.yml');
45
46 The `sfYaml::load()` static method takes a YAML string or a file containing
47 YAML. Internally, it calls the `sfYamlParser::parse()` method, but with some
48 added bonuses:
49
50 * It executes the YAML file as if it was a PHP file, so that you can embed
51 PHP commands in YAML files;
52
53 * When a file cannot be parsed, it automatically adds the file name to the
54 error message, simplifying debugging when your application is loading
55 several YAML files.
56
57 Writing YAML Files
58 ------------------
59
60 The `sfYamlDumper` dumps any PHP array to its YAML representation:
61
62 [php]
63 $array = array('foo' => 'bar', 'bar' => array('foo' => 'bar', 'bar' => 'baz'));
64
65 $dumper = new sfYamlDumper();
66 $yaml = $dumper->dump($array);
67 file_put_contents('/path/to/file.yaml', $yaml);
68
69 >**NOTE**
70 >Of course, the Symfony YAML dumper is not able to dump resources. Also,
71 >even if the dumper is able to dump PHP objects, it is to be considered
72 >an alpha feature.
73
74 If you only need to dump one array, you can use the `sfYaml::dump()` static
75 method shortcut:
76
77 [php]
78 $yaml = sfYaml::dump($array, $inline);
79
80 The YAML format supports two kind of representation for arrays, the expanded
81 one, and the inline one. By default, the dumper uses the inline
82 representation:
83
84 [yml]
85 { foo: bar, bar: { foo: bar, bar: baz } }
86
87 The second argument of the `dump()` method customizes the level at which the
88 output switches from the expanded representation to the inline one:
89
90 [php]
91 echo $dumper->dump($array, 1);
92
93 -
94
95 [yml]
96 foo: bar
97 bar: { foo: bar, bar: baz }
98
99 -
100
101 [php]
102 echo $dumper->dump($array, 2);
103
104 -
105
106 [yml]
107 foo: bar
108 bar:
109 foo: bar
110 bar: baz

  ViewVC Help
Powered by ViewVC 1.1.30