=================================
SHYAML: YAML for the command line
=================================
.. image:: https://img.shields.io/pypi/v/shyaml.svg
:target: https://pypi.python.org/pypi/shyaml
.. image:: https://img.shields.io/travis/0k/shyaml/master.svg?style=flat
:target: https://travis-ci.com/github/0k/shyaml/
:alt: Travis CI build status
.. image:: https://img.shields.io/appveyor/ci/vaab/shyaml.svg
:target: https://ci.appveyor.com/project/vaab/shyaml/branch/master
:alt: Appveyor CI build status
.. image:: http://img.shields.io/codecov/c/github/0k/shyaml.svg?style=flat
:target: https://codecov.io/gh/0k/shyaml/
:alt: Test coverage
Description
===========
Simple script 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.
This script supports only read access and it might not support all
the subtleties of YAML specification. But it should support some handy
basic query of YAML file.
Requirements
============
``shyaml`` works in Linux, MacOSX, and Windows with python 2.7 and 3+.
Installation
============
You don't need to download the GIT version of the code as ``shyaml`` is
available on the PyPI. So you should be able to run::
pip install shyaml
If you have downloaded the GIT sources, then you could add install
the current version via::
pip install .
And if you don't have the GIT sources but would like to get the latest
master or branch from github, you could also::
pip install git+https://github.com/0k/shyaml
Or even select a specific revision (branch/tag/commit)::
pip install git+https://github.com/0k/shyaml@master
On macOS, you can also install the latest release version via `Homebrew
<https://github.com/Homebrew/brew/>`_::
brew install shyaml
Or to install the master branch::
brew install shyaml --HEAD
Documentation
=============
The following documented examples are actually tested automatically at
each release for conformance on all platform and python versions.
Please note that there is some subtle benign differences in some
output whether ``shyaml`` is using the ``libyaml`` C implementation or
the full python implementation. The documentation can be run with both
implementation but some examples will fail depending on the
implementation. To make things clear, I'll use some annotation and you
can yourself check which version you are using with::
$ shyaml -V | grep "^libyaml used:" ## docshtest: if-success-set LIBYAML
libyaml used: True
Usage
=====
``shyaml`` takes its YAML input file from standard input ONLY. So let's
define here a common YAML input for the next examples::
$ cat <<EOF > test.yaml
name: "MyName !! héhé" ## using encoding, and support comments !
subvalue:
how-much: 1.1
how-many: 2
things:
- first
- second
- third
maintainer: "Valentin Lab"
description: |
Multiline description:
Line 1
Line 2
subvalue.how-much: 1.2
subvalue.how-much\more: 1.3
subvalue.how-much\.more: 1.4
EOF
General browsing struct and displaying simple values
----------------------------------------------------
Simple query of simple attribute::
$ cat test.yaml | shyaml get-value name
MyName !! héhé
Query nested attributes by using '.' between key labels::
$ 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
Get length of structures or sequences::
$ cat test.yaml | shyaml get-length subvalue
5
$ cat test.yaml | shyaml get-length subvalue.things
3
But this won't work on other types::
$ cat test.yaml | shyaml get-length name
Error: get-length does not support 'str' type. Please provide or select a sequence or struct.
Parse structure
---------------
Get sub YAML from a structure attribute::
$ cat test.yaml | shyaml get-type subvalue
struct
$ cat test.yaml | shyaml get-value subvalue ## docshtest: ignore-if LIBYAML
how-much: 1.1
how-many: 2
things:
- first
- second
- third
maintainer: Valentin Lab
description: 'Multiline description:
Line 1
Line 2
'
Iteration through keys only::
$ cat test.yaml | shyaml keys
name
subvalue
subvalue.how-much
subvalue.how-much\more
subvalue.how-much\.more
Iteration through keys only (``\0`` terminated strings)::
$ cat test.yaml | shyaml keys-0 subvalue | xargs -0 -n 1 echo "VALUE:"
VALUE: how-much
VALUE: how-many
VALUE: things
VALUE: maintainer
VALUE: description
Iteration through values only (``\0`` terminated string highly recommended)::
$ cat test.yaml | shyaml values-0 subvalue |
while IFS='' read -r -d $'\0' value; do
echo "RECEIVED: '$value'"
done
RECEIVED: '1.1'
RECEIVED: '2'
RECEIVED: '- first
- second
- third
'
RECEIVED: 'Valentin Lab'
RECEIVED: 'Multiline description:
Line 1
Line 2
'
Iteration through keys and values (``\0`` terminated string highly recommended)::
$ read-0() {
while [ "$1" ]; do
IFS=$'\0' read -r -d '' "$1" || return 1
shift
done
} &&
cat test.yaml | shyaml key-values-0 subvalue |
while read-0 key value; do
echo "KEY: '$key'"
echo "VALUE: '$value'"
echo
done
KEY: 'how-much'
VALUE: '1.1'
KEY: 'how-many'
VALUE: '2'
KEY: 'things'
VALUE: '- first
- second
- third
'
KEY: 'maintainer'
VALUE: 'Valentin Lab'
KEY: 'description'
VALUE: 'Multiline description:
Line 1
Line 2
'
<BLANKLINE>
Notice, that you'll get the same result using
``get-values``. ``get-values`` will support sequences and struct,
and ``key-values`` support only struct. (for a complete table of
which function support what you can look at the usage line)
And, if you ask for keys, values, key-values on non struct like, you'll
get an error::
$ cat test.yaml | shyaml keys name
Error: keys does not support 'str' type. Please provide or select a struct.
$ cat test.yaml | shyaml values subvalue.how-many
Error: values does not support 'int' type. Please provide or select a struct.
$ cat test.yaml | shyaml key-values subvalue.how-much
Error: key-values does not support 'float' type. Please provide or select a struct.
Parse sequence
--------------
Query a sequence with ``get-value``::
$ cat test.yaml | shyaml get-value subvalue.things
- first
- second
- third
And access individual elements with python-like indexing::
$ 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: invalid path 'subvalue.things.5', index 5 is out of range (3 elements in sequence).
Note that this will work only with integer (preceded or not by a minus
sign)::
$ cat test.yaml | shyaml get-value subvalue.things.foo
Error: invalid path 'subvalue.things.foo', non-integer index 'foo' provided on a sequence.
More usefull, parse a list in one go with ``get-values``::
$ 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 newline char(s) (which is os dependent), this can bring
havoc if you are parsing values containing newlines itself. 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 IFS='' read -r -d '' key &&
IFS='' read -r -d '' value; do
echo "'$key' -> '$value'"
done
'how-much' -> '1.1'
'how-many' -> '2'
'things' -> '- first
- second
- third
'
'maintainer' -> 'Valentin Lab'
'description' -> 'Multiline description:
Line 1
Line 2
'
Please note that, if ``get-values{,-0}`` actually works on ``struct``,
it's maybe more explicit to use the equivalent ``key-values{,0}``. It
should be noted that ``key-values{,0}`` is not completly equivalent as
it is meant to be used with ``struct`` only and will complain if not.
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.
Of course, ``get-values`` should only be called on sequence elements::
$ cat test.yaml | shyaml get-values name
Error: get-values does not support 'str' type. Please provide or select a sequence or struct.
Parse YAML document streams
---------------------------
YAML input can be a stream of documents, the action will then be
applied to each document::
$ i=0; while true; do
((i++))
echo "ingests:"
echo " - data: xxx"
echo " id: tag-$i"
if ((i >= 3)); then
break
fi
echo "---"
done | shyaml get-value ingests.0.id | tr '\0' '&'
tag-1&tag-2&tag-3
Notice that ``NUL`` char is used by default for separating output
iterations if not used in ``-y`` mode. You can use that to separate
each output. ``-y`` mode will use conventional YAML way to separate
documents (which is ``---``).
So::
$ i=0; while true; do
((i++))
echo "ingests:"
echo " - data: xxx"
echo " id: tag-$i"
if ((i >= 3)); then
break
fi
echo "---"
done | shyaml get-value -y ingests.0.id ## docshtest: ignore-if LIBYAML
tag-1
...
---
tag-2
...
---
tag-3
...
Notice that it is not supported to use any query that can output more than one
value (like all the query that can be suffixed with ``*-0``) with a multi-document
YAML::
$ i=0; while true; do
((i++))
echo "ingests:"
echo " - data: xxx"
echo " id: tag-$i"
if ((i >= 3)); then
break
fi
echo "---"
done | shyaml keys ingests.0 >/dev/null
Error: Source YAML is multi-document, which doesn't support any other action than get-type, get-length, get-value
You'll probably notice also, that output seems buffered. The previous
content is displayed as a whole only at the end. If you need a
continuous flow of YAML document, then the command line option ``-L``
is required to force a non-buffered line-by-line reading of the file
so as to ensure that each document is properly parsed as soon as
possible. That means as soon as either a YAML document end is detected
(``---`` or ``EOF``):
Without the ``-L``, if we kill our shyaml process before the end::
$ i=0; while true; do
((i++))
echo "ingests:"
echo " - data: xxx"
echo " id: tag-$i"
if ((i >= 2)); then
break
fi
echo "---"
sleep 10
done 2>/dev/null | shyaml get-value ingests.0.id & pid=$! ; sleep 2; kill $pid
With the ``-L``, if we kill our shyaml process before the end::
$ i=0; while true; do
((i++))
echo "ingests:"
echo " - data: xxx"
echo " id: tag-$i"
if ((i >= 2)); then
break
fi
echo "---"
sleep 10
done 2>/dev/null | shyaml get-value -L ingests.0.id & pid=$! ; sleep 2; kill $pid
tag-1
Using ``-y`` is required to force a YAML output that will be also parseable as a stream,
which could help you chain shyaml calls::
$ i=0; while true; do
((i++))
echo "ingests:"
echo " - data: xxx"
echo " id: tag-$i"
if ((i >= 3)); then
break
fi
echo "---"
sleep 0.2
done | shyaml get-value ingests.0 -L -y | shyaml get-value id | tr '\0' '\n'
tag-1
tag-2
tag-3
An empty string will be still considered as an empty YAML document::
$ echo | shyaml get-value "toto"
Error: invalid path 'toto', can't query subvalue 'toto' of a leaf (leaf value is None).
Keys containing '.'
-------------------
Use and ``\\`` to access keys with ``\`` and ``\.`` to access keys
with literal ``.`` in them. Just be mindful of shell escaping (example
uses single quotes)::
$ cat test.yaml | shyaml get-value 'subvalue\.how-much'
1.2
$ cat test.yaml | shyaml get-value 'subvalue\.how-much\\more'
1.3
$ cat test.yaml | shyaml get-value 'subvalue\.how-much\\.more' default
default
This last one didn't escape correctly the last ``.``, this is the
correct version::
$ cat test.yaml | shyaml get-value 'subvalue\.how-much\\\.more' default
1.4
empty string keys
-----------------
Yep, ``shyaml`` supports empty stringed keys. You might never have use
for this one, but it's in YAML specification. So ``shyaml`` supports
it::
$ cat <<EOF > test.yaml
empty-sub-key:
"":
a: foo
"": bar
"": wiz
EOF
$ cat test.yaml | shyaml get-value empty-sub-key..
bar
$ cat test.yaml | shyaml get-value ''
wiz
Please notice that one empty string is different than no string at all::
$ cat <<EOF > test.yaml
"":
a: foo
b: bar
"x": wiz
EOF
$ cat test.yaml | shyaml keys
x
$ cat test.yaml | shyaml keys ''
a
b
The first asks for keys of the root YAML, the second asks for keys of the
content of the empty string named element located in the root YAML.
Handling missing paths
----------------------
There is a third argument on the command line of shyaml which is the
DEFAULT argument. If the given KEY was not found in the YAML
structure, then ``shyaml`` would return what you provided as DEFAULT.
As of version < 0.3, this argument was defaulted to the empty
string. For all version above 0.3 (included), if not provided, then
an error message will be printed::
$ echo "a: 3" | shyaml get-value a mydefault
3
$ echo "a: 3" | shyaml get-value b mydefault
mydefault
$ echo "a: 3" | shyaml get-value b
Error: invalid path 'b', missing key 'b' in struct.
You can emulate pre v0.3 behavior by specifying explicitly an empty
string as third argument::
$ echo "a: 3" | shyaml get-value b ''
Starting with version 0.6, you can also use the ``-q`` or ``--quiet`` to fail
silently in case of KEY not found in the YAML structure::
$ echo "a: 3" | shyaml -q get-value b; echo "errlvl: $?"
errlvl: 1
$ echo "a: 3" | shyaml -q get-value a; echo "errlvl: $?"
3errlvl: 0
Ordered mappings
----------------
Currently, using ``shyaml`` in a shell script involves happily taking
YAML inputs and outputting YAML outputs that will further be processed.
And this works very well.
Before version ``0.4.0``, ``shyaml`` would boldly re-order (sorting them
alphabetically) the keys in mappings. If this should be considered
harmless per specification (mappings are indeed supposed to be
unordered, this means order does not matter), in practical, YAML users
could feel wronged by ``shyaml`` when there YAML got mangled and they
wanted to give a meaning to the basic YAML mapping.
Who am I to forbid such usage of YAML mappings ? So starting from
version ``0.4.0``, ``shyaml`` will happily keep the order of your
mappings::
$ cat <<EOF > test.yaml
mapping:
a: 1
c: 2
b: 3
EOF
For ``shyaml`` version before ``0.4.0``::
# shyaml get-value mapping < test.yaml
a: 1
b: 3
c: 2
For ``shyaml`` version including and after ``0.4.0``::
$ shyaml get-value mapping < test.yaml
a: 1
c: 2
b: 3
Strict YAML for further processing
----------------------------------
Processing yaml can be done recursively and extensively through using
the output of ``shyaml`` into ``shyaml``. Most of its output is itself
YAML. Most ? Well, for ease of use, literal keys (string, numbers) are
outputed directly without YAML quotes, which is often convenient.
But this has the consequence of introducing inconsistent behavior. So
when processing YAML coming out of shyaml, you should probably think
about using the ``--yaml`` (or ``-y``) option to output only strict YAML.
With the drawback that when you'll want to output string, you'll need to
call a last time ``shyaml get-value`` to explicitly unquote the YAML.
Object Tag
----------
YAML spec allows object tags which allows you to map local data to
objects in your application.
When using ``shyaml``, we do not want to mess with these tags, but still
allow parsing their internal structure.
``get-type`` will correctly give you the type of the object::
$ cat <<EOF > test.yaml
%TAG !e! tag:example.com,2000:app/
---
- !e!foo "bar"
EOF
$ shyaml get-type 0 < test.yaml
tag:example.com,2000:app/foo
``get-value`` with ``-y`` (see section Strict YAML) will give you the
complete yaml tagged value::
$ shyaml get-value -y 0 < test.yaml ## docshtest: ignore-if LIBYAML
!<tag:example.com,2000:app/foo> 'bar'
Another example::
$ cat <<EOF > test.yaml
%TAG ! tag:clarkevans.com,2002:
--- !shape
# Use the ! handle for presenting
# tag:clarkevans.com,2002:circle
- !circle
center: &ORIGIN {x: 73, y: 129}
radius: 7
- !line
start: *ORIGIN
finish: { x: 89, y: 102 }
- !label
start: *ORIGIN
color: 0xFFEEBB
text: Pretty vector drawing.
EOF
$ shyaml get-type 2 < test.yaml
tag:clarkevans.com,2002:label
And you can still traverse internal value::
$ shyaml get-value -y 2.start < test.yaml
x: 73
y: 129
Note that all global tags will be resolved and simplified (as
``!!map``, ``!!str``, ``!!seq``), but not unknown local tags::
$ cat <<EOF > test.yaml
%YAML 1.1
---
!!map {
? !!str "sequence"
: !!seq [ !!str "one", !!str "two" ],
? !!str "mapping"
: !!map {
? !!str "sky" : !myobj "blue",
? !!str "sea" : !!str "green",
},
}
EOF
$ shyaml get-value < test.yaml ## docshtest: ignore-if LIBYAML
sequence:
- one
- two
mapping:
sky: !myobj 'blue'
sea: green
Empty documents
---------------
When provided with an empty document, ``shyaml`` will consider the
document to hold a ``null`` value::
$ echo | shyaml get-value -y ## docshtest: ignore-if LIBYAML
null
...
Usage string
------------
A quick reminder of what is available will be printed when calling
``shyaml`` without any argument::
$ shyaml
Error: Bad number of arguments.
Usage:
shyaml {-h|--help}
shyaml {-V|--version}
shyaml [-y|--yaml] [-q|--quiet] ACTION KEY [DEFAULT]
<BLANKLINE>
The full help is available through the usage of the standard ``-h`` or
``-help``::
$ shyaml --help
Parses and output chosen subpart or values from YAML input.
It reads YAML in stdin and will output on stdout it's return value.
Usage:
shyaml {-h|--help}
shyaml {-V|--version}
shyaml [-y|--yaml] [-q|--quiet] ACTION KEY [DEFAULT]
Options:
-y, --yaml
Output only YAML safe value, more precisely, even
literal values will be YAML quoted. This behavior
is required if you want to output YAML subparts and
further process it. If you know you have are dealing
with safe literal value, then you don't need this.
(Default: no safe YAML output)
-q, --quiet
In case KEY value queried is an invalid path, quiet
mode will prevent the writing of an error message on
standard error.
(Default: no quiet mode)
-L, --line-buffer
Force parsing stdin line by line allowing to process
streamed YAML as it is fed instead of buffering
input and treating several YAML streamed document
at once. This is likely to have some small performance
hit if you have a huge stream of YAML document, but
then you probably don't really care about the
line-buffering.
(Default: no line buffering)
ACTION Depending on the type of data you've targetted
thanks to the KEY, ACTION can be:
These ACTIONs applies to any YAML type:
get-type ## returns a short string
get-value ## returns YAML
These ACTIONs applies to 'sequence' and 'struct' YAML type:
get-values{,-0} ## returns list of YAML
get-length ## returns an integer
These ACTION applies to 'struct' YAML type:
keys{,-0} ## returns list of YAML
values{,-0} ## returns list of YAML
key-values,{,-0} ## returns list of YAML
Note that any value returned is returned on stdout, and
when returning ``list of YAML``, it'll be separated by
a newline or ``NUL`` char depending of you've used the
``-0`` suffixed ACTION.
KEY Identifier to browse and target subvalues into YAML
structure. Use ``.`` to parse a subvalue. If you need
to use a literal ``.`` or ``\``, use ``\`` to quote it.
Use struct keyword to browse ``struct`` YAML data and use
integers to browse ``sequence`` YAML data.
DEFAULT if not provided and given KEY do not match any value in
the provided YAML, then DEFAULT will be returned. If no
default is provided and the KEY do not match any value
in the provided YAML, shyaml will fail with an error
message.
Examples:
## get last grocery
cat recipe.yaml | shyaml get-value groceries.-1
## get all words of my french dictionary
cat dictionaries.yaml | shyaml keys-0 french.dictionary
## get YAML config part of 'myhost'
cat hosts_config.yaml | shyaml get-value cfgs.myhost
<BLANKLINE>
Using invalid keywords will issue an error and the usage message::
$ shyaml get-foo
Error: 'get-foo' is not a valid action.
Usage:
shyaml {-h|--help}
shyaml {-V|--version}
shyaml [-y|--yaml] [-q|--quiet] ACTION KEY [DEFAULT]
<BLANKLINE>
Version information
-------------------
You can get useful information (in case of a bug) or if you want to
check if shyaml is using the ``libyaml`` C bindings, thanks to
``shyaml --version`` (or ``-V``)::
# shyaml -V ## Example of possible output
version: unreleased
PyYAML: 3.13
libyaml available: 0.1.6
libyaml used: True
Python: 2.7.8 (default, Oct 20 2014, 15:05:19) [GCC 4.9.1]
Note that you can force to use the python implementation even if
``libyaml`` is available using ``FORCE_PYTHON_YAML_IMPLEMENTATION``::
$ FORCE_PYTHON_YAML_IMPLEMENTATION=1 shyaml --version | grep "^libyaml used:"
libyaml used: False
Python API
==========
``shyaml`` can be used from within python if you need so::
>>> import shyaml
>>> try:
... from StringIO import StringIO
... except ImportError:
... from io import StringIO
>>> yaml_content = StringIO("""
... a: 1.1
... b:
... x: foo
... y: bar
... """)
>>> for out in shyaml.do(stream=yaml_content,
... action="get-type",
... key="a"):
... print(repr(out))
'float'
Please note that ``shyaml.do(..)`` outputs a generator iterating
through all the yaml documents of the stream. In most usage case,
you'll have only one document.
You can have a peek at the code, the ``do(..)`` function has a documented
prototype.
Contributing
============
Any suggestion or issue is welcome. Push request are very welcome,
please check out the guidelines.
Push Request Guidelines
-----------------------
You can send any code. I'll look at it and will integrate it myself in
the code base and leave you as the author. This process can take time and
it'll take less time if you follow the following guidelines:
- check your code with PEP8 or pylint. Try to stick to 80 columns wide.
- separate your commits per smallest concern.
- each commit should pass the tests (to allow easy bisect)
- each functionality/bugfix commit should contain the code, tests,
and doc.
- prior minor commit with typographic or code cosmetic changes are
very welcome. These should be tagged in their commit summary with
``!minor``.
- the commit message should follow gitchangelog rules (check the git
log to get examples)
- if the commit fixes an issue or finished the implementation of a
feature, please mention it in the summary.
If you have some questions about guidelines which is not answered here,
please check the current ``git log``, you might find previous commit that
would show you how to deal with your issue.
License
=======
Copyright (c) 2020 Valentin Lab.
Licensed under the `BSD License`_.
.. _BSD License: http://raw.github.com/0k/shyaml/master/LICENSE
Changelog
=========
0.6.2 (2020-12-15)
------------------
Fix
~~~
- UTF-8 values would end in tracebacks (fixes #51) [Valentin Lab]
0.6.1 (2018-12-14)
------------------
New
~~~
- Added ``-V|--version`` shyaml command line option to get full version
information. [Valentin Lab]
This includes ``shyaml``'s version, but also PyYAML version installed,
and availability of the C libyaml bindings, and if they are used.
Fix
~~~
- Document behavior on empty input. [Valentin Lab]
0.6.0 (2018-12-13)
------------------
New
~~~
- Python 3.7 compatibility. [Valentin Lab]
- Support YAML streams (fixes #32) [Valentin Lab]
- ``shyaml`` can now be used from within python. [Valentin Lab]
You can import ``shyaml`` and launch inner function in a python
program thanks to accessible API.
- ``-q`` or ``--quiet`` to avoid printing error message on missing
paths. (fix #14) [Valentin Lab]
- Full support of yaml tags (fix #40) [Valentin Lab]
Changes
~~~~~~~
- Finish to document all behaviors. [Valentin Lab]
Fix
~~~
- Script was not installed correctly on windows. (fix #38) [Valentin
Lab]
- Python 3 incompatible code removed in ``get-values{,-0}``. [Valentin
Lab]
- Use C yaml implementation from ``libyaml`` when available (fix #3)
[Valentin Lab]
0.5.2 (2018-04-25)
------------------
Fix
~~~
- Missing doc about ``get-length`` and typo corrected in help message.
[Valentin Lab]
- Python 3.0 exception when querying for missing keys removed. (fix #34)
[Valentin Lab]
0.5.1 (2018-03-06)
------------------
New
~~~
- Add ``requirements`` section. [Valentin Lab]
- Add command ``get-length`` for structures or sequences (closes #25,
fixes #20) [gt3389b]
Fix
~~~
- Add homebrew installation instructions. [Zhiming Wang]
- Using ``-y`` with no argument casted an exception instead of
displaying usage. (fixes #41) [Valentin Lab]
0.5.0 (2017-03-23)
------------------
New
~~~
- Introduce ``-y`` option to force full yaml output. [Valentin Lab]
By default, output of literal string where directly printed unquoted and
useable. If this is very useful, there are many cases where this is not
consistent and is ambiguous, especially when this string is itself a
YAML representation.
This could actually lead to subtle bugs occuring when re-using
``shyaml`` output for further parsing.
So if you want unquoted literal types to further process these elements,
use ``-y``. If you expect a string and wan't it plain raw, avoid ``-y``.
0.4.2 (2017-02-08)
------------------
Fix
~~~
- ``<<:`` YAML merging facility support. [Valentin Lab]
0.4.1 (2016-08-29)
------------------
Fix
~~~
- On python2, unicode strings would be displayed literaly (fixes #26).
[Valentin Lab]
``str`` is not the correct type to match all type of strings in python
2. So unicode strings (usually produced thanks to accentuated
characters) would be printed quoted (the python representation).
0.4.0 (2016-01-11)
------------------
New
~~~
- Avoid reordering mapping keys in the output. [Valentin Lab]
Several commands from ``shyaml`` will output YAML themselves. But in the
process, the whole content is parsed and re-dumped. This can lead to
differences with the original inputs. The ordering of keys can be
annoying in some use cases, even if, well mappings should not be
ordered, these are ordered by the sequential nature of a file, and using
'omap' is often tedious. ``shyaml`` now keep the original order the keys
were met.
0.3.4 (2015-03-06)
------------------
New
~~~
- Added a nice ``--help`` doc. [Valentin Lab]
- Added ``key-values{,-0}`` argument to get key and values in one go.
[Valentin Lab]
- Error is casted if no default specified and the key is not existent.
[Valentin Lab]
Changes
~~~~~~~
- Be more informative in some key related error message. (fixed #7)
[Valentin Lab]
0.2.2 (2014-03-19)
------------------
Fix
~~~
- No argument at all was treated as one empty string argument. Thx Yassa
Bb. (fixes #6) [Valentin Lab]
0.2.1 (2013-11-23)
------------------
New
~~~
- Python3 support. [Valentin Lab]
Fix
~~~
- Keys can now be empty or contains dots ``.`` if they are properly
escaped (fixes #5, thanks to Daniel Giribet) [Daniel Giribet]
0.2.0 (2013-05-03)
------------------
New
~~~
- Support for iteration in sequence and struct in one go. [Valentin Lab]
Fix
~~~
- Forgot to mention ``./autogen.sh`` execution when getting the code
from git, and be more clear about other means of installation.
[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
~~~~~~~
- Some minor enhancements, and an "Install" section. [Valentin Lab]
0.1.0 (2013-02-27)
------------------
- First import. [Valentin Lab]
Raw data
{
"_id": null,
"home_page": "http://github.com/0k/shyaml",
"name": "shyaml",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "",
"author": "Valentin Lab",
"author_email": "valentin.lab@kalysto.org",
"download_url": "https://files.pythonhosted.org/packages/b9/59/7e6873fa73a476de053041d26d112b65d7e1e480b88a93b4baa77197bd04/shyaml-0.6.2.tar.gz",
"platform": "",
"description": "=================================\nSHYAML: YAML for the command line\n=================================\n\n.. image:: https://img.shields.io/pypi/v/shyaml.svg\n :target: https://pypi.python.org/pypi/shyaml\n\n.. image:: https://img.shields.io/travis/0k/shyaml/master.svg?style=flat\n :target: https://travis-ci.com/github/0k/shyaml/\n :alt: Travis CI build status\n\n.. image:: https://img.shields.io/appveyor/ci/vaab/shyaml.svg\n :target: https://ci.appveyor.com/project/vaab/shyaml/branch/master\n :alt: Appveyor CI build status\n\n.. image:: http://img.shields.io/codecov/c/github/0k/shyaml.svg?style=flat\n :target: https://codecov.io/gh/0k/shyaml/\n :alt: Test coverage\n\n\n\nDescription\n===========\n\nSimple script that allow read access to YAML files through command line.\n\nThis can be handy, if you want to get access to YAML data in your shell\nscripts.\n\nThis script supports only read access and it might not support all\nthe subtleties of YAML specification. But it should support some handy\nbasic query of YAML file.\n\n\nRequirements\n============\n\n``shyaml`` works in Linux, MacOSX, and Windows with python 2.7 and 3+.\n\n\nInstallation\n============\n\nYou don't need to download the GIT version of the code as ``shyaml`` is\navailable on the PyPI. So you should be able to run::\n\n pip install shyaml\n\nIf you have downloaded the GIT sources, then you could add install\nthe current version via::\n\n pip install .\n\nAnd if you don't have the GIT sources but would like to get the latest\nmaster or branch from github, you could also::\n\n pip install git+https://github.com/0k/shyaml\n\nOr even select a specific revision (branch/tag/commit)::\n\n pip install git+https://github.com/0k/shyaml@master\n\nOn macOS, you can also install the latest release version via `Homebrew\n<https://github.com/Homebrew/brew/>`_::\n\n brew install shyaml\n\nOr to install the master branch::\n\n brew install shyaml --HEAD\n\n\nDocumentation\n=============\n\nThe following documented examples are actually tested automatically at\neach release for conformance on all platform and python versions.\n\nPlease note that there is some subtle benign differences in some\noutput whether ``shyaml`` is using the ``libyaml`` C implementation or\nthe full python implementation. The documentation can be run with both\nimplementation but some examples will fail depending on the\nimplementation. To make things clear, I'll use some annotation and you\ncan yourself check which version you are using with::\n\n $ shyaml -V | grep \"^libyaml used:\" ## docshtest: if-success-set LIBYAML\n libyaml used: True\n\n\nUsage\n=====\n\n``shyaml`` takes its YAML input file from standard input ONLY. So let's\ndefine here a common YAML input for the next examples::\n\n $ cat <<EOF > test.yaml\n name: \"MyName !! h\u00e9h\u00e9\" ## using encoding, and support comments !\n subvalue:\n how-much: 1.1\n how-many: 2\n things:\n - first\n - second\n - third\n maintainer: \"Valentin Lab\"\n description: |\n Multiline description:\n Line 1\n Line 2\n subvalue.how-much: 1.2\n subvalue.how-much\\more: 1.3\n subvalue.how-much\\.more: 1.4\n EOF\n\n\nGeneral browsing struct and displaying simple values\n----------------------------------------------------\n\nSimple query of simple attribute::\n\n $ cat test.yaml | shyaml get-value name\n MyName !! h\u00e9h\u00e9\n\nQuery nested attributes by using '.' between key labels::\n\n $ cat test.yaml | shyaml get-value subvalue.how-much\n 1.1\n\nGet type of attributes::\n\n $ cat test.yaml | shyaml get-type name\n str\n $ cat test.yaml | shyaml get-type subvalue.how-much\n float\n\nGet length of structures or sequences::\n\n $ cat test.yaml | shyaml get-length subvalue\n 5\n $ cat test.yaml | shyaml get-length subvalue.things\n 3\n\nBut this won't work on other types::\n\n $ cat test.yaml | shyaml get-length name\n Error: get-length does not support 'str' type. Please provide or select a sequence or struct.\n\n\nParse structure\n---------------\n\nGet sub YAML from a structure attribute::\n\n $ cat test.yaml | shyaml get-type subvalue\n struct\n $ cat test.yaml | shyaml get-value subvalue ## docshtest: ignore-if LIBYAML\n how-much: 1.1\n how-many: 2\n things:\n - first\n - second\n - third\n maintainer: Valentin Lab\n description: 'Multiline description:\n\n Line 1\n\n Line 2\n\n '\n\nIteration through keys only::\n\n $ cat test.yaml | shyaml keys\n name\n subvalue\n subvalue.how-much\n subvalue.how-much\\more\n subvalue.how-much\\.more\n\nIteration through keys only (``\\0`` terminated strings)::\n\n $ cat test.yaml | shyaml keys-0 subvalue | xargs -0 -n 1 echo \"VALUE:\"\n VALUE: how-much\n VALUE: how-many\n VALUE: things\n VALUE: maintainer\n VALUE: description\n\nIteration through values only (``\\0`` terminated string highly recommended)::\n\n $ cat test.yaml | shyaml values-0 subvalue |\n while IFS='' read -r -d $'\\0' value; do\n echo \"RECEIVED: '$value'\"\n done\n RECEIVED: '1.1'\n RECEIVED: '2'\n RECEIVED: '- first\n - second\n - third\n '\n RECEIVED: 'Valentin Lab'\n RECEIVED: 'Multiline description:\n Line 1\n Line 2\n '\n\nIteration through keys and values (``\\0`` terminated string highly recommended)::\n\n $ read-0() {\n while [ \"$1\" ]; do\n IFS=$'\\0' read -r -d '' \"$1\" || return 1\n shift\n done\n } &&\n cat test.yaml | shyaml key-values-0 subvalue |\n while read-0 key value; do\n echo \"KEY: '$key'\"\n echo \"VALUE: '$value'\"\n echo\n done\n KEY: 'how-much'\n VALUE: '1.1'\n\n KEY: 'how-many'\n VALUE: '2'\n\n KEY: 'things'\n VALUE: '- first\n - second\n - third\n '\n\n KEY: 'maintainer'\n VALUE: 'Valentin Lab'\n\n KEY: 'description'\n VALUE: 'Multiline description:\n Line 1\n Line 2\n '\n <BLANKLINE>\n\nNotice, that you'll get the same result using\n``get-values``. ``get-values`` will support sequences and struct,\nand ``key-values`` support only struct. (for a complete table of\nwhich function support what you can look at the usage line)\n\nAnd, if you ask for keys, values, key-values on non struct like, you'll\nget an error::\n\n $ cat test.yaml | shyaml keys name\n Error: keys does not support 'str' type. Please provide or select a struct.\n $ cat test.yaml | shyaml values subvalue.how-many\n Error: values does not support 'int' type. Please provide or select a struct.\n $ cat test.yaml | shyaml key-values subvalue.how-much\n Error: key-values does not support 'float' type. Please provide or select a struct.\n\n\nParse sequence\n--------------\n\nQuery a sequence with ``get-value``::\n\n $ cat test.yaml | shyaml get-value subvalue.things\n - first\n - second\n - third\n\nAnd access individual elements with python-like indexing::\n\n $ cat test.yaml | shyaml get-value subvalue.things.0\n first\n $ cat test.yaml | shyaml get-value subvalue.things.-1\n third\n $ cat test.yaml | shyaml get-value subvalue.things.5\n Error: invalid path 'subvalue.things.5', index 5 is out of range (3 elements in sequence).\n\nNote that this will work only with integer (preceded or not by a minus\nsign)::\n\n $ cat test.yaml | shyaml get-value subvalue.things.foo\n Error: invalid path 'subvalue.things.foo', non-integer index 'foo' provided on a sequence.\n\nMore usefull, parse a list in one go with ``get-values``::\n\n $ cat test.yaml | shyaml get-values subvalue.things\n first\n second\n third\n\nNote that the action is called ``get-values``, and that output is\nseparated by newline char(s) (which is os dependent), this can bring\nhavoc if you are parsing values containing newlines itself. Hopefully,\n``shyaml`` has a ``get-values-0`` to terminate strings by ``\\0`` char,\nwhich allows complete support of any type of values, including YAML.\n``get-values`` outputs key and values for ``struct`` types and only\nvalues for ``sequence`` types::\n\n $ cat test.yaml | shyaml get-values-0 subvalue |\n while IFS='' read -r -d '' key &&\n IFS='' read -r -d '' value; do\n echo \"'$key' -> '$value'\"\n done\n 'how-much' -> '1.1'\n 'how-many' -> '2'\n 'things' -> '- first\n - second\n - third\n '\n 'maintainer' -> 'Valentin Lab'\n 'description' -> 'Multiline description:\n Line 1\n Line 2\n '\n\nPlease note that, if ``get-values{,-0}`` actually works on ``struct``,\nit's maybe more explicit to use the equivalent ``key-values{,0}``. It\nshould be noted that ``key-values{,0}`` is not completly equivalent as\nit is meant to be used with ``struct`` only and will complain if not.\n\nYou should also notice that values that are displayed are YAML compatible. So\nif they are complex, you can re-use ``shyaml`` on them to parse their content.\n\nOf course, ``get-values`` should only be called on sequence elements::\n\n $ cat test.yaml | shyaml get-values name\n Error: get-values does not support 'str' type. Please provide or select a sequence or struct.\n\n\nParse YAML document streams\n---------------------------\n\nYAML input can be a stream of documents, the action will then be\napplied to each document::\n\n $ i=0; while true; do\n ((i++))\n echo \"ingests:\"\n echo \" - data: xxx\"\n echo \" id: tag-$i\"\n if ((i >= 3)); then\n break\n fi\n echo \"---\"\n done | shyaml get-value ingests.0.id | tr '\\0' '&'\n tag-1&tag-2&tag-3\n\n\nNotice that ``NUL`` char is used by default for separating output\niterations if not used in ``-y`` mode. You can use that to separate\neach output. ``-y`` mode will use conventional YAML way to separate\ndocuments (which is ``---``).\n\nSo::\n\n $ i=0; while true; do\n ((i++))\n echo \"ingests:\"\n echo \" - data: xxx\"\n echo \" id: tag-$i\"\n if ((i >= 3)); then\n break\n fi\n echo \"---\"\n done | shyaml get-value -y ingests.0.id ## docshtest: ignore-if LIBYAML\n tag-1\n ...\n ---\n tag-2\n ...\n ---\n tag-3\n ...\n\nNotice that it is not supported to use any query that can output more than one\nvalue (like all the query that can be suffixed with ``*-0``) with a multi-document\nYAML::\n\n $ i=0; while true; do\n ((i++))\n echo \"ingests:\"\n echo \" - data: xxx\"\n echo \" id: tag-$i\"\n if ((i >= 3)); then\n break\n fi\n echo \"---\"\n done | shyaml keys ingests.0 >/dev/null\n Error: Source YAML is multi-document, which doesn't support any other action than get-type, get-length, get-value\n\nYou'll probably notice also, that output seems buffered. The previous\ncontent is displayed as a whole only at the end. If you need a\ncontinuous flow of YAML document, then the command line option ``-L``\nis required to force a non-buffered line-by-line reading of the file\nso as to ensure that each document is properly parsed as soon as\npossible. That means as soon as either a YAML document end is detected\n(``---`` or ``EOF``):\n\nWithout the ``-L``, if we kill our shyaml process before the end::\n\n $ i=0; while true; do\n ((i++))\n echo \"ingests:\"\n echo \" - data: xxx\"\n echo \" id: tag-$i\"\n if ((i >= 2)); then\n break\n fi\n echo \"---\"\n sleep 10\n done 2>/dev/null | shyaml get-value ingests.0.id & pid=$! ; sleep 2; kill $pid\n\n\nWith the ``-L``, if we kill our shyaml process before the end::\n\n $ i=0; while true; do\n ((i++))\n echo \"ingests:\"\n echo \" - data: xxx\"\n echo \" id: tag-$i\"\n if ((i >= 2)); then\n break\n fi\n echo \"---\"\n sleep 10\n done 2>/dev/null | shyaml get-value -L ingests.0.id & pid=$! ; sleep 2; kill $pid\n tag-1\n\n\nUsing ``-y`` is required to force a YAML output that will be also parseable as a stream,\nwhich could help you chain shyaml calls::\n\n $ i=0; while true; do\n ((i++))\n echo \"ingests:\"\n echo \" - data: xxx\"\n echo \" id: tag-$i\"\n if ((i >= 3)); then\n break\n fi\n echo \"---\"\n sleep 0.2\n done | shyaml get-value ingests.0 -L -y | shyaml get-value id | tr '\\0' '\\n'\n tag-1\n tag-2\n tag-3\n\n\nAn empty string will be still considered as an empty YAML document::\n\n $ echo | shyaml get-value \"toto\"\n Error: invalid path 'toto', can't query subvalue 'toto' of a leaf (leaf value is None).\n\n\nKeys containing '.'\n-------------------\n\nUse and ``\\\\`` to access keys with ``\\`` and ``\\.`` to access keys\nwith literal ``.`` in them. Just be mindful of shell escaping (example\nuses single quotes)::\n\n $ cat test.yaml | shyaml get-value 'subvalue\\.how-much'\n 1.2\n $ cat test.yaml | shyaml get-value 'subvalue\\.how-much\\\\more'\n 1.3\n $ cat test.yaml | shyaml get-value 'subvalue\\.how-much\\\\.more' default\n default\n\nThis last one didn't escape correctly the last ``.``, this is the\ncorrect version::\n\n $ cat test.yaml | shyaml get-value 'subvalue\\.how-much\\\\\\.more' default\n 1.4\n\n\nempty string keys\n-----------------\n\nYep, ``shyaml`` supports empty stringed keys. You might never have use\nfor this one, but it's in YAML specification. So ``shyaml`` supports\nit::\n\n $ cat <<EOF > test.yaml\n empty-sub-key:\n \"\":\n a: foo\n \"\": bar\n \"\": wiz\n EOF\n\n $ cat test.yaml | shyaml get-value empty-sub-key..\n bar\n $ cat test.yaml | shyaml get-value ''\n wiz\n\nPlease notice that one empty string is different than no string at all::\n\n $ cat <<EOF > test.yaml\n \"\":\n a: foo\n b: bar\n \"x\": wiz\n EOF\n $ cat test.yaml | shyaml keys\n\n x\n $ cat test.yaml | shyaml keys ''\n a\n b\n\nThe first asks for keys of the root YAML, the second asks for keys of the\ncontent of the empty string named element located in the root YAML.\n\n\nHandling missing paths\n----------------------\n\nThere is a third argument on the command line of shyaml which is the\nDEFAULT argument. If the given KEY was not found in the YAML\nstructure, then ``shyaml`` would return what you provided as DEFAULT.\n\nAs of version < 0.3, this argument was defaulted to the empty\nstring. For all version above 0.3 (included), if not provided, then\nan error message will be printed::\n\n $ echo \"a: 3\" | shyaml get-value a mydefault\n 3\n\n $ echo \"a: 3\" | shyaml get-value b mydefault\n mydefault\n\n $ echo \"a: 3\" | shyaml get-value b\n Error: invalid path 'b', missing key 'b' in struct.\n\nYou can emulate pre v0.3 behavior by specifying explicitly an empty\nstring as third argument::\n\n $ echo \"a: 3\" | shyaml get-value b ''\n\nStarting with version 0.6, you can also use the ``-q`` or ``--quiet`` to fail\nsilently in case of KEY not found in the YAML structure::\n\n $ echo \"a: 3\" | shyaml -q get-value b; echo \"errlvl: $?\"\n errlvl: 1\n $ echo \"a: 3\" | shyaml -q get-value a; echo \"errlvl: $?\"\n 3errlvl: 0\n\n\nOrdered mappings\n----------------\n\nCurrently, using ``shyaml`` in a shell script involves happily taking\nYAML inputs and outputting YAML outputs that will further be processed.\n\nAnd this works very well.\n\nBefore version ``0.4.0``, ``shyaml`` would boldly re-order (sorting them\nalphabetically) the keys in mappings. If this should be considered\nharmless per specification (mappings are indeed supposed to be\nunordered, this means order does not matter), in practical, YAML users\ncould feel wronged by ``shyaml`` when there YAML got mangled and they\nwanted to give a meaning to the basic YAML mapping.\n\nWho am I to forbid such usage of YAML mappings ? So starting from\nversion ``0.4.0``, ``shyaml`` will happily keep the order of your\nmappings::\n\n $ cat <<EOF > test.yaml\n mapping:\n a: 1\n c: 2\n b: 3\n EOF\n\nFor ``shyaml`` version before ``0.4.0``::\n\n # shyaml get-value mapping < test.yaml\n a: 1\n b: 3\n c: 2\n\nFor ``shyaml`` version including and after ``0.4.0``::\n\n $ shyaml get-value mapping < test.yaml\n a: 1\n c: 2\n b: 3\n\n\nStrict YAML for further processing\n----------------------------------\n\nProcessing yaml can be done recursively and extensively through using\nthe output of ``shyaml`` into ``shyaml``. Most of its output is itself\nYAML. Most ? Well, for ease of use, literal keys (string, numbers) are\noutputed directly without YAML quotes, which is often convenient.\n\nBut this has the consequence of introducing inconsistent behavior. So\nwhen processing YAML coming out of shyaml, you should probably think\nabout using the ``--yaml`` (or ``-y``) option to output only strict YAML.\n\nWith the drawback that when you'll want to output string, you'll need to\ncall a last time ``shyaml get-value`` to explicitly unquote the YAML.\n\n\nObject Tag\n----------\n\nYAML spec allows object tags which allows you to map local data to\nobjects in your application.\n\nWhen using ``shyaml``, we do not want to mess with these tags, but still\nallow parsing their internal structure.\n\n``get-type`` will correctly give you the type of the object::\n\n $ cat <<EOF > test.yaml\n %TAG !e! tag:example.com,2000:app/\n ---\n - !e!foo \"bar\"\n EOF\n\n $ shyaml get-type 0 < test.yaml\n tag:example.com,2000:app/foo\n\n``get-value`` with ``-y`` (see section Strict YAML) will give you the\ncomplete yaml tagged value::\n\n $ shyaml get-value -y 0 < test.yaml ## docshtest: ignore-if LIBYAML\n !<tag:example.com,2000:app/foo> 'bar'\n\n\nAnother example::\n\n $ cat <<EOF > test.yaml\n %TAG ! tag:clarkevans.com,2002:\n --- !shape\n # Use the ! handle for presenting\n # tag:clarkevans.com,2002:circle\n - !circle\n center: &ORIGIN {x: 73, y: 129}\n radius: 7\n - !line\n start: *ORIGIN\n finish: { x: 89, y: 102 }\n - !label\n start: *ORIGIN\n color: 0xFFEEBB\n text: Pretty vector drawing.\n EOF\n $ shyaml get-type 2 < test.yaml\n tag:clarkevans.com,2002:label\n\nAnd you can still traverse internal value::\n\n $ shyaml get-value -y 2.start < test.yaml\n x: 73\n y: 129\n\n\nNote that all global tags will be resolved and simplified (as\n``!!map``, ``!!str``, ``!!seq``), but not unknown local tags::\n\n $ cat <<EOF > test.yaml\n %YAML 1.1\n ---\n !!map {\n ? !!str \"sequence\"\n : !!seq [ !!str \"one\", !!str \"two\" ],\n ? !!str \"mapping\"\n : !!map {\n ? !!str \"sky\" : !myobj \"blue\",\n ? !!str \"sea\" : !!str \"green\",\n },\n }\n EOF\n\n $ shyaml get-value < test.yaml ## docshtest: ignore-if LIBYAML\n sequence:\n - one\n - two\n mapping:\n sky: !myobj 'blue'\n sea: green\n\n\nEmpty documents\n---------------\n\nWhen provided with an empty document, ``shyaml`` will consider the\ndocument to hold a ``null`` value::\n\n $ echo | shyaml get-value -y ## docshtest: ignore-if LIBYAML\n null\n ...\n\n\nUsage string\n------------\n\nA quick reminder of what is available will be printed when calling\n``shyaml`` without any argument::\n\n $ shyaml\n Error: Bad number of arguments.\n Usage:\n\n shyaml {-h|--help}\n shyaml {-V|--version}\n shyaml [-y|--yaml] [-q|--quiet] ACTION KEY [DEFAULT]\n <BLANKLINE>\n\nThe full help is available through the usage of the standard ``-h`` or\n``-help``::\n\n\n $ shyaml --help\n\n Parses and output chosen subpart or values from YAML input.\n It reads YAML in stdin and will output on stdout it's return value.\n\n Usage:\n\n shyaml {-h|--help}\n shyaml {-V|--version}\n shyaml [-y|--yaml] [-q|--quiet] ACTION KEY [DEFAULT]\n\n\n Options:\n\n -y, --yaml\n Output only YAML safe value, more precisely, even\n literal values will be YAML quoted. This behavior\n is required if you want to output YAML subparts and\n further process it. If you know you have are dealing\n with safe literal value, then you don't need this.\n (Default: no safe YAML output)\n\n -q, --quiet\n In case KEY value queried is an invalid path, quiet\n mode will prevent the writing of an error message on\n standard error.\n (Default: no quiet mode)\n\n -L, --line-buffer\n Force parsing stdin line by line allowing to process\n streamed YAML as it is fed instead of buffering\n input and treating several YAML streamed document\n at once. This is likely to have some small performance\n hit if you have a huge stream of YAML document, but\n then you probably don't really care about the\n line-buffering.\n (Default: no line buffering)\n\n ACTION Depending on the type of data you've targetted\n thanks to the KEY, ACTION can be:\n\n These ACTIONs applies to any YAML type:\n\n get-type ## returns a short string\n get-value ## returns YAML\n\n These ACTIONs applies to 'sequence' and 'struct' YAML type:\n\n get-values{,-0} ## returns list of YAML\n get-length ## returns an integer\n\n These ACTION applies to 'struct' YAML type:\n\n keys{,-0} ## returns list of YAML\n values{,-0} ## returns list of YAML\n key-values,{,-0} ## returns list of YAML\n\n Note that any value returned is returned on stdout, and\n when returning ``list of YAML``, it'll be separated by\n a newline or ``NUL`` char depending of you've used the\n ``-0`` suffixed ACTION.\n\n KEY Identifier to browse and target subvalues into YAML\n structure. Use ``.`` to parse a subvalue. If you need\n to use a literal ``.`` or ``\\``, use ``\\`` to quote it.\n\n Use struct keyword to browse ``struct`` YAML data and use\n integers to browse ``sequence`` YAML data.\n\n DEFAULT if not provided and given KEY do not match any value in\n the provided YAML, then DEFAULT will be returned. If no\n default is provided and the KEY do not match any value\n in the provided YAML, shyaml will fail with an error\n message.\n\n Examples:\n\n ## get last grocery\n cat recipe.yaml | shyaml get-value groceries.-1\n\n ## get all words of my french dictionary\n cat dictionaries.yaml | shyaml keys-0 french.dictionary\n\n ## get YAML config part of 'myhost'\n cat hosts_config.yaml | shyaml get-value cfgs.myhost\n\n <BLANKLINE>\n\nUsing invalid keywords will issue an error and the usage message::\n\n $ shyaml get-foo\n Error: 'get-foo' is not a valid action.\n Usage:\n\n shyaml {-h|--help}\n shyaml {-V|--version}\n shyaml [-y|--yaml] [-q|--quiet] ACTION KEY [DEFAULT]\n <BLANKLINE>\n\n\nVersion information\n-------------------\n\nYou can get useful information (in case of a bug) or if you want to\ncheck if shyaml is using the ``libyaml`` C bindings, thanks to\n``shyaml --version`` (or ``-V``)::\n\n # shyaml -V ## Example of possible output\n version: unreleased\n PyYAML: 3.13\n libyaml available: 0.1.6\n libyaml used: True\n Python: 2.7.8 (default, Oct 20 2014, 15:05:19) [GCC 4.9.1]\n\nNote that you can force to use the python implementation even if\n``libyaml`` is available using ``FORCE_PYTHON_YAML_IMPLEMENTATION``::\n\n $ FORCE_PYTHON_YAML_IMPLEMENTATION=1 shyaml --version | grep \"^libyaml used:\"\n libyaml used: False\n\n\nPython API\n==========\n\n``shyaml`` can be used from within python if you need so::\n\n >>> import shyaml\n >>> try:\n ... from StringIO import StringIO\n ... except ImportError:\n ... from io import StringIO\n\n >>> yaml_content = StringIO(\"\"\"\n ... a: 1.1\n ... b:\n ... x: foo\n ... y: bar\n ... \"\"\")\n\n >>> for out in shyaml.do(stream=yaml_content,\n ... action=\"get-type\",\n ... key=\"a\"):\n ... print(repr(out))\n 'float'\n\nPlease note that ``shyaml.do(..)`` outputs a generator iterating\nthrough all the yaml documents of the stream. In most usage case,\nyou'll have only one document.\n\nYou can have a peek at the code, the ``do(..)`` function has a documented\nprototype.\n\n\nContributing\n============\n\nAny suggestion or issue is welcome. Push request are very welcome,\nplease check out the guidelines.\n\n\nPush Request Guidelines\n-----------------------\n\nYou can send any code. I'll look at it and will integrate it myself in\nthe code base and leave you as the author. This process can take time and\nit'll take less time if you follow the following guidelines:\n\n- check your code with PEP8 or pylint. Try to stick to 80 columns wide.\n- separate your commits per smallest concern.\n- each commit should pass the tests (to allow easy bisect)\n- each functionality/bugfix commit should contain the code, tests,\n and doc.\n- prior minor commit with typographic or code cosmetic changes are\n very welcome. These should be tagged in their commit summary with\n ``!minor``.\n- the commit message should follow gitchangelog rules (check the git\n log to get examples)\n- if the commit fixes an issue or finished the implementation of a\n feature, please mention it in the summary.\n\nIf you have some questions about guidelines which is not answered here,\nplease check the current ``git log``, you might find previous commit that\nwould show you how to deal with your issue.\n\n\nLicense\n=======\n\nCopyright (c) 2020 Valentin Lab.\n\nLicensed under the `BSD License`_.\n\n.. _BSD License: http://raw.github.com/0k/shyaml/master/LICENSE\n\nChangelog\n=========\n\n\n0.6.2 (2020-12-15)\n------------------\n\nFix\n~~~\n- UTF-8 values would end in tracebacks (fixes #51) [Valentin Lab]\n\n\n0.6.1 (2018-12-14)\n------------------\n\nNew\n~~~\n- Added ``-V|--version`` shyaml command line option to get full version\n information. [Valentin Lab]\n\n This includes ``shyaml``'s version, but also PyYAML version installed,\n and availability of the C libyaml bindings, and if they are used.\n\n\nFix\n~~~\n- Document behavior on empty input. [Valentin Lab]\n\n\n0.6.0 (2018-12-13)\n------------------\n\nNew\n~~~\n- Python 3.7 compatibility. [Valentin Lab]\n- Support YAML streams (fixes #32) [Valentin Lab]\n- ``shyaml`` can now be used from within python. [Valentin Lab]\n\n You can import ``shyaml`` and launch inner function in a python\n program thanks to accessible API.\n\n- ``-q`` or ``--quiet`` to avoid printing error message on missing\n paths. (fix #14) [Valentin Lab]\n- Full support of yaml tags (fix #40) [Valentin Lab]\n\nChanges\n~~~~~~~\n- Finish to document all behaviors. [Valentin Lab]\n\nFix\n~~~\n- Script was not installed correctly on windows. (fix #38) [Valentin\n Lab]\n- Python 3 incompatible code removed in ``get-values{,-0}``. [Valentin\n Lab]\n- Use C yaml implementation from ``libyaml`` when available (fix #3)\n [Valentin Lab]\n\n\n0.5.2 (2018-04-25)\n------------------\n\nFix\n~~~\n- Missing doc about ``get-length`` and typo corrected in help message.\n [Valentin Lab]\n- Python 3.0 exception when querying for missing keys removed. (fix #34)\n [Valentin Lab]\n\n\n0.5.1 (2018-03-06)\n------------------\n\nNew\n~~~\n- Add ``requirements`` section. [Valentin Lab]\n- Add command ``get-length`` for structures or sequences (closes #25,\n fixes #20) [gt3389b]\n\nFix\n~~~\n- Add homebrew installation instructions. [Zhiming Wang]\n- Using ``-y`` with no argument casted an exception instead of\n displaying usage. (fixes #41) [Valentin Lab]\n\n\n0.5.0 (2017-03-23)\n------------------\n\nNew\n~~~\n- Introduce ``-y`` option to force full yaml output. [Valentin Lab]\n\n By default, output of literal string where directly printed unquoted and\n useable. If this is very useful, there are many cases where this is not\n consistent and is ambiguous, especially when this string is itself a\n YAML representation.\n\n This could actually lead to subtle bugs occuring when re-using\n ``shyaml`` output for further parsing.\n\n So if you want unquoted literal types to further process these elements,\n use ``-y``. If you expect a string and wan't it plain raw, avoid ``-y``.\n\n\n\n0.4.2 (2017-02-08)\n------------------\n\nFix\n~~~\n- ``<<:`` YAML merging facility support. [Valentin Lab]\n\n\n0.4.1 (2016-08-29)\n------------------\n\nFix\n~~~\n- On python2, unicode strings would be displayed literaly (fixes #26).\n [Valentin Lab]\n\n ``str`` is not the correct type to match all type of strings in python\n 2. So unicode strings (usually produced thanks to accentuated\n characters) would be printed quoted (the python representation).\n\n\n\n0.4.0 (2016-01-11)\n------------------\n\nNew\n~~~\n- Avoid reordering mapping keys in the output. [Valentin Lab]\n\n Several commands from ``shyaml`` will output YAML themselves. But in the\n process, the whole content is parsed and re-dumped. This can lead to\n differences with the original inputs. The ordering of keys can be\n annoying in some use cases, even if, well mappings should not be\n ordered, these are ordered by the sequential nature of a file, and using\n 'omap' is often tedious. ``shyaml`` now keep the original order the keys\n were met.\n\n\n\n0.3.4 (2015-03-06)\n------------------\n\nNew\n~~~\n- Added a nice ``--help`` doc. [Valentin Lab]\n- Added ``key-values{,-0}`` argument to get key and values in one go.\n [Valentin Lab]\n- Error is casted if no default specified and the key is not existent.\n [Valentin Lab]\n\nChanges\n~~~~~~~\n- Be more informative in some key related error message. (fixed #7)\n [Valentin Lab]\n\n\n0.2.2 (2014-03-19)\n------------------\n\nFix\n~~~\n- No argument at all was treated as one empty string argument. Thx Yassa\n Bb. (fixes #6) [Valentin Lab]\n\n\n0.2.1 (2013-11-23)\n------------------\n\nNew\n~~~\n- Python3 support. [Valentin Lab]\n\nFix\n~~~\n- Keys can now be empty or contains dots ``.`` if they are properly\n escaped (fixes #5, thanks to Daniel Giribet) [Daniel Giribet]\n\n\n0.2.0 (2013-05-03)\n------------------\n\nNew\n~~~\n- Support for iteration in sequence and struct in one go. [Valentin Lab]\n\nFix\n~~~\n- Forgot to mention ``./autogen.sh`` execution when getting the code\n from git, and be more clear about other means of installation.\n [Valentin Lab]\n\n\n0.1.3 (2013-03-29)\n------------------\n\nFix\n~~~\n- Removed the spurious line feed at the end of any ``shyaml`` output.\n [Valentin Lab]\n- Support querying for... nothing. Which now returns the whole input\n YAML. [Valentin Lab]\n\n Before this fix, you couldn't ask for ``shyaml get-value`` alone, even if it\n makes sense but is completely useless as it returns the whole YAML input.\n\n\n\n0.1.2 (2013-03-23)\n------------------\n\nNew\n~~~\n- Support for list indexes (see README.rst). [Valentin Lab]\n- Catch exceptions when parsing structure and output a clean error\n message. [Valentin Lab]\n\n\n0.1.1 (2013-02-27)\n------------------\n\nChanges\n~~~~~~~\n- Some minor enhancements, and an \"Install\" section. [Valentin Lab]\n\n\n0.1.0 (2013-02-27)\n------------------\n- First import. [Valentin Lab]\n\n\n\n",
"bugtrack_url": null,
"license": "BSD 3-Clause License",
"summary": "YAML for command line",
"version": "0.6.2",
"project_urls": {
"Homepage": "http://github.com/0k/shyaml"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "2a5c139cda90758d6bc18a16876a2c291264cf06fd736ca54606862a43931877",
"md5": "db51d35d653b1eb04c86c8681376fa60",
"sha256": "d4849f0a280dea2da6d952539bc6a867ddf9c7026b026eb3170185e638da73ef"
},
"downloads": -1,
"filename": "shyaml-0.6.2-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "db51d35d653b1eb04c86c8681376fa60",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 19846,
"upload_time": "2020-12-15T20:07:58",
"upload_time_iso_8601": "2020-12-15T20:07:58.030789Z",
"url": "https://files.pythonhosted.org/packages/2a/5c/139cda90758d6bc18a16876a2c291264cf06fd736ca54606862a43931877/shyaml-0.6.2-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "b9597e6873fa73a476de053041d26d112b65d7e1e480b88a93b4baa77197bd04",
"md5": "1df5a9a30af975dc29d023355d912031",
"sha256": "696e94f1c49d496efa58e09b49c099f5ebba7e24b5abe334f15e9759740b7fd0"
},
"downloads": -1,
"filename": "shyaml-0.6.2.tar.gz",
"has_sig": false,
"md5_digest": "1df5a9a30af975dc29d023355d912031",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 38093,
"upload_time": "2020-12-15T20:08:00",
"upload_time_iso_8601": "2020-12-15T20:08:00.023554Z",
"url": "https://files.pythonhosted.org/packages/b9/59/7e6873fa73a476de053041d26d112b65d7e1e480b88a93b4baa77197bd04/shyaml-0.6.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2020-12-15 20:08:00",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "0k",
"github_project": "shyaml",
"travis_ci": true,
"coveralls": true,
"github_actions": false,
"appveyor": true,
"lcname": "shyaml"
}
JSON
