Changes between Version 7 and Version 8 of PyYAMLDocumentation

Timestamp:

05/05/06 18:48:49 (7 years ago)

Author:

xi

Comment:

--

PyYAMLDocumentation

@@ -5 +5 @@
 ''RPG-ish descriptions are stolen from [http://www.thangorodrim.net/ the Angband rogue-like game].
 Names of the heroes are generated with [http://www.ibiblio.org/pub/Linux/games/muds/mudnames-1.5.lsm MudNames].''
+
+''This documentation is very brief and incomplete. Feel free to fix or improve it.''
+
 
 [[PageOutline]]
@@ -470 +473 @@
 }}}
 
+Each style has its own quirks. A plain scalar does not use indicators to denote its
+start and end, therefore it's the most restricted style. Its natural applications are
+names of attributes and parameters.
+
+Using single-quoted scalars, you may express any value that does not contain special characters.
+No escaping occurs for single quoted scalars except that duplicate quotes '''`''`''' are replaced
+with a single quote '''`'`'''.
+
+Double-quoted is the most powerful style and the only style that can express any scalar value.
+Double-quoted scalars allow ''escaping''. Using escaping sequences '''`\x**`''' and '''`\u****`''',
+you may express any ASCII or Unicode character.
+
+There are two kind of block scalar styles: '''literal''' and '''folded'''. The literal style is
+the most suitable style for large block of text such as source code. The folded style is similar
+to the literal style, but two consequent non-empty lines are joined to a single line separated
+by a space character.
+
 
 === Aliases ===
 
+'''Note that PyYAML does not yet support recursive objects.'''
+
+Using YAML you may represent objects of arbitrary graph-like structures. If you want to refer
+to the same object from different parts of a document, you need to use anchors and aliases.
+
+Anchors are denoted by the '''`&`''' indicator while aliases are denoted by '''`*`'''. For instance,
+the document
+{{{
+left hand: &A The Bastard Sword of Eowyn
+right hand: *A
+}}}
+expresses the idea of a hero holding a heavy sword in both hands.
+
 
 === Tags ===
 
+Tags are used to denote the type of a YAML node. Standard YAML tags are defined at
+http://yaml.org/type/index.html.
+
+Tags may be implicit:
+{{{
+boolean: true
+integer: 3
+float: 3.14
+}}}
+{{{
+#!python
+{'boolean': True, 'integer': 3, 'float': 3.14}
+}}}
+
+or explicit:
+{{{
+boolean: !!bool "true"
+integer: !!int "3"
+float: !!float "3.14"
+}}}
+{{{
+#!python
+{'boolean': True, 'integer': 3, 'float': 3.14}
+}}}
+
+Plain scalars without explicitly defined tag are subject to implicit tag
+resolution. The scalar value is checked against a set of regular expressions
+and if one of them matches, the corresponding tag is assigned to the scalar.
+PyYAML allows an application to add custom implicit tag resolvers.
+
 
 == YAML tags and Python types ==
 
+The following table describes how nodes with different tags are converted
+to Python objects.
+
+|| '''YAML tag'''                  || '''Python type'''  ||
+|| ''Standard YAML tags''          ||                    ||
+|| `!!null`                        || `None`             ||
+|| `!!bool`                        || `bool`             ||
+|| `!!int`                         || `int` or `long`    ||
+|| `!!float`                       || `float`            ||
+|| `!!binary`                      || `str`              ||
+|| `!!timestamp`                   || `datetime.datetime` ||
+|| `!!omap`, ``!!pairs``           || `list` of pairs    ||
+|| `!!set`                         || `set`              ||
+|| `!!str`                         || `str` or `unicode` ||
+|| `!!seq`                         || `list`             ||
+|| `!!map`                         || `dict`             ||
+|| ''Python-specific tags''        ||                    ||
+|| `!!python/none`                 || `None`             ||
+|| `!!python/bool`                 || `bool`             ||
+|| `!!python/str`                  || `str`              ||
+|| `!!python/unicode`              || `unicode`          ||
+|| `!!python/int`                  || `int`              ||
+|| `!!python/long`                 || `long`             ||
+|| `!!python/float`                || `float`            ||
+|| `!!python/complex`              || `complex`          ||
+|| `!!python/list`                 || `list`             ||
+|| `!!python/tuple`                || `tuple`            ||
+|| `!!python/dict`                 || `dict`             ||
+|| ''Complex Python tags''         ||                    ||
+|| `!!python/name:module.name`      || `module.name`       ||
+|| `!!python/module:package.module` || `package.module`   ||
+|| `!!python/object:module.cls`     || `module.cls` instance ||
+|| `!!python/object/new:module.cls` || `module.cls` instance ||
+|| `!!python/object/apply:module.f` || value of `f(...)`    ||
+
+
+=== String conversion ===
+
+There are four tags that are converted to `str` and `unicode` values:
+`!!str`, `!!binary`, `!!python/str`, and `!!python/unicode`.
+
+`!!str`-tagged scalars are converted to `str` objects if its value is ''ASCII''. Otherwise it is converted to `unicode`.
+`!!binary`-tagged scalars are converted to `str` objects with its value decoded using the ''base64'' encoding.
+`!!python/str` scalars are converted to `str` objects encoded with ''utf-8'' encoding.
+`!!python/unicode` scalars are converted to `unicode` objects.
+
+Conversely, a `str` object is converted to
+ 1. a `!!str` scalar if its value is ''ASCII''.
+ 2. a `!!python/str` scalar if its value is a correct ''utf-8'' sequence.
+ 3. a `!!binary` scalar otherwise.
+
+A `unicode` object is converted to
+ 1. a `!!python/unicode` scalar if its value is ''ASCII''.
+ 2. a `!!str` scalar otherwise.
+
+=== Names and modules ===
+
+In order to represent static Python objects like functions or classes, you need to use
+a complex '''`!!python/name`''' tag. For instance, the function '''`yaml.dump`''' can be represented as
+{{{
+!!python/name:yaml.dump
+}}}
+
+
+Similarly, modules are represented using the tag '''`!python/module`''':
+{{{
+!!python/module:yaml
+}}}
+
+=== Objects ===
+
+Any pickleable object can be serialized using the '''`!!python/object`''' tag:
+{{{
+!!python/object:module.Class { attribute: value, ... }
+}}}
+
+In order to support the pickle protocol, two additional forms of the '''`!!python/object`''' tag
+are provided:
+{{{
+!!python/object/new:module.Class
+args: [argument, ...]
+kwds: {key: value, ...}
+state: ...
+listitems: [item, ...]
+dictitems: [key: value, ...]
+}}}
+{{{
+!!python/object/apply:module.function
+args: [argument, ...]
+kwds: {key: value, ...}
+state: ...
+listitems: [item, ...]
+dictitems: [key: value, ...]
+}}}
+
+If only the '''`args`''' field is non-empty, the above records can be shortened:
+{{{
+!!python/object/new:module.Class [argument, ...]
+}}}
+{{{
+!!python/object/apply:module.function [argument, ...]
+}}}
 
 == Reference ==