Changes between Version 21 and Version 22 of PyYAMLDocumentation

Timestamp:

05/07/06 09:34:49 (7 years ago)

Author:

xi

Comment:

--

PyYAMLDocumentation

@@ -12 +12 @@
 
 
-== Basic usage ==
+== Introduction ==
 
 Start with importing the '''`yaml`''' package.
@@ -22 +22 @@
 
 
-=== load() ===
+=== Loading YAML ===
 
 '''Warning: It is not safe to call `yaml.load` with any data received from an untrusted source!
@@ -63 +63 @@
 }}}
 
-if a string or a file contains several documents, you may load them all with the
+If a string or a file contains several documents, you may load them all with the
 '''`yaml.load_all`''' function.
 
@@ -142 +142 @@
 
 
-=== dump() ===
+=== Dumping YAML ===
 
 The '''`yaml.dump`''' function accepts a Python object and produces a YAML document.
@@ -236 +236 @@
 >>> print yaml.dump(range(5), default_flow_style=True, default_style='"')
 [!!int "0", !!int "1", !!int "2", !!int "3", !!int "4"]
+}}}
+
+
+=== Constructors, representers, resolvers ===
+
+You may define your own application-specific tags. The easiest way to do it is
+to define a subclass of '''`yaml.YAMLObject`''':
+{{{{
+#!python
+>>> yaml.load("""
+... --- !Monster
+... name: Cave spider
+... hp: [2,6]    # 2d6
+... ac: 16
+... attacks: [BITE, HURT]
+... """)
+
+Monster(name='Cave spider', hp=[2, 6], ac=16, attacks=['BITE', 'HURT'])
+
+>>> print yaml.dump(Monster(
+...     name='Cave lizard', hp=[3,6], ac=16, attacks=['BITE','HURT']))
+
+!Monster
+ac: 16
+attacks: [BITE, HURT]
+hp: [3, 6]
+name: Cave lizard
+}}}}
+
+'''`yaml.YAMLObject`''' uses metaclass magic to register a constructor, which
+transforms a YAML node to a class instance, and a representer, which serializes
+a class instance to a YAML node.
+
+If you don't want to use metaclasses, you may register your constructors
+and representers using the functions '''`yaml.add_constructor`''' and
+'''`yaml.add_representer`'''. For instance, you may want to add a constructor
+and a representer for the following '''`Dice`''' class:
+{{{
+#!python
+>>> class Dice(tuple):
+...     def __new__(cls, a, b):
+...         return tuple.__new__(cls, [a, b])
+...     def __repr__(self):
+...         return "%sd%s" % self
+
+>>> print Dice(3,6)
+3d6
+}}}
+
+First we define a representer, that convert a dice object to scalar node
+with the tag `!dice` and register it.
+{{{
+#!python
+>>> def dice_representer(dumper, data):
+...     return dumper.represent_scalar(u'!dice', unicode(data))
+
+>>> yaml.add_representer(Dice, dice_representer)
+}}}
+
+Now you may dump an instance of the `Dice` object:
+{{{
+#!python
+>>> print yaml.dump({'gold': Dice(10,6)})
+{gold: !dice '10d6'}
+}}}
+
+Let us add the code to construct a Dice object:
+{{{
+#!python
+>>> def dice_constructor(loader, node):
+...     value = loader.construct_scalar(node)
+...     a, b = map(int, value.split('d'))
+...     return Dice(a, b)
+
+>>> yaml.add_constructor(u'!dice', dice_constructor)
+}}}
+
+Then you may load a `Dice` object as well:
+{{{
+#!python
+>>> print yaml.load("""
+... initial hit points: !dice 8d4
+... """)
+
+{'initial hit points': 8d4
+}}}
+
+You might want to not specify the tag `!dice` everywhere. There is a way
+to teach PyYAML that any untagged plain scalar that looks like XdY has
+the implicit tag `!dice`. Use '''`add_implicit_resolver`''':
+{{{
+#!python
+>>> import re
+>>> pattern = re.compile(r'^\d+d\d+$')
+>>> yaml.add_implicit_resolver(u'!dice', pattern)
+}}}
+
+Now you don't have to specify the tag to define a `Dice` object:
+{{{
+#!python
+>>> print yaml.dump({'treasure': Dice(10,20)})
+
+{treasure: 10d20}
+
+>>> print yaml.load("""
+... damage: 5d10
+... """)
+
+{'damage': 5d10}
 }}}
 
@@ -1354 +1463 @@
 } # this is indentation violation according to the spec.
 }}}
- * ':' is not allowed for plain scalars in the flow mode. '''{1:2}''' is
-   interpreted as '''{ 1 : 2 }'''.
+ * ':' is not allowed for plain scalars in the flow mode. ~~~'''{1:2}''' is
+   interpreted as '''{ 1 : 2 }'''.~~~
 
 
 == Notes ==
 
-Long-term goals:
- * fix tabs, ~~indentation for flow collections, indentation for scalars (min=1?), 'y' is '''!!bool'''~~,
+To do and long-term goals:
+ * fix recursive objects, refactor Emitter, tabs,
+   ~~indentation for flow collections, indentation for scalars (min=1?), 'y' is '''!!bool'''~~,
  * libyaml3000 (my SoC proposal).