Changes between Version 9 and Version 10 of PyYAMLDocumentation

Timestamp:

05/06/06 10:49:57 (7 years ago)

Author:

xi

Comment:

--

PyYAMLDocumentation

@@ -663 +663 @@
 === YAMLError ===
 
+{{{
+#!python
+YAMLError()
+}}}
+
+If YAML parser encounters an error condition, it raises an exception which is an instance of
+'''`YAMLError`''' or of its subclass. An application may catch this exception and warn a user.
+{{{
+#!python
+try:
+    config = yaml.load(file('config.yaml', 'r'))
+except yaml.YAMLError, exc:
+    print "Error in configuration file:", exc
+}}}
+
+
+=== Mark ===
+{{{
+#!python
+Mark(name, index, line, column, buffer, pointer)
+}}}
+
+An instance of '''`Mark`''' points to a certain position in the input stream. '''`name`''' is
+the name of the stream, for instance it may be the filename if the input stream is a file.
+'''`line`''' and '''`column`''' is the line and column of the position (starting from 0).
+'''`buffer`''', when it is not `None`, is a part of the input stream that contain the position
+and '''`pointer`''' refers to the position in the `buffer`.
+
 
 === Tokens ===
 
+Tokens are produced by a YAML scanner. They are not really useful except for low-level YAML
+applications such as syntax highlighting.
+
+The PyYAML scanner produces the following types of tokens:
+{{{
+#!python
+StreamStartToken(encoding, start_mark, end_mark) # Start of the stream.
+StreamEndToken(start_mark, end_mark) # End of the stream.
+DirectiveToken(name, value, start_mark, end_mark) # YAML directive, either %YAML or %TAG.
+DocumentStartToken(start_mark, end_mark) # '---'.
+DocumentEndToken(start_mark, end_mark) # '...'.
+BlockSequenceStartToken(start_mark, end_mark) # Start of a new block sequence.
+BlockMappingStartToken(start_mark, end_mark) # Start of a new block mapping.
+BlockEndToken(start_mark, end_mark) # End of a block collection.
+FlowSequenceStartToken(start_mark, end_mark) # '['.
+FlowMappingStartToken(start_mark, end_mark) # '{'.
+FlowSequenceEndToken(start_mark, end_mark) # ']'.
+FlowMappingEndToken(start_mark, end_mark) # '}'.
+KeyToken(start_mark, end_mark) # Either '?' or start of a simple key.
+ValueToken(start_mark, end_mark) # ':'.
+BlockEntryToken(start_mark, end_mark) # '-'.
+FlowEntryToken(start_mark, end_mark) # ','.
+AliasToken(value, start_mark, end_mark) # '*value'.
+AnchorToken(value, start_mark, end_mark) # '&value'.
+TagToken(value, start_mark, end_mark) # '!value'.
+ScalarToken(value, plain, style, start_mark, end_mark) # 'value'.
+}}}
+
+'''`start_mark`''' and '''`end_mark`''' denote the beginning and the and of a token.
+
+Example:
+{{{
+#!python
+>>> document = """
+... ---
+... block sequence:
+... - BlockEntryToken
+... block mapping:
+...   ? KeyToken
+...   : ValueToken
+... flow sequence: [FlowEntryToken, FlowEntryToken]
+... flow mapping: {KeyToken: ValueToken}
+... anchors and tags:
+... - &A !!int '5'
+... - *A
+... ...
+... """
+
+>>> for token in yaml.scan(document):
+...     print token
+
+StreamStartToken(encoding='utf-8')
+
+DocumentStartToken()
+
+BlockMappingStartToken()
+
+KeyToken()
+ScalarToken(plain=True, style=None, value=u'block sequence')
+
+ValueToken()
+BlockEntryToken()
+ScalarToken(plain=True, style=None, value=u'BlockEntryToken')
+
+KeyToken()
+ScalarToken(plain=True, style=None, value=u'block mapping')
+
+ValueToken()
+BlockMappingStartToken()
+KeyToken()
+ScalarToken(plain=True, style=None, value=u'KeyToken')
+ValueToken()
+ScalarToken(plain=True, style=None, value=u'ValueToken')
+BlockEndToken()
+
+KeyToken()
+ScalarToken(plain=True, style=None, value=u'flow sequence')
+
+ValueToken()
+FlowSequenceStartToken()
+ScalarToken(plain=True, style=None, value=u'FlowEntryToken')
+FlowEntryToken()
+ScalarToken(plain=True, style=None, value=u'FlowEntryToken')
+FlowSequenceEndToken()
+
+KeyToken()
+ScalarToken(plain=True, style=None, value=u'flow mapping')
+
+ValueToken()
+FlowMappingStartToken()
+KeyToken()
+ScalarToken(plain=True, style=None, value=u'KeyToken')
+ValueToken()
+ScalarToken(plain=True, style=None, value=u'ValueToken')
+FlowMappingEndToken()
+
+KeyToken()
+ScalarToken(plain=True, style=None, value=u'anchors and tags')
+
+ValueToken()
+BlockEntryToken()
+AnchorToken(value=u'A')
+TagToken(value=(u'!!', u'int'))
+ScalarToken(plain=False, style="'", value=u'5')
+BlockEntryToken()
+AliasToken(value=u'A')
+
+BlockEndToken()
+
+DocumentEndToken()
+
+StreamEndToken()
+}}}
+
 
 === Events ===
 
+Events are used by the low-level Parser and Emitter interfaces, which are similar to the SAX API.
+While the Parser parses a YAML stream and produces a sequence of events, the Emitter accepts
+a sequence of events and emits a YAML stream.
+
+The following events are defined:
+{{{
+#!python
+StreamStartEvent(encoding, start_mark, end_mark)
+StreamEndEvent(start_mark, end_mark)
+DocumentStartEvent(explicit, version, tags, start_mark, end_mark)
+DocumentEndEvent(start_mark, end_mark)
+SequenceStartEvent(anchor, tag, implicit, flow_style, start_mark, end_mark)
+SequenceEndEvent(start_mark, end_mark)
+MappingStartEvent(anchor, tag, implicit, flow_style, start_mark, end_mark)
+MappingEndEvent(start_mark, end_mark)
+AliasEvent(anchor, start_mark, end_mark)
+ScalarEvent(anchor, tag, implicit, value, style, start_mark, end_mark)
+}}}
+
+The '''`flow_style`''' flag indicates if a collection is block or flow. The possible values are
+`None`, `True`, `False`. The '''`style`''' flag of a scalar event indicates the style of the scalar.
+Possible values are `None`, `''`, `'\''`, `'"'`, `'|'`, `'>'`. The '''`implicit`''' flag of a collection
+start event indicates if the tag may be omitted when the collection is emitted. The '''`implicit`''' flag
+of a scalar event is a pair of boolean values that indicate if the tag may be omitted when the scalar
+is emitted in a plain and non-plain style correspondingly.
+
+Example:
+{{{
+#!python
+>>> document = """
+... scalar: &A !!int '5'
+... alias: *A
+... sequence: [1, 2, 3]
+... mapping: [1: one, 2: two, 3: three]
+... """
+
+>>> for event in yaml.parse(document):
+...     print event
+
+StreamStartEvent()
+
+DocumentStartEvent()
+
+MappingStartEvent(anchor=None, tag=None, implicit=True)
+
+ScalarEvent(anchor=None, tag=None, implicit=(True, False), value=u'scalar')
+ScalarEvent(anchor=u'A', tag=u'tag:yaml.org,2002:int', implicit=(False, False), value=u'5')
+
+ScalarEvent(anchor=None, tag=None, implicit=(True, False), value=u'alias')
+AliasEvent(anchor=u'A')
+
+ScalarEvent(anchor=None, tag=None, implicit=(True, False), value=u'sequence')
+SequenceStartEvent(anchor=None, tag=None, implicit=True)
+ScalarEvent(anchor=None, tag=None, implicit=(True, False), value=u'1')
+ScalarEvent(anchor=None, tag=None, implicit=(True, False), value=u'2')
+ScalarEvent(anchor=None, tag=None, implicit=(True, False), value=u'3')
+SequenceEndEvent()
+
+ScalarEvent(anchor=None, tag=None, implicit=(True, False), value=u'mapping')
+MappingStartEvent(anchor=None, tag=None, implicit=True)
+ScalarEvent(anchor=None, tag=None, implicit=(True, False), value=u'1')
+ScalarEvent(anchor=None, tag=None, implicit=(True, False), value=u'one')
+ScalarEvent(anchor=None, tag=None, implicit=(True, False), value=u'2')
+ScalarEvent(anchor=None, tag=None, implicit=(True, False), value=u'two')
+ScalarEvent(anchor=None, tag=None, implicit=(True, False), value=u'3')
+ScalarEvent(anchor=None, tag=None, implicit=(True, False), value=u'three')
+MappingEndEvent()
+
+MappingEndEvent()
+
+DocumentEndEvent()
+
+StreamEndEvent()
+
+>>> print yaml.emit([
+...     yaml.StreamStartEvent(encoding='utf-8'),
+...     yaml.DocumentStartEvent(explicit=True),
+...     yaml.MappingStartEvent(anchor=None, tag=u'tag:yaml.org,2002:map', implicit=True, flow_style=False),
+...     yaml.ScalarEvent(anchor=None, tag=u'tag:yaml.org,2002:str', implicit=(True, True), value=u'agile languages'),
+...     yaml.SequenceStartEvent(anchor=None, tag=u'tag:yaml.org,2002:seq', implicit=True, flow_style=True),
+...     yaml.ScalarEvent(anchor=None, tag=u'tag:yaml.org,2002:str', implicit=(True, True), value=u'Python'),
+...     yaml.ScalarEvent(anchor=None, tag=u'tag:yaml.org,2002:str', implicit=(True, True), value=u'Perl'),
+...     yaml.ScalarEvent(anchor=None, tag=u'tag:yaml.org,2002:str', implicit=(True, True), value=u'Ruby'),
+...     yaml.SequenceEndEvent(),
+...     yaml.MappingEndEvent(),
+...     yaml.DocumentEndEvent(explicit=True),
+...     yaml.StreamEndEvent(),
+... ])
+
+---
+agile languages: [Python, Perl, Ruby]
+...
+}}}
+
 
 === Nodes ===
+