/* STANDARD_RIFT_IO_COPYRIGHT */

/**
 * @file rw-pb-ext.yang
 * @author Tim Mortsolf, Anil Gunturu, Tom Seidenberg
 * @date 2013/03/21
 * @brief RiftWare yang to protobuf conversion extensions
 */

module rw-pb-ext
{
  namespace "http://riftio.com/ns/riftware-1.0/rw-pb-ext";
  prefix "rwpb";

  revision 2014-03-28 {
    description
      "Initial revision.";
    reference
      "RIFT yang extensions for converting yang files to Google
      Protocol Buffers (protobuf) using rift protoc-c extensions.";
  }

  extension msg-new {
    argument "typename";
    description
      "Generate an equivalent, top-level, protobuf message for this
      container, list, rpc input, rpc output, or notification.  The
      argument is the name of the protobuf message type.  Allowed
      values are valid C identifiers.

      The protobuf definition will only be generated when processing
      the same module that defines the yang object - a duplicate will
      not be generated when importing reusing a yang object via uses,
      or when importing the module.";
  }

  extension msg-name {
    argument "typename";
    description
      "Change the name of an embedded protobuf message type for this
      container or list.  Allowed values are valid C identifiers.

      In lieu of this extension, embedded protobuf message typenames
      are based on the fieldname, and further mangled by removing
      underscores and CamelCased at underscore boundaries.  This
      extension allows the automatic mangling procedure to be
      overridden.

      This extension is incompatible with msg-new, which already
      defines the typename for top-level messages.  Use this extension
      solely for embedded messages.";
  }

  extension msg-flat {
    argument "selection";
    description
      "Set the protobuf message rw_msgopts flat option on a container
      or list statement.  Allowed values are 'true', 'false', and
      'auto'.  The default is 'false' for top-level messages, and
      'auto' for embedded messages.  If 'auto' is specified, the
      behavior is the same as the enclosing container or list.

      Unless overridden, this extension effectively applies to all
      enclosed descendent container and list statements.  Flatness will
      be required by the protobuf compilation step.";
  }

  extension msg-tag-base {
    argument "value";
    description
      "Specify a base tag value for a container, list, grouping, or
      uses statement.  Field tags may be specified relative to this
      base.  Allowed values are positive
      decimal integers.";
    // ATTN:  would really like to specify field-relative in uses!
  }

/*
  extension msg-tag-reserve {
    argument "value";
    description
      "Reserve space in the tag numbering for future expansion of the
      enclosing grouping, container, or choice.  Must be a positive
      decimal integer.  Choose carefully, as you cannot increase the
      value at a later time.";
  }
*/

  extension msg-proto-max-size {
    argument "value";
    description
      "Specify the maximum size of this message in the C structure or
      so in bytes.  Allowed values are positive decimal integers.";
  }

  extension msg-typedef {
    argument "typename";
    description
      "Create a prototbuf-c message typedef for the original, base
      definition of the container, list, grouping, rpc input, rpc
      output, or notification.  Allowed values are valid C identifiers.

      typename will be appended to the mangeled protobuf package name
      and an underscore, to ensure name uniqueness across the global
      schema.

      The typedef will only be generated when processing
      the same module that defines the yang object - a duplicate will
      not be generated when importing reusing a yang object via uses,
      or when importing the module.";
  }

  extension field-name {
    argument "fieldname";
    description
      "Change the name of the element to fieldname, when converting the
      object to protobuf.  Allowed values are valid C identifiers.

      In lieu of this extension, element names will be used as-is, if
      possible, or mangled to fit in the C identifier character space
      (invalid C identifier characters will be replaced with
      underscore).  This extension allows the automatic mangling
      procedure to be overridden.";
  }

  extension field-inline {
    argument "selection";
    description
      "Set the protobuf field 'inline' option on a container, list,
      leaf-list, or leaf statement.  Allowed values are 'true',
      'false', and 'auto'.  If 'auto' is specified, the behavior is
      controlled by the enclosing container or list's protobuf-msg-flat
      setting.

      When applied to a container or list statement, this extension is
      inherited by all enclosed objects, unless overridden.";
  }

  extension field-inline-max {
    argument "limit";
    description
      "Set the protobuf field 'inline_max' option for list and
      leaf-list statements.  Allowed values are a positive decimal
      integer, 'yang', or 'none'.  Example limits:

        '64'
        'yang'
        'none'

      If 'none' is specified, then the inline_max protobuf extension
      will not be used.

      If 'yang' is specified, then the number of elements specified in
      the yang 'max-elements' statement is used.  If there is no
      'max-elements' statement, the behavior defaults to 'none'.

      If a decimal integer is specified, that number is used as the
      maximum length.

      If this extension is not specified, the behavior defaults to
      'yang'.  Descendant list and leaf-list objects do not inherit
      this extension.";
  }

  extension field-string-max {
    argument "limit";
    description
      "Set the protobuf field 'string_max' option for a leaf or
      leaf-list of type string, binary, leafref, identityref, or
      instance-identifier.  Allowed values are a positive decimal
      integer, 'yang', or 'none'.  An optional encoding specifier may
      also be specified, as octet or utf8, which specifies how
      characters are counted.  If specified, the encoding must come
      first.  Example limits:

        'octet 64'
        'utf8 20'
        'utf8 yang'
        'utf8'
        '128'
        'none'

      If 'none' is specified, then the string_max protobuf extension
      will not be used.  'none' cannot be combined with 'octet' or
      'utf8'.

      If 'yang' is specified, the yang type must be string or binary.
      If the yang type includes the length statement, then the
      statements maximum length is used as the length.  Otherwise,
      behavior defaults to 'none'.

      If a decimal integer is specified, that number is used as the
      length.

      The encoding specifiers are used to determine the actual number
      of bytes used in the protobuf extension.  If the 'octet'
      specifier is used, then the maximum length is used literally as
      the byte length.  If the 'utf8' specified is used, then the
      maximum length is considered to be in terms of worst-case UTF-8
      characters, in which case the protobuf byte length will actually
      be 4 times the specified length.

      For string and binary types, the default encoding is 'octet'.
      For the remaining types, the default encoding is 'utf8',
      reflecting those types fundemental description as XML entities
      assumed to be encoded in UTF-8.

      If this extension is not specified, then the default is 'yang'
      for string and binary, and 'none' for the other types.  This
      extension cannot be specified on aggregate objects, and so it
      cannot be inherited.";
  }

  extension field-tag {
    argument "value";
    description
      "Set the protobuf field tag.  Allowed values are a positive
      decimal integer, 'auto', a base-relative addition expression, or
      a field-relative addition expression.

      If a decimal integer is specified, then the tag is set to the
      specified number.  You should avoid using this form in a
      grouping, because you may not be able to guarantee uniqueness
      across all the uses of the group.  However, the syntax will be
      allowed.

      A base-relative addition expression allows the tag of a field to
      be defined in terms of the base tag of an enclosing grouping,
      container, list, or uses statement.  The expression has the form
      '+NUMBER', where NUMBER is the value to add to the base to derive
      the current field's tag.

      A field-relative addition expression allows the tag of one field
      to be defined in terms of another field.  The expression has the
      form 'NAME+NUMBER', where NAME is the name of the other field,
      and NUMBER is the value to add to the other fields tag to derive
      the current field's tag.

      If this extension is not specified, the default behavior is
      'auto'.";
  }

  extension field-type {
    argument "type";
    description
      "Override the default protobuf field type mapping for a leaf or
      leaf-list type, and use the specified protobuf type instead.

      Allowed values are any of the Protobuf scalar types, as
      restricted by the yang leaf type:

      +---------------------------+-------------------------------+
      | (pseudo) yang leaf type   | (pseudo) protobuf scalar type |
      |---------------------------+-------------------------------+
      | int8, int16, int32        | int32, sint32, sfixed32, auto |
      +---------------------------+-------------------------------+
      | int64                     | int64, sint64, sfixed64, auto |
      +---------------------------+-------------------------------+
      | uint8, uint16, uint32     | uint32, fixed32, auto         |
      +---------------------------+-------------------------------+
      | uint64                    | uint64, fixed64, auto         |
      +---------------------------+-------------------------------+
      | decimal                   | uint64, sint64, int64,        |
      |                           | fixed64, sfixed64,            |
      |                           | float, double, auto           |
      +---------------------------+-------------------------------+
      | empty, boolean            | bool, auto                    |
      +---------------------------+-------------------------------+
      | string, leafref,          | string, auto                  |
      | identityref,              |                               |
      | instance-identifier,      |                               |
      | anyxml                    |                               |
      +---------------------------+-------------------------------+
      | bits, binary              | bytes, auto                   |
      +---------------------------+-------------------------------+

      If 'auto' is specified, the default conversion will be used.  The
      protobuf pseudo-type utf8 is equivalent to string, except that
      length limits will be adjusted in protobuf extentions to allow
      the string to be composed entirely of the maximum sized UTF-8
      multibyte characters (byte length is 4 times larger than the
      character length).";
  }

  extension field-c-type {
    argument "type";
    description
      "Override the default protoc-c C-language type mapping for a leaf
      or leaf-list type, and use the specified C type instead.";
  }

  /* ATTN: Stop using this extension? */
  extension package-name {
    argument "pkgname";
    description
      "Specifies the name of the package name in the generated .proto
      file on a module statement The argument is the name of the
      package-name.  Allowed values are valid C identifiers When
      package-name is not specified the generated package name defaults
      to the Yang module name";
  }

  extension application-request-point {
    description
      "This extension is used temporarily until the config and data portions
       are split into different namespaces and keyspecs. This allows
       applications to provide data at a keyspec, and request config at a
       different level";
  }

  extension enum-name {
    argument "enumname";
    description
      "Use the specified name for the enum enumerator in the .proto
      instead of the default mangled name of the yang identifer.
      If there is a name conflict with other enum name either specified
      explicitly or generated one, the yangpbc conversion will fail.
      Allowed values are valid C identifiers.";
  }

  extension enum-type {
    argument "enumtypename";
    description
      "Use the specified name for the enum type in the .proto instead
      of the default mangled name of the yang identifier.  If there is
      a name conflict with another enum type, either auto-generated or
      explicitly specified one, the yangpbc conversion will fail.
      Allowed values are valid C identifiers.";
  }

  extension file-pbc-include {
    argument "pathstring";
    description
      "A module level extension to specify the include files for pb-c.h
      when any rift specific c-types are used.  This extension can
      occur multiple times as a child of module statement.  The value
      should be a valid path string.";
  }

  extension field-merge-behavior {
    argument "value";
    description
      "An extension for controlling the merge done for listy types
       during upacking of protobuf. It can take 3 different value:
       
       1) default: The default is whatever protobuf-c does today 
          (for keyed lists, the default is equivalent to by-keys).

       2) by-keys: allowed on keyed lists (and leaf-lists): merge 
          elements with matching key.

       3) none: allowed on keyed lists (and leaf-lists): do not 
          attempt to merge elements. This must ONLY be used when it 
          is known or expected that the proto message would contain
          large number of list items.";
  }

} // rw-pb-ext