Metadata-Version: 1.1
Name: shyaml
Version: 0.2.0
Summary: Simple YAML accessor for shell scripts
Description: =================================
       |SHYAML: YAML for the command line
       |=================================
       |
       |
       |Disclaimer
       |==========
       |
       |This scripts was written very quickly and will not support all YAML
       |manipulation that you could have dreamed of. But it should support
       |some handy basic query of YAML file.
       |
       |Please take a look at the next section to get a quick overview of
       |``shyaml`` capabilities.
       |
       |
       |Description
       |===========
       |
       |Simple scripts that allow read access to YAML files through command line.
       |
       |This can be handy, if you want to get access to YAML data in your shell
       |scripts.
       |
       |
       |Installation
       |============
       |
       |This script could be used out of the box, take the ``shyaml`` file and use it
       |directly.
       |
       |If you want to use the distribution method I've chosen, which is ``distutils2``,
       |please first make sure you have ``distutils2``, in which case you could do a::
       |
       |    pysetup install shyaml
       |
       |It should be compatible with older distribution method, so this should also
       |work::
       |
       |    pip install shyaml
       |
       |Please note that if you got the code thanks to git. You'll need to execute
       |``./autogen.sh`` in order to generate missing files as the ``CHANGELOG.rst``
       |and the ``setup.py``. Then you can choose to directly use the ``shyaml``
       |binary, or install it thanks to classical ``pysetup install``
       |(or ``python setup.py``).
       |
       |
       |Usage
       |=====
       |
       |``shyaml`` takes its YAML input file from standard input ONLY. So there are
       |some sample routine:
       |
       |Let's create a sample yaml file::
       |
       |    $ cat <<EOF > test.yaml
       |    name: "MyName !!"
       |    subvalue:
       |        how-much: 1.1
       |        how-many: 2
       |        things:
       |            - first
       |            - second
       |            - third
       |        maintainer: "Valentin Lab"
       |        description: |
       |            Multiline description:
       |            Line 1
       |            Line 2
       |    EOF
       |
       |
       |General browsing struct and displaying simple values
       |----------------------------------------------------
       |
       |Simple query of simple attribute::
       |
       |    $ cat test.yaml | shyaml get-value name
       |    MyName !!
       |
       |Query nested attributes::
       |
       |    $ cat test.yaml | shyaml get-value subvalue.how-much
       |    1.1
       |
       |Get type of attributes::
       |
       |    $ cat test.yaml | shyaml get-type name
       |    str
       |    $ cat test.yaml | shyaml get-type subvalue.how-much
       |    float
       |
       |
       |Parse structure
       |---------------
       |
       |Get sub YAML from a structure attribute::
       |
       |    $ cat test.yaml | shyaml get-type subvalue
       |    struct
       |    $ cat test.yaml | shyaml get-value subvalue
       |    description: 'Multiline description:
       |
       |      Line 1
       |
       |      Line 2
       |
       |      '
       |    how-many: 2
       |    how-much: 1.1
       |    maintainer: Valentin Lab
       |    things:
       |    - first
       |    - second
       |    - third
       |
       |Iteration through keys only::
       |
       |    $ cat test.yaml | shyaml keys
       |    subvalue
       |    name
       |
       |Iteration through keys only (\0 terminated strings)::
       |
       |    $ cat test.yaml | shyaml keys-0 subvalue | xargs -0 -n 1 echo "VALUE:"
       |    VALUE: how-much
       |    VALUE: things
       |    VALUE: how-many
       |    VALUE: maintainer
       |    VALUE: description
       |
       |
       |Iteration though values only (\0 terminated string highly recommended)::
       |
       |    $ cat test.yaml | shyaml values-0 | \
       |      while read -r -d $'\0' value; do
       |          echo "RECEIVED: '$value'"
       |      done
       |    RECEIVED: '1.1'
       |    RECEIVED: '- first
       |    - second
       |    - third'
       |    RECEIVED: '2'
       |    RECEIVED: 'Valentin Lab'
       |    RECEIVED: 'Multiline description:
       |    Line 1
       |    Line 2'
       |
       |
       |Parse sequence
       |--------------
       |
       |Query a sequence::
       |
       |   $ cat test.yaml | shyaml get-value subvalue.things
       |   - first
       |   - second
       |   - third
       |   $ cat test.yaml | shyaml get-value subvalue.things.0
       |   first
       |   $ cat test.yaml | shyaml get-value subvalue.things.-1
       |   third
       |   $ cat test.yaml | shyaml get-value subvalue.things.5
       |   Error: list index error in path 'subvalue.things.5'.
       |
       |More usefull, parse a list in one go::
       |
       |   $ cat test.yaml | shyaml get-values subvalue.things
       |   first
       |   second
       |   third
       |
       |Note that the action is called ``get-values``, and that output is separated by
       |``\n`` chars, this can bring havoc if you are parsing values containing this
       |character. Hopefully, ``shyaml`` has a ``get-values-0`` to terminate strings by
       |``\0`` char, which allows complete support of any type of values, including
       |YAML.  ``get-values`` outputs key and values for ``struct`` types and only
       |values for ``sequence`` types::
       |
       |    $ cat test.yaml | shyaml get-values-0 subvalue | \
       |      while read -r -d $'\0' key value; do
       |          echo "'$key' -> '$value'"
       |      done
       |    'how-much' -> '1.1'
       |    'things' -> '- first
       |    - second
       |    - third'
       |    'how-many' -> '2'
       |    'maintainer' -> 'Valentin Lab'
       |    'description' -> 'Multiline description:
       |    Line 1
       |    Line 2'
       |
       |You should also notice that values that are displayed are YAML compatible. So
       |if they are complex, you can re-use ``shyaml`` on them to parse their content.
       |
       |
       |Usage string
       |------------
       |
       |A Quick remainder of what is available::
       |
       |    $ shyaml
       |    usage:
       |        shyaml {get-value{,-0},get-type,keys{,-0},values{,-0}} KEY DEFAULT
       |Changelog
       |=========
       |
       |0.2.0 (2013-05-03)
       |------------------
       |
       |New
       |~~~
       |
       |- Support for iteration in sequence and struct in one go. [Valentin Lab]
       |
       |- Generate the ``setup.py`` files from ``setup.cfg`` so that PyPI
       |  packages are compatible with ``setuptools``-like installers (as
       |  ``pip``). [Valentin Lab]
       |
       |Fix
       |~~~
       |
       |- Doc: forgot to mention ``./autogen.sh`` execution when getting the
       |  code from git, and be more clear about other means of installation.
       |  [Valentin Lab]
       |
       |- Generated ``setup.py`` do not support file names on the same line,
       |  this prevented installation via ``pip install``. [Valentin Lab]
       |
       |0.1.3 (2013-03-29)
       |------------------
       |
       |Fix
       |~~~
       |
       |- Removed the spurious line feed at the end of any ``shyaml`` output.
       |  [Valentin Lab]
       |
       |- Support querying for... nothing. Which now returns the whole input
       |  YAML. [Valentin Lab]
       |
       |  Before this fix, you couldn't ask for ``shyaml get-value`` alone, even
       |  if it makes sense but is completely useless as it returns the whole
       |  YAML input.
       |
       |0.1.2 (2013-03-23)
       |------------------
       |
       |New
       |~~~
       |
       |- Support for list indexes (see README.rst). [Valentin Lab]
       |
       |- Catch exceptions when parsing structure and output a clean error
       |  message. [Valentin Lab]
       |
       |0.1.1 (2013-02-27)
       |------------------
       |
       |Changes
       |~~~~~~~
       |
       |- Doc: some minor enhancements, and an "Install" section. [Valentin Lab]
Keywords: 
Home-page: http://github.com/0k/shyaml
Author: Valentin Lab
Author-email: valentin.lab@kalysto.org
License: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: GNU General Public License (GPL)
Download-URL: UNKNOWN
