Introduce new barectf configuration API and YAML configuration schema

Introduce new barectf configuration API and YAML configuration schema

This patch:

* Updates the configuration API (breaking change) to:

  * Match, more or less, Babeltrace 2's terminology.
  * Be more clear and consistent.
  * Prepare for CTF 2.

* Adds support for a new type of YAML configuration to match the updated
  configuration API.

  Internally, the new schema is named "v3" as it will be barectf 3's
  configuration format. The (now) old schema is named "v2".

* Updates all the existing code to deal with the updated configuration
  API.

I admit that this is a very big change, but it was too arduous to split
in various patches. This message explains what changes and why.

Configuration API changes (metadata)
====================================
barectf 2's metadata API has existed for five years now.

During those five years, I had the chance to work on Babeltrace 2,
CTF 2, and LTTng, and polished CTF's concepts, type relations, and
terminology.

The main goal of this patch is, as much as possible, to make barectf's
configuration API match what was done in Babeltrace 2's trace IR API [1]
at the metadata level.

A few examples:

* All metadata objects are "types" (classes in Babeltrace 2): field
  type, clock type, event type, stream type, and so on.

* A signed enumeration field type inherits an enumeration field type
  (which inherits an integer field type) and a signed integer field
  type.

* Integer and string field types have no encoding property.

  If we need them, we can introduce text array field types in the
  future.

  A string field type has a fixed UTF-8 (a superset of ASCII) encoding.

With this patch, an integer field type doesn't have any property
mapping. Instead, when you create a stream type, you can specify a
default clock type: the event time and packet beginning/end time members
refer to this default clock type in the generated TSDL metadata stream
so that each stream has an instance of it.

One other important change is that, with this patch, you cannot specify:

* The packet header field type of a trace type.
* The packet context field type of a stream type.
* The event header field type of a stream type.

I believe it was an error to let the user control those structure field
types as, fundamentally, they are "format" field types (reserved by
CTF).

As of this patch, you can enable/disable trace type and stream type
features which eventually translate to the automatic creation of the
field types listed above. For example, the "discarded events counter
field type" feature of a stream type controls whether or not the packets
of its instances (streams) contain a discarded events counter field. You
can either:

* Disable the feature (`None`).

* Enable the feature with a default field type (`DEFAULT_FIELD_TYPE`).

* Enable the feature with a custom field type
  (`UnsignedIntegerFieldType` instance).

The packet context field type is a bit of an exception here as it can
contain both format (total size, content size, beginning/end times, and
the rest) and user members. As such, when you create a stream type, you
can specify extra packet context field type members.

This feature approach hides all the reserved CTF member names (`id`,
`magic`, `uuid`, `timestamp_begin`, and the rest): barectf deals with
this internally. There are sane defaults, for example:

* The "magic" and "stream type ID" trace type features are enabled by
  default.

* If, when you create a stream type, you specify a default clock type
  and default features, then the event time and packet beginning/end
  times features are enabled.

All the configuration names are in `config.py` (removing `metadata.py`).

The big picture is:

* A configuration has a trace and options (prefixes and other generation
  options).

* A trace has an environment (think TSDL environment) and a type.

* A trace type has a default byte order, a UUID, features, and one or
  more stream types.

* A stream type has an ID, a name, an default clock type,
  features, extra packet context field type members, a common event
  context field type, and one or more event types.

* A clock type has a name, a frequency, a UUID, a description, a
  precision, an offset, and whether or not its origin is the Unix epoch.

* An event type has an ID, a name, a log level, and specific context and
  payload field types.

* A field type (abstract) has an alignment.

* A bit array field type (abstract) adds the size (bits) and byte order
  properties to a field type.

* An integer field type adds the preferred display base properties to a
  bit array field type.

* An enumeration field type adds the mappings property to an integer
  field type.

* A real field type is a bit array field type.

  The only valid sizes are 32 (single-precision) and 64
  (double-precision).

* An array field type (abstract) adds element field type property to a
  field type.

* A static array field type adds the length property to an array field
  type.

  This field type is only used for the "UUID field type" trace type
  feature.

* A structure field type has named members.

  Each member has a field type.

  In the future (CTF 2), a structure field type member could also
  contain custom user attributes.

New YAML configuration schema
=============================
The barectf 3 YAML configuration format mirrors the new configuration
API, with some sugar to make it easier to write a YAML configuration
file.

The most significant changes are:

* There's no configuration version property.

  Starting from barectf 3, a barectf YAML configuration node is a map
  with the YAML tag [2] `tag:barectf.org,2020/3/config`. Consequently, a
  barectf 3 YAML configuration file will typically start like this:

      %YAML 1.2
      --- !<tag:barectf.org,2020/3/config>

  As you can see, the barectf major version is encoded within the tag.
  The major version is enough: minor bumps of barectf 3 will only add
  features without breaking the schema.

  Only the configuration node needs an explicit tag: all the nodes under
  it have implicit tags according to the schema. This top-level tag
  makes it possible to integrate a barectf 3 configuration node within
  another YAML document, if this ever becomes a use case.

* The terminology, the property names, and, in general, the object
  layouts, are the same as with the configuration API.

* There are two ways to specify prefixes:

  Single prefix:
      Use `PREFIX_` for C identifiers, where `PREFIX` is the single
      prefix, and `PREFIX` for file names.

      For example, with

          prefix: hello

      identifiers start with `hello_` and file names with `hello`.

  Explicit prefixes:
      Specify the exact prefixes to be used for C identifiers and file
      names.

      For example, with

          prefix:
            identifier: lol_
            file-name: meow

      identifiers start with `lol_` and file names with `meow`.

* For the trace type and stream types, specify features in the
  `$features` property.

  Example:

      $features:
        magic-field-type: true
        uuid-field-type: false
        stream-type-id-field-type:
          class: unsigned-int
          size: 8
          byte-order: le

  A field type feature can be one of:

  True:
      Use the default field type.

  False:
      Disable the feature.

  Field type node:
      Use a specific field type.

* The only way to make a stream type the default stream type is with its
  `$is-default` property.

  Example:

      my_stream:
        $is-default: true

  Only one stream type can have this property set to true.

* Specify field type aliases with any order, whatever the dependencies.

  Example:

      $field-type-aliases:
        hello:
          $inherit: meow
          alignment: 32
        meow:
          class: signed-int
          size: 32

* An enumeration field type is an integer field type; there's no concept
  of "value field type" anymore.

  Example:

      class: unsigned-enum
      size: 32
      byte-order: le
      mappings:
        # ...

* An enumeration field type's `mappings` property is a map of labels to
  lists of integer ranges.

  The order of individual mappings is not important.

  An integer range is either a single integer or a pair of integers
  (lower and upper).

  Example:

      class: unsigned-enum
      size: 32
      mappings:
        HOLA: [2]
        MEOW:
          - 23
          - [4, 17]
        ROCK:
          - [1000, 2000]
          - [3000, 4000]
          - [5000, 6000]

* A real field type is a bit array field type.

  Example (single-precision):

      class: real
      size: 32

* Specify the members of a structure field type like a YAML ordered
  map [3], without having to specify the `tag:yaml.org,2002:omap`
  tag.

  This fixes a "bug" which exists since barectf 2.0: a YAML map is not
  ordered per se; as such, the members of a structure field type cannot
  be a simple map. It works in barectf 2 because PyYAML parses the map
  entries in order, but there's no requirement to do so.

  Example:

      class: struct
      members:
        - sup:
            field-type: uint32
        - meow:
            field-type:
              class: string
        - bob:
            field-type:
              $inherit: double
              byte-order: be

  It might seem silly to specify `field-type` for each member, but CTF 2
  might bring user attributes for individual structure field type
  members, so barectf 3 will be ready. For example:

      class: struct
      members:
        - sup:
            field-type: uint32
        - meow:
            field-type:
              class: string
            user-attributes:
              'https://example.com/ns/ctf':
                type: user-name
                color: blue
        - bob:
            field-type:
              $inherit: double
              byte-order: be

Internally, barectf detects the YAML configuration file's version. If
it's a barectf 2 configuration node, it converts it to a barectf 3
configuration node, and then it decodes it, as such:

    barectf 2 YAML    barectf 3 YAML
    config. node   -> config node.   -> barectf config. object (API)

What you get with `--dump-config` occurs after step 1.

barectf 3 will remain fully backward compatible regarding barectf 2 YAML
configurations and the CLI. This is why the `barectf/include` directory
contains inclusion files for both barectf 2 and 3: the CLI selects the
appropriate directory based on the detected version.

`barectf/schemas` also contains JSON schemas for both versions of the
configuration, as well as common schemas.

Configuration API changes (functions)
=====================================
The configuration API functions are now:

configuration_file_major_version():
    Returns the major version (2 or 3) of a YAML configuration file-like
    object.

effective_configuration_file():
    Returns the effective configuration file (YAML string) using a
    file-like object and a list of inclusion directories.

    An effective configuration file is a file where:

    * All field type nodes are expanded (aliases and inheritance).

    * Log level aliases are substituted for their integral equivalents.

    * Some properties are normalized.

      For example, the `be` byte order becomes `big-endian` (both are
      valid). Also, null properties are simply removed.

configuration_from_file():
    Returns a `barectf.Configuration` object from a YAML configuration
    file-like object.

Code generation API
===================
This patch also brings changes to the code generation API.

Now you create a `barectf.CodeGenerator` object, passing a barectf
configuration.

With such a code generator object, call its generate_c_headers(),
generate_c_sources(), and generate_metadata_stream() methods to generate
code.

generate_c_headers() and generate_c_sources() return lists of
`barectf.gen._GeneratedFile` objects. Such an object contains the name
of the file and its (UTF-8 text) contents.

generate_metadata_stream() returns a single `barectf.gen._GeneratedFile`
object.

`__init__.py`
=============
The whole barectf API is now available directly under its package.

`__init__.py` picks what needs to be exposed from its different modules.

Tests
=====
Tests which were directly under `tests/config` are moved to
`tests/config/2` as we could add barectf 3 configuration tests in the
future.

[1]: https://babeltrace.org/docs/v2.0/libbabeltrace2/group__api-tir.html
[2]: https://yaml.org/spec/1.2/spec.html#id2761292

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>