Changes between Version 7 and Version 8 of PyYAMLDocumentation


Ignore:
Timestamp:
05/05/06 18:48:49 (9 years ago)
Author:
xi
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • PyYAMLDocumentation

    v7 v8  
    55''RPG-ish descriptions are stolen from [http://www.thangorodrim.net/ the Angband rogue-like game]. 
    66Names of the heroes are generated with [http://www.ibiblio.org/pub/Linux/games/muds/mudnames-1.5.lsm MudNames].'' 
     7 
     8''This documentation is very brief and incomplete. Feel free to fix or improve it.'' 
     9 
    710 
    811[[PageOutline]] 
     
    470473}}} 
    471474 
     475Each style has its own quirks. A plain scalar does not use indicators to denote its 
     476start and end, therefore it's the most restricted style. Its natural applications are 
     477names of attributes and parameters. 
     478 
     479Using single-quoted scalars, you may express any value that does not contain special characters. 
     480No escaping occurs for single quoted scalars except that duplicate quotes '''`''`''' are replaced 
     481with a single quote '''`'`'''. 
     482 
     483Double-quoted is the most powerful style and the only style that can express any scalar value. 
     484Double-quoted scalars allow ''escaping''. Using escaping sequences '''`\x**`''' and '''`\u****`''', 
     485you may express any ASCII or Unicode character. 
     486 
     487There are two kind of block scalar styles: '''literal''' and '''folded'''. The literal style is 
     488the most suitable style for large block of text such as source code. The folded style is similar 
     489to the literal style, but two consequent non-empty lines are joined to a single line separated 
     490by a space character. 
     491 
    472492 
    473493=== Aliases === 
    474494 
     495'''Note that PyYAML does not yet support recursive objects.''' 
     496 
     497Using YAML you may represent objects of arbitrary graph-like structures. If you want to refer 
     498to the same object from different parts of a document, you need to use anchors and aliases. 
     499 
     500Anchors are denoted by the '''`&`''' indicator while aliases are denoted by '''`*`'''. For instance, 
     501the document 
     502{{{ 
     503left hand: &A The Bastard Sword of Eowyn 
     504right hand: *A 
     505}}} 
     506expresses the idea of a hero holding a heavy sword in both hands. 
     507 
    475508 
    476509=== Tags === 
    477510 
     511Tags are used to denote the type of a YAML node. Standard YAML tags are defined at 
     512http://yaml.org/type/index.html. 
     513 
     514Tags may be implicit: 
     515{{{ 
     516boolean: true 
     517integer: 3 
     518float: 3.14 
     519}}} 
     520{{{ 
     521#!python 
     522{'boolean': True, 'integer': 3, 'float': 3.14} 
     523}}} 
     524 
     525or explicit: 
     526{{{ 
     527boolean: !!bool "true" 
     528integer: !!int "3" 
     529float: !!float "3.14" 
     530}}} 
     531{{{ 
     532#!python 
     533{'boolean': True, 'integer': 3, 'float': 3.14} 
     534}}} 
     535 
     536Plain scalars without explicitly defined tag are subject to implicit tag 
     537resolution. The scalar value is checked against a set of regular expressions 
     538and if one of them matches, the corresponding tag is assigned to the scalar. 
     539PyYAML allows an application to add custom implicit tag resolvers. 
     540 
    478541 
    479542== YAML tags and Python types == 
    480543 
     544The following table describes how nodes with different tags are converted 
     545to Python objects. 
     546 
     547|| '''YAML tag'''                  || '''Python type'''  || 
     548|| ''Standard YAML tags''          ||                    || 
     549|| `!!null`                        || `None`             || 
     550|| `!!bool`                        || `bool`             || 
     551|| `!!int`                         || `int` or `long`    || 
     552|| `!!float`                       || `float`            || 
     553|| `!!binary`                      || `str`              || 
     554|| `!!timestamp`                   || `datetime.datetime` || 
     555|| `!!omap`, ``!!pairs``           || `list` of pairs    || 
     556|| `!!set`                         || `set`              || 
     557|| `!!str`                         || `str` or `unicode` || 
     558|| `!!seq`                         || `list`             || 
     559|| `!!map`                         || `dict`             || 
     560|| ''Python-specific tags''        ||                    || 
     561|| `!!python/none`                 || `None`             || 
     562|| `!!python/bool`                 || `bool`             || 
     563|| `!!python/str`                  || `str`              || 
     564|| `!!python/unicode`              || `unicode`          || 
     565|| `!!python/int`                  || `int`              || 
     566|| `!!python/long`                 || `long`             || 
     567|| `!!python/float`                || `float`            || 
     568|| `!!python/complex`              || `complex`          || 
     569|| `!!python/list`                 || `list`             || 
     570|| `!!python/tuple`                || `tuple`            || 
     571|| `!!python/dict`                 || `dict`             || 
     572|| ''Complex Python tags''         ||                    || 
     573|| `!!python/name:module.name`      || `module.name`       || 
     574|| `!!python/module:package.module` || `package.module`   || 
     575|| `!!python/object:module.cls`     || `module.cls` instance || 
     576|| `!!python/object/new:module.cls` || `module.cls` instance || 
     577|| `!!python/object/apply:module.f` || value of `f(...)`    || 
     578 
     579 
     580=== String conversion === 
     581 
     582There are four tags that are converted to `str` and `unicode` values: 
     583`!!str`, `!!binary`, `!!python/str`, and `!!python/unicode`. 
     584 
     585`!!str`-tagged scalars are converted to `str` objects if its value is ''ASCII''. Otherwise it is converted to `unicode`. 
     586`!!binary`-tagged scalars are converted to `str` objects with its value decoded using the ''base64'' encoding. 
     587`!!python/str` scalars are converted to `str` objects encoded with ''utf-8'' encoding. 
     588`!!python/unicode` scalars are converted to `unicode` objects. 
     589 
     590Conversely, a `str` object is converted to 
     591 1. a `!!str` scalar if its value is ''ASCII''. 
     592 2. a `!!python/str` scalar if its value is a correct ''utf-8'' sequence. 
     593 3. a `!!binary` scalar otherwise. 
     594 
     595A `unicode` object is converted to 
     596 1. a `!!python/unicode` scalar if its value is ''ASCII''. 
     597 2. a `!!str` scalar otherwise. 
     598 
     599=== Names and modules === 
     600 
     601In order to represent static Python objects like functions or classes, you need to use 
     602a complex '''`!!python/name`''' tag. For instance, the function '''`yaml.dump`''' can be represented as 
     603{{{ 
     604!!python/name:yaml.dump 
     605}}} 
     606 
     607 
     608Similarly, modules are represented using the tag '''`!python/module`''': 
     609{{{ 
     610!!python/module:yaml 
     611}}} 
     612 
     613=== Objects === 
     614 
     615Any pickleable object can be serialized using the '''`!!python/object`''' tag: 
     616{{{ 
     617!!python/object:module.Class { attribute: value, ... } 
     618}}} 
     619 
     620In order to support the pickle protocol, two additional forms of the '''`!!python/object`''' tag 
     621are provided: 
     622{{{ 
     623!!python/object/new:module.Class 
     624args: [argument, ...] 
     625kwds: {key: value, ...} 
     626state: ... 
     627listitems: [item, ...] 
     628dictitems: [key: value, ...] 
     629}}} 
     630{{{ 
     631!!python/object/apply:module.function 
     632args: [argument, ...] 
     633kwds: {key: value, ...} 
     634state: ... 
     635listitems: [item, ...] 
     636dictitems: [key: value, ...] 
     637}}} 
     638 
     639If only the '''`args`''' field is non-empty, the above records can be shortened: 
     640{{{ 
     641!!python/object/new:module.Class [argument, ...] 
     642}}} 
     643{{{ 
     644!!python/object/apply:module.function [argument, ...] 
     645}}} 
    481646 
    482647== Reference ==