yaml.txt Utility used to yaml JSON files
==============================================================================
==============================================================================
This plugin is a YAML-1.2 dumper/emitter. It is able to dump Vim data to
a YAML string, or load data from YAML encoded string.
Plugin requires stuf, load and oop plugins.
==============================================================================
This plugin provides 7 functions. Functions are accessed via dictionary
------------------------------------------------------------------------------
All following functions are accessed via dictionary returned by
Load YAML data from string.
given string.
Encode {data} in YAML and return resulting string. If optional
argument is present and it is not 1, then dumps function returns
a list of lines. {opts} optional variables is a dictionary with the
following keys:
Key Description
preserve_locks If this key is present and is 1, then it will add
a tag !!vim/Locked{type} to any locked variable, so
that locks can be restored
key_sort If this key is present and is 1, then dictionary keys
are sorted before dumping. It also accepts 0 for no
sorting and any function that does accept sort()
built-in (note that it accepts only function
references, not function names). Default: keep list
returned by keys() function unsorted.
all_flow If this key is present and is 1, then instead of using
block styles of collections and mappings and plain
(unquoted) flow scalar style, it will use only flow
and double-quoted styles.
custom_tags If this key is present and contains a list of function
references, then for every dumped object if one of the
functions in custom_tags list being given this object
as a single argument, returns a list with two items:
a String and an object, then first item in this list
is taken as a tag and second is dumped. For example,
the following function can be used to preserve locks
for a List and Dictionary objects: >
function DumpLocked(obj)
if islocked('a:obj')
return ["!!vim/Locked", a:obj]
endif
endfunction
Define a constructor for a given tag. {Constructor} function must
accept the only argument: dictionary that is an instance of a class
"Node" created by vimoop plugin (and it also is given an instance of
a class "Loader" as a self dictionary). This function must do the
following:
1. Being given a Node instance it must construct and return
appropriate value
2. Manually add constructed object to self.constructed_objects
dictionary like that (only if you want to support recursive data
structures): >
function Constructor(node) dict
let data=[] " or `let data={}'
let self.constructed_objects[a:node.id]=data
" Some code that modifies `data' variable
return data
endfunction
except construct_document define
self.constructed_objects[a:node.id] for you, so you do not need
to worry unless you want to support recursive data structures
like that: >
# Infinitely nested list that contains a link to itself as
# a first value
%YAML 1.2
--- &a
- *a
<
add_multi_constructor({tag-prefix}, {Constructor})
Define a constructor for all tags that start with {tag-prefix}.
{Constructor} function must accept two arguments: dictionary that is
an instance of a class "Node" created by vimoop plugin and
{tag-suffix}: part of a tag string after {tag-prefix} (and it also is
given an instance of a class "Loader" as a self dictionary). This
function must do the following:
1. Being given a Node instance it must construct and return
appropriate value
2. Manually add constructed object to self.constructed_objects
dictionary like that (only if you want to support recursive data
structures): >
function Constructor(node, suffix) dict
let data=[] " or `let data={}'
let self.constructed_objects[a:node.id]=data
" Some code that modifies `data' variable
return data
endfunction
except construct_document define
self.constructed_objects[a:node.id] for you, so you do not need
to worry unless you want to support recursive data structures
like that: >
# Infinitely nested list that contains a link to itself as
# a first value
%YAML 1.2
--- &a
- *a
tag or tag prefix.
==============================================================================
This section describe only that classes that may be helpful for writing custom
constructor.
Some notes:
- Description of the class may be incomplete since some functions are not
intended to be used outside this plugin.
(and other *Node classes)
------------------------------------------------------------------------------
Internally, every instance of this class is a dictionary with the following
keys (see oop.txt for more details):
Name of the class. As class `Node' is not used directly, it will
be one of the following:
- ScalarNode
- MappingNode
- SequenceNode
Unique (for the current document) identificator of the node.
Node value: depending on a type of the node it may be one of the
following:
Class Value
ScalarNode String
MappingNode List of Lists with two nodes:
[[{key-node}, {value-node}], ...]
SequenceNode List of nodes
Node's YAML tag string.
------------------------------------------------------------------------------
Internally, every instance of this class is a dictionary with the following
keys (see oop.txt for more details):
constructs a String with its value. If it is being given other
class' instance then it throws a error.
constructs a List. If it is being given other class' instance then
it throws a error.
constructs a Dictionary. If it is being given other class'
instance then it throws a error.
it: if it finds a key node with a tag `tag:yaml.org,2002:merge'
http://yaml.org/type/merge.html.
pairs.
------------------------------------------------------------------------------
Internally, every instance of this class is a dictionary with the following
keys (see oop.txt for more details):
Raise a marked yaml error. Arguments (in order):
1. Name of the function where error occures. You may specify 0 if
instead of function name to omit `In function ...:' header.
2. Name of some error class (without suffix `Error') that inherits
from MarkedYAMLError. If you are writing a constructor, then
use `Constructor' (that will throw ConstructorError) string
here.
3. Message string. It must contain `@|' that will separate context
description (like `While parsing a flow node') from problem
description. If you do not want to have a context message, then
just use `@|Problem message'. Note that it must contain only
one `@|'.
then specify 0 instead.
5. (Optional) note message. In fact, I never used it, so it is
untested.
vim: ft=help:tw=78