Quick start
===========

Treefic is available both as a `python library <reference>`:doc: and as a command-line tool. This section gives an overview on how to use the latter.

Basic usage
-----------

The ``treefic`` command-line tool can be invoked with two parameters:
* the name of a file containing the grammar to be used
* the name of a file containing the textual data to convert to XML.

E.g.::

  treefic examples/avpairs-grammar.txt examples/avpairs-data.txt

The data file contains the following data::

        name = Doe
  first-name = John
       email = john@doe.org
     address = 123 Second Street / Smalltown

and the resulting output is (without indentation)::

  <av-pairs>
    <pair key="name">Doe</pair>
    <pair key="first-name">John</pair>
    <pair key="email">john@doe.org</pair>
    <pair key="address">123 Second Street / Smalltown</pair>
  </av-pairs>

Pipeline usage
--------------

As an alternative, if only one filename is given, ``treefic`` will read the textual data from its standard input. It is indeed intended to be used in a pipeline where preceding commands produce the textual data, and following commands processing the corresponding XML tree. E.g.::

  grep -v name examples/avpairs-data.txt \
  | treefic examples/avpairs-grammar.txt \
  | xmllint --relaxng examples/avpairs-schema.rng

To go further
-------------

The `next section <grammar>`:doc: explains how to write a grammar file recognized by ``treefic``.