.. _cmdline-tools:

==================
Command-line tools
==================
This section describes two command line tools that are part of the Yangson package. A few more specialized Python scripts are available in the project repository, directory `tools/python`_.

.. _yangson-tool:

yangson
-------

This tool provides a command-line interface to the essential high-level functions of the Yangson library, namely

* printing an ASCII schema tree, see :meth:`.DataModel.ascii_tree`

* printing an opaque identifier of a YANG module set,
  see :meth:`.DataModel.module_set_id`.

* printing a schema digest in JSON format,
  see :meth:`.DataModel.schema_digest`.

* validating an instance document against a data model schema or subschema,
  see :meth:`.InstanceNode.validate`.

* dumping and loading a YANG data model in a serialized (pickled) form
  that reduces data model loading time compared to repeated parsing of
  source YANG modules; see the Python standard library module
  :mod:`pickle`.

For example, an ASCII tree of the schema from :ref:`sec-ex4` can be
generated by executing the following command in the
``docs/examples/ex4`` directory:

.. shtest::
   :cwd: examples/ex4

   $ yangson -p .:../../../yang-modules/ietf -t yang-library-ex4.json
   +--rw example-4-a:bag!
   |  +--ro bar <boolean>
   |  x--rw foo <uint8>
   |  +--rw (opts)?
   |     +--:(a)
   |     |  +--rw baz? <empty>
   |     +--:(example-4-b:fooref)
   |        +--rw fooref? <leafref>
   +--rw example-4-b:quux# <decimal64>

An overview of command-line parameters can be obtained by using the ``--help/-h`` switch:

.. sh:: yangson --help

Consult the :ref:`manual page <yangson-man>` for further details.

.. toctree::
   :hidden:

   yangson-man

.. _convert8525-tool:

convert8525
-----------

This script allows for extracting one schema from NMDA-enabled YANG
library data [RFC8525]_ (in JSON representation) and storing its
parameters in the old YANG library format of [RFC7895]_ that can be
used as input to *Yangson* library functions and the *yangson* tool.

As an example, the distribution directory ``docs/examples/ex3`` also contains new-format YANG library data in the file ``rfc8525-ex3.json``. It can be converted to the old format by executing the following command in that directory:

.. shtest::
   :cwd: examples/ex3

   $ convert8525 --path ../../../yang-modules/ietf --datastore running rfc8525-ex3.json
   {
     "ietf-yang-library:modules-state": {
       "module-set-id": "5798f6c8acd78ccb1171cb36d34fb95ca797c769",
       "module": [
         {
           "name": "example-3-a",
           "revision": "2017-08-01",
           "conformance-type": "implement",
           "namespace": "http://example.com/example-3/a",
           "submodule": [
             {
               "name": "example-3-suba",
               "revision": "2017-08-01"
             }
           ],
           "feature": [
             "fea1",
             "fea2"
           ]
         },
         {
           "name": "example-3-b",
           "revision": "2016-08-22",
           "conformance-type": "implement",
           "namespace": "http://example.com/example-3/b"
         },
         {
           "name": "ietf-inet-types",
           "revision": "2010-09-24",
           "conformance-type": "import",
           "namespace": "urn:ietf:params:xml:ns:yang:ietf-inet-types"
         },
         {
           "name": "ietf-yang-types",
           "revision": "2013-07-15",
           "conformance-type": "import",
           "namespace": "urn:ietf:params:xml:ns:yang:ietf-yang-types"
         },
         {
           "name": "ietf-inet-types",
           "revision": "2013-07-15",
           "conformance-type": "import",
           "namespace": "urn:ietf:params:xml:ns:yang:ietf-inet-types"
         }
       ]
     }
   }

An overview of command-line parameters can be obtained by using the ``--help/-h`` switch:

.. sh:: convert8525 --help

Consult the :ref:`manual page <convert8525-man>` for further details.

.. toctree::
   :hidden:

   convert8525-man

.. _tools/python: https://github.com/CZ-NIC/yangson/tree/master/tools/python