Changes between Version 9 and Version 10 of PyYAMLDocumentation


Ignore:
Timestamp:
05/06/06 10:49:57 (8 years ago)
Author:
xi
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • PyYAMLDocumentation

    v9 v10  
    663663=== YAMLError === 
    664664 
     665{{{ 
     666#!python 
     667YAMLError() 
     668}}} 
     669 
     670If YAML parser encounters an error condition, it raises an exception which is an instance of 
     671'''`YAMLError`''' or of its subclass. An application may catch this exception and warn a user. 
     672{{{ 
     673#!python 
     674try: 
     675    config = yaml.load(file('config.yaml', 'r')) 
     676except yaml.YAMLError, exc: 
     677    print "Error in configuration file:", exc 
     678}}} 
     679 
     680 
     681=== Mark === 
     682{{{ 
     683#!python 
     684Mark(name, index, line, column, buffer, pointer) 
     685}}} 
     686 
     687An instance of '''`Mark`''' points to a certain position in the input stream. '''`name`''' is 
     688the name of the stream, for instance it may be the filename if the input stream is a file. 
     689'''`line`''' and '''`column`''' is the line and column of the position (starting from 0). 
     690'''`buffer`''', when it is not `None`, is a part of the input stream that contain the position 
     691and '''`pointer`''' refers to the position in the `buffer`. 
     692 
    665693 
    666694=== Tokens === 
    667695 
     696Tokens are produced by a YAML scanner. They are not really useful except for low-level YAML 
     697applications such as syntax highlighting. 
     698 
     699The PyYAML scanner produces the following types of tokens: 
     700{{{ 
     701#!python 
     702StreamStartToken(encoding, start_mark, end_mark) # Start of the stream. 
     703StreamEndToken(start_mark, end_mark) # End of the stream. 
     704DirectiveToken(name, value, start_mark, end_mark) # YAML directive, either %YAML or %TAG. 
     705DocumentStartToken(start_mark, end_mark) # '---'. 
     706DocumentEndToken(start_mark, end_mark) # '...'. 
     707BlockSequenceStartToken(start_mark, end_mark) # Start of a new block sequence. 
     708BlockMappingStartToken(start_mark, end_mark) # Start of a new block mapping. 
     709BlockEndToken(start_mark, end_mark) # End of a block collection. 
     710FlowSequenceStartToken(start_mark, end_mark) # '['. 
     711FlowMappingStartToken(start_mark, end_mark) # '{'. 
     712FlowSequenceEndToken(start_mark, end_mark) # ']'. 
     713FlowMappingEndToken(start_mark, end_mark) # '}'. 
     714KeyToken(start_mark, end_mark) # Either '?' or start of a simple key. 
     715ValueToken(start_mark, end_mark) # ':'. 
     716BlockEntryToken(start_mark, end_mark) # '-'. 
     717FlowEntryToken(start_mark, end_mark) # ','. 
     718AliasToken(value, start_mark, end_mark) # '*value'. 
     719AnchorToken(value, start_mark, end_mark) # '&value'. 
     720TagToken(value, start_mark, end_mark) # '!value'. 
     721ScalarToken(value, plain, style, start_mark, end_mark) # 'value'. 
     722}}} 
     723 
     724'''`start_mark`''' and '''`end_mark`''' denote the beginning and the and of a token. 
     725 
     726Example: 
     727{{{ 
     728#!python 
     729>>> document = """ 
     730... --- 
     731... block sequence: 
     732... - BlockEntryToken 
     733... block mapping: 
     734...   ? KeyToken 
     735...   : ValueToken 
     736... flow sequence: [FlowEntryToken, FlowEntryToken] 
     737... flow mapping: {KeyToken: ValueToken} 
     738... anchors and tags: 
     739... - &A !!int '5' 
     740... - *A 
     741... ... 
     742... """ 
     743 
     744>>> for token in yaml.scan(document): 
     745...     print token 
     746 
     747StreamStartToken(encoding='utf-8') 
     748 
     749DocumentStartToken() 
     750 
     751BlockMappingStartToken() 
     752 
     753KeyToken() 
     754ScalarToken(plain=True, style=None, value=u'block sequence') 
     755 
     756ValueToken() 
     757BlockEntryToken() 
     758ScalarToken(plain=True, style=None, value=u'BlockEntryToken') 
     759 
     760KeyToken() 
     761ScalarToken(plain=True, style=None, value=u'block mapping') 
     762 
     763ValueToken() 
     764BlockMappingStartToken() 
     765KeyToken() 
     766ScalarToken(plain=True, style=None, value=u'KeyToken') 
     767ValueToken() 
     768ScalarToken(plain=True, style=None, value=u'ValueToken') 
     769BlockEndToken() 
     770 
     771KeyToken() 
     772ScalarToken(plain=True, style=None, value=u'flow sequence') 
     773 
     774ValueToken() 
     775FlowSequenceStartToken() 
     776ScalarToken(plain=True, style=None, value=u'FlowEntryToken') 
     777FlowEntryToken() 
     778ScalarToken(plain=True, style=None, value=u'FlowEntryToken') 
     779FlowSequenceEndToken() 
     780 
     781KeyToken() 
     782ScalarToken(plain=True, style=None, value=u'flow mapping') 
     783 
     784ValueToken() 
     785FlowMappingStartToken() 
     786KeyToken() 
     787ScalarToken(plain=True, style=None, value=u'KeyToken') 
     788ValueToken() 
     789ScalarToken(plain=True, style=None, value=u'ValueToken') 
     790FlowMappingEndToken() 
     791 
     792KeyToken() 
     793ScalarToken(plain=True, style=None, value=u'anchors and tags') 
     794 
     795ValueToken() 
     796BlockEntryToken() 
     797AnchorToken(value=u'A') 
     798TagToken(value=(u'!!', u'int')) 
     799ScalarToken(plain=False, style="'", value=u'5') 
     800BlockEntryToken() 
     801AliasToken(value=u'A') 
     802 
     803BlockEndToken() 
     804 
     805DocumentEndToken() 
     806 
     807StreamEndToken() 
     808}}} 
     809 
    668810 
    669811=== Events === 
    670812 
     813Events are used by the low-level Parser and Emitter interfaces, which are similar to the SAX API. 
     814While the Parser parses a YAML stream and produces a sequence of events, the Emitter accepts 
     815a sequence of events and emits a YAML stream. 
     816 
     817The following events are defined: 
     818{{{ 
     819#!python 
     820StreamStartEvent(encoding, start_mark, end_mark) 
     821StreamEndEvent(start_mark, end_mark) 
     822DocumentStartEvent(explicit, version, tags, start_mark, end_mark) 
     823DocumentEndEvent(start_mark, end_mark) 
     824SequenceStartEvent(anchor, tag, implicit, flow_style, start_mark, end_mark) 
     825SequenceEndEvent(start_mark, end_mark) 
     826MappingStartEvent(anchor, tag, implicit, flow_style, start_mark, end_mark) 
     827MappingEndEvent(start_mark, end_mark) 
     828AliasEvent(anchor, start_mark, end_mark) 
     829ScalarEvent(anchor, tag, implicit, value, style, start_mark, end_mark) 
     830}}} 
     831 
     832The '''`flow_style`''' flag indicates if a collection is block or flow. The possible values are 
     833`None`, `True`, `False`. The '''`style`''' flag of a scalar event indicates the style of the scalar. 
     834Possible values are `None`, `''`, `'\''`, `'"'`, `'|'`, `'>'`. The '''`implicit`''' flag of a collection 
     835start event indicates if the tag may be omitted when the collection is emitted. The '''`implicit`''' flag 
     836of a scalar event is a pair of boolean values that indicate if the tag may be omitted when the scalar 
     837is emitted in a plain and non-plain style correspondingly. 
     838 
     839Example: 
     840{{{ 
     841#!python 
     842>>> document = """ 
     843... scalar: &A !!int '5' 
     844... alias: *A 
     845... sequence: [1, 2, 3] 
     846... mapping: [1: one, 2: two, 3: three] 
     847... """ 
     848 
     849>>> for event in yaml.parse(document): 
     850...     print event 
     851 
     852StreamStartEvent() 
     853 
     854DocumentStartEvent() 
     855 
     856MappingStartEvent(anchor=None, tag=None, implicit=True) 
     857 
     858ScalarEvent(anchor=None, tag=None, implicit=(True, False), value=u'scalar') 
     859ScalarEvent(anchor=u'A', tag=u'tag:yaml.org,2002:int', implicit=(False, False), value=u'5') 
     860 
     861ScalarEvent(anchor=None, tag=None, implicit=(True, False), value=u'alias') 
     862AliasEvent(anchor=u'A') 
     863 
     864ScalarEvent(anchor=None, tag=None, implicit=(True, False), value=u'sequence') 
     865SequenceStartEvent(anchor=None, tag=None, implicit=True) 
     866ScalarEvent(anchor=None, tag=None, implicit=(True, False), value=u'1') 
     867ScalarEvent(anchor=None, tag=None, implicit=(True, False), value=u'2') 
     868ScalarEvent(anchor=None, tag=None, implicit=(True, False), value=u'3') 
     869SequenceEndEvent() 
     870 
     871ScalarEvent(anchor=None, tag=None, implicit=(True, False), value=u'mapping') 
     872MappingStartEvent(anchor=None, tag=None, implicit=True) 
     873ScalarEvent(anchor=None, tag=None, implicit=(True, False), value=u'1') 
     874ScalarEvent(anchor=None, tag=None, implicit=(True, False), value=u'one') 
     875ScalarEvent(anchor=None, tag=None, implicit=(True, False), value=u'2') 
     876ScalarEvent(anchor=None, tag=None, implicit=(True, False), value=u'two') 
     877ScalarEvent(anchor=None, tag=None, implicit=(True, False), value=u'3') 
     878ScalarEvent(anchor=None, tag=None, implicit=(True, False), value=u'three') 
     879MappingEndEvent() 
     880 
     881MappingEndEvent() 
     882 
     883DocumentEndEvent() 
     884 
     885StreamEndEvent() 
     886 
     887>>> print yaml.emit([ 
     888...     yaml.StreamStartEvent(encoding='utf-8'), 
     889...     yaml.DocumentStartEvent(explicit=True), 
     890...     yaml.MappingStartEvent(anchor=None, tag=u'tag:yaml.org,2002:map', implicit=True, flow_style=False), 
     891...     yaml.ScalarEvent(anchor=None, tag=u'tag:yaml.org,2002:str', implicit=(True, True), value=u'agile languages'), 
     892...     yaml.SequenceStartEvent(anchor=None, tag=u'tag:yaml.org,2002:seq', implicit=True, flow_style=True), 
     893...     yaml.ScalarEvent(anchor=None, tag=u'tag:yaml.org,2002:str', implicit=(True, True), value=u'Python'), 
     894...     yaml.ScalarEvent(anchor=None, tag=u'tag:yaml.org,2002:str', implicit=(True, True), value=u'Perl'), 
     895...     yaml.ScalarEvent(anchor=None, tag=u'tag:yaml.org,2002:str', implicit=(True, True), value=u'Ruby'), 
     896...     yaml.SequenceEndEvent(), 
     897...     yaml.MappingEndEvent(), 
     898...     yaml.DocumentEndEvent(explicit=True), 
     899...     yaml.StreamEndEvent(), 
     900... ]) 
     901 
     902--- 
     903agile languages: [Python, Perl, Ruby] 
     904... 
     905}}} 
     906 
    671907 
    672908=== Nodes === 
     909 
    673910 
    674911