module yangdump-pro {

    yang-version 1.1;

    namespace
      "http://yumaworks.com/ns/yangdump-pro";

    prefix ydpro;

    import ietf-yang-structure-ext {
      prefix sx;
    }
    import yuma-ncx {
      prefix ncx;
    }
    import yuma-app-common {
      prefix ncxapp;
    }
    import yuma-types {
      prefix yt;
    }
    import yumaworks-app-common {
      prefix ywapp;
    }

    organization "YumaWorks, Inc.";

    contact
      "Support <support at yumaworks.com>";

    description
      "yangdump-pro provides validation and translation of YANG data
models. Information about a module or submodule can be
generated as well.

INPUT FILES

   Operations can be performed on one or more files with
   the 'module' parameter, or an entire directory tree
   with the 'subtree' parameter.  Unless the 'help' or
   'version' parameters is entered, one of these input
   parameters must be present.

SEARCH PATH

    When a module name is entered as input, or when a
    module or submodule name is specified in an import or
    include statement within the file, the following search
    algorithm is used to find the file:

    1) file is in the current directory
    2) YUMAPRO_MODPATH environment var (or set by modpath parm)
    3) $HOME/modules directory
    4) $YUMAPRO_HOME/modules directory
    5) $YUMAPRO_INSTALL/modules directory OR
       default install module location,
       '/usr/share/yumapro/modules'

    By default, the entire directory tree for all locations
    (except step 1) will be searched, not just the specified
    directory.  The 'subdirs' parameter can be used to
    prevent sub-directories from being searched.

    Any directory name beginning with a dot character '.'
    will be skipped.  Also, any directory named 'CVS' will
    be skipped in directory searches.

TRANSLATION MODES

    The 'format' parameter is used to select a translation output mode.
    If it is missing, then no translation will be done.
    This parameter can be used with the module reports parameters,
    but the translation output should be directed to a file
    instead of STDOUT to keep them separated.

    For XSD 1.0 translation, use the 'format=xsd' parameter.

    For XHTML 1.0 translation, use the 'format=html' parameter.

    For YIN translation, use the 'format=yin' parameter.

MODULE REPORTS

    For a 1 line output of the module name and version,
    use the 'modversion' parameter.

    For a listing of all the symbols that the file exports
    to other files, use the 'exports' parameter.

    For a listing of all the files that the file depends on,
    to compile, use the 'dependencies' parameter.

    For a listing of all the accessible object identifiers that
    the file contains, use the 'identifiers' parameter.

    For a tree listing of all the accessible object identifiers that
    the file contains, use the 'tree-identifiers' parameter.

OUTPUT MODES

    By default, any translation output will be sent to STDOUT.

    The 'output' parameter can be used to specify the
    full filespec of the output file,  or a
    partial directory specification to be combined
    with a default filename.

    The 'defnames' parameter can be used to generate a default
    filename in the current directory for the output, or
    in the 'output' directory, if one is specified.

    By default, an output filename will have the form:

	  <module-name>.<module-revision>.<ext>

    If the 'versionnames=false' parameter is used, then the
    default filename will have the form:

	  <module-name>.<ext>

    This parameter will also affect URL generation during
    HTML translation.

    When the 'subtree' input parameter is used for XSD or HTML
    translation, the 'defnames' parameter will be automatically
    set to 'true', to maintain well-formed XML documents when
    multiple translations are possible.

    If the 'unified' parameter is set to 'true', then all
    submodules will be processed when the input is a main
    module that includes any submodules.  For XSD and HTML
    translation, the submodule content will be generated
    instead of an 'include' statement.  Submodule files
    will be skipped in 'subtree' mode.

ERROR LOGGING

    By default, warnings and errors are sent to STDOUT.

    A log file can be specified instead with the 'log' parameter.
    Existing log files can be reused with the 'logappend'
    parameter, otherwise log files are overwritten.

    The logging level can be controlled with the 'log-level'
    parameter.  The default log level is 'info'.  The
    log-levels are additive:

       off:    suppress all errors (not recommended!)
	       A program return code of '1' indicates some error.
       error:  print errors
       warn:   print warnings
       info:   print generally interesting trace info
       debug:  print general debugging trace info
       debug2: print verbose debugging trace info

Copyright (c) 2010 - 2023 YumaWorks, Inc. All rights reserved.

Redistribution and use in source and binary forms, with or
without modification, is permitted pursuant to, and subject
to the license terms contained in, the BSD 3-Clause License
http://opensource.org/licenses/BSD-3-Clause";

    revision "2024-02-25" {
      description
        "Add sil-edit3 CLI parameters.";
    }

    revision "2023-08-04" {
      description
        "22.10T-11: Change CLI container to sx:structure";
    }

    revision "2021-10-23" {
      description
        "Change defaults for some code generation parameters
that are now deprecated. Changes start in 21.10-1.
Add --sil-edit1 and --sil-get1 parameters to preserve
deprecated behavior with new CLI parameters.";
    }

    revision "2021-05-02" {
      description
        "Add --doxygen-headers parameter.";
    }

    revision "2020-11-14" {
      description
        "Add short-names and force-prefix parameters.";
    }

    revision "2019-09-22" {
      description "Add sil-nmda parameter.";
    }

    revision "2018-03-28" {
      description
        "Add lang-errors parameter.";
    }

    revision "2017-06-14" {
      description
        "Add quiet-mode parameter.";
    }

    revision "2017-04-27" {
      description
        "Add with-ocpattern parameter.";
    }

    revision "2015-08-27" {
      description
        "Add sil-get2 and sil-edit2 CLI parameters.";
    }

    revision "2014-05-03" {
      description "Add --sil-sa parameter.";
    }

    revision "2013-10-08" {
      description
        "Add --sil-bundle and --sil-include parameters.";
    }

    revision "2012-08-16" {
      description
        "Split out from yangdump.yang.";
    }

    revision "2011-10-08" {
      description "Add --home parameter.";
    }

    revision "2011-09-12" {
      description
        "Add --format=uc and --format=uh to support
generation of separate SIL user functions";
    }

    revision "2011-01-28" {
      description
        "Change output leaf to ncxapp:OutputParm grouping";
    }

    revision "2010-05-31" {
      description
        "Added --stats and --totals parameters
for YANG statistics reporting.";
    }

    revision "2010-03-11" {
      description
        "Added new format enum for TG2 code generation.";
    }

    revision "2010-01-30" {
      description
        "Initial version for 0.10 release.";
    }

    sx:structure "yangdump-pro";

    typedef FormatType {
      type enumeration {
        enum "xsd" {
          value 0;
          description "Convert YANG to XSD";
        }
        enum "sql" {
          value 1;
          description
            "Convert YANG to SQL history collection (TBD)";
        }
        enum "sqldb" {
          value 2;
          description
            "Convert YANG to SQL input for netconfcentral.org
database.";
        }
        enum "html" {
          value 3;
          description
            "Convert YANG to HTML documentation format.";
        }
        enum "yang" {
          value 4;
          description
            "Convert YANG to canonical YANG format.";
        }
        enum "copy" {
          value 5;
          description
            "Copy and rename the YANG file to canonical name
format.";
        }
        enum "h" {
          value 6;
          description
            "Generate combined server instrumentation library
H file. Compatible with version 1 'h' format";
        }
        enum "c" {
          value 7;
          description
            "Generate combined server instrumentation library
C file. Compatible with version 1 'c' format";
        }
        enum "cpp_test" {
          value 8;
          description
            "Generate combined server instrumentation library
CPP file for testing purposes.";
        }
        enum "uh" {
          value 9;
          description
            "Generate server instrumentation library
user callback H file.";
        }
        enum "uc" {
          value 10;
          description
            "Generate server instrumentation library
user callback C file.";
        }
        enum "yh" {
          value 11;
          description
            "Generate split server instrumentation library
user callback H file.";
        }
        enum "yc" {
          value 12;
          description
            "Generate server instrumentation library
user callback H file.";
        }
        enum "yin" {
          value 13;
          description
            "Convert YANG to YIN format.";
        }
        enum "tg2" {
          value 14;
          description
            "Convert YANG to Turbogears 2 Source code files.";
        }
        enum "bh" {
          value 15;
          description
            "Generate server instrumentation library
bundle callback H file.";
        }
        enum "bc" {
          value 16;
          description
            "Generate server instrumentation library
bundle callback C file.";
        }
      }
      description
        "Conversion Output Formats.";
    }

    typedef TocType {
      type enumeration {
        enum "none" {
          value 0;
        }
        enum "plain" {
          value 1;
        }
        enum "menu" {
          value 2;
        }
      }
      default "menu";
      description
        "Requested table of contents type.";
    }

    typedef ObjViewType {
      type enumeration {
        enum "raw" {
          value 0;
          description
            "output includes augment and uses clauses, not the
expanded results of those clauses.";
        }
        enum "cooked" {
          value 1;
          description
            "output does not include augment or uses clauses,
just the objects generated from those clauses (if any).";
        }
      }
      default "raw";
      description
        "Requested view format for objects.";
    }

    container yangdump-pro {
      ncx:cli;
      ncx:default-parm "module";
      description
        "CLI Parameter Set for the YANG Converter Application.";
      leaf defnames {
        type boolean;
        default "false";
        description
          "If 'true', then output to a file with the default name
for the format, usually to the current directory.
Not used if the format parameter is missing.

If the 'output' parameter is present and represents
an existing directory, then the default filename
will be created in that directory, instead of the
current directory.

If 'false', then default naming will not be used.
Output will either be to the current directory
or to STDOUT.";
      }

      leaf dependencies {
        type empty;
        description
          "Validate the file, write the module name, version
and module source for each file that this [sub]module
imports and includes, then exit.

Each dependency type, name, version, and source
is listed once.

If the dependency version and source are missing,
then that import or include file was not found.";
      }

      leaf doxygen-headers {
        type boolean;
        default "true";
        description
          "Controls whether doxygen format headers will be used.

If 'true' then doxygen comments will be generated
in the yumapro-sdk program for C and H file generation.

If 'false' then the older existing  header format
will be generated in the yumapro-sdk program for
C and H file generation.";
      }

      leaf exports {
        type empty;
        description
          "Validate the file, write information for the symbols
that this [sub]module exports, then exit.  Report
includes the following info for the specific file,
not the entire module, if submodules are used:
    - [sub]module name
    - version
    - source filespec
    - namespace (module only)
    - prefix (module only)
    - belongs-to (submodule only)
    - typedefs
    - groupings
    - objects, rpcs, notifications
    - extensions.";
      }

      leaf force-prefix {
        type yt:NcxName;
        description
          "If the 'short-names' parameter is 'true' then this
object can be used to force a specific prefix
value instead of the module prefix, when generating
instrumentation code.

This object should only be used if the module prefix is
known to cause a naming conflict with existing code.

This object cannot be used if the 'sil-bundle' parameter
is also used, and --short-names=true.";
      }

      leaf format {
        type FormatType;
        description
          "Type of conversion desired, if any. If this
parameter is missing, then no translation
will be done, but the module will be validated,
and any requested reports will be generated.

The following values are supported:
   xsd  == XSD 1.0 translation
   sql == SQL schema (TBD)
   sqldb == netconfcentral.org database info
   html == XHTML 1.0 translation
   yang == Canonical YANG translation
   copy == Validate and copy with a new name.
   h == netconfd instrumentation H file
   c == netconfd instrumentation C file.";
      }

      leaf html-div {
        type boolean;
        default "false";
        description
          "If 'true', and HTML translation is requested, then this
parameter will cause the output to be a single <div> element,
instead of  an entire HTML file.

This allows the HTML translation to be easily integrated
within more complex WEB pages, but the proper CSS definitions
need to be present for the HTML to render properly.

The default filename extension will be '.div' instead of '.html'
if this parameter is present.  The contents will be well-formed
XHTML 1.0, but without any namespace declarations.

If 'false', then a complete <html> element will be generated
instead.";
      }

      leaf html-toc {
        type TocType;
        description
          "The HTML Table of Contents output mode.
Ignored unless the 'format' parameter is
set to 'html'.  Default is 'menu'.
Values:
  - none: no ToC generated
  - plain: plain list ToC generated
  - menu: drop-down menu ToC generated.";
      }

      leaf identifiers {
        type empty;
        description
          "Validate the file, write the list of object identifiers,
that this [sub]module contains, then exit.

Each accessible object node is listed once,
including all child nodes.  Notifications and
RPC methods are considered top-level objects,
and have object identifiers as well as configuration
and state data..";
      }

      leaf lang-errors {
        type empty;
        description
          "If present, list each error or warning
number and its default message string
using the language error string format.
The program will exit after this is done.";
      }

      leaf modversion {
        type empty;
        description
          "Validate the file, write the [sub]module
name, version and source filespec, then exit.";
      }

      leaf objview {
        type ObjViewType;
        description
          "Determines how objects are generated in HTML and
YANG outputs.
The default mode is the 'raw' view.
XSD output is always 'cooked', since refined groupings
and locally-scoped definitions are not supported in XSD.

raw -- output includes augment and uses clauses, not the
       expanded results of those clauses.

cooked -- output does not include augment or uses clauses,
      just the objects generated from those clauses.";
      }

      leaf quiet-mode {
        type empty;
        description
          "If present, do not print summaries with 0 errors and
zero warnings. Only print parser summaries if
warnings or errors are found.

If not present then parse in the normal mode and print
parser summaries for these modules.";
      }

      leaf short-names {
        type boolean;
        default "true";
        description
          "If 'true', generate instrumentation code using short
names whenever possible. The module prefix and the
node name will be used. A numeric qualifier will be
appended to the name if the short name would cause
a duplicate symbol to be generated. The 'force-prefix'
value will be use for the prefix if that parameter is
present.

If 'false', then generate instrumentation code using
long names which encode the module name and the
entire path to the object into the name.";
      }

      leaf show-errors {
        type empty;
        description
          "If present, list each error or warning
number and its default message string.
The program will exit after this is done.";
      }

      leaf sil-bundle {
        type yt:NcxName;
        description
          "The name of the SIL bundle to create.  This parameter
is only used if the format parameter is also used and
is equal to 'c', 'h', 'yc', or 'yh'.  It is used to
create SIL code stubs for a bundle of YANG modules.

All the specified modules will be loaded into memory.
Then the SIL code stubs will be generated according
to the given parameters.  Any external augment-stmt
data will be expanded at this point, so the SIL code
will be generated for the fully augmented version.";
      }

      choice sil-edit {
        description
          "Type of edit callback code generation";
        leaf sil-edit1 {
          type empty;
          status deprecated;
          description
            "If present, then the deprecated first generation
'edit' functions will be generated for SIL or SIL-SA modes
instead of current 2nd generation 'edit' functions,
if code generation is being requested. Ignored otherwise.
The EDIT1 callbacks are now deprecated.
A warning will be generated if this parameter is used
for code generation.";
        }
        leaf sil-edit2 {
          type empty;
          description
            "If present, then the 2nd generation 'edit' functions
will be generated for SIL or SIL-SA modes
instead of first generation 'edit' functions,
if code generation is being requested.

The EDIT2 callbacks are now the default.
This parameter is no longer needed.";
        }
        leaf sil-edit3 {
          type empty;
          description
            "If present, then the 3nd generation 'edit' functions
will be generated for SIL or SIL-SA modes
instead of other generation 'edit' functions,
if code generation is being requested. Ignored otherwise.";
        }
      }  // choice sil-edit

      choice sil-get {
        description
          "Type of get callback code generation";
        leaf sil-get1 {
          type empty;
          status deprecated;
          description
            "If present, then the first generation 'get' functions
will be generated for SIL or SIL-SA modes
instead of second generation 'GET2' functions,
if code generation is being requested. Ignored otherwise.
The GET1 callbacks are now deprecated.
A warning will be generated if this parameter is used
for code generation.";
        }
        leaf sil-get2 {
          type empty;
          description
            "If present, then the 2nd generation 'get' functions
will be generated for SIL or SIL-SA modes
instead of first generation 'get' functions,
if code generation is being requested. Ignored otherwise.

The GET2 callbacks are now the default.
This parameter is no longer needed.";
        }
      }  // choice sil-get

      leaf-list sil-include {
        type string;
        ordered-by user;
        description
          "The name of an include file to inject into C files
when the conversion format is equal to 'c' or 'yc'.
An #include statement will be generated for each
instance of this parameter, in the order these
parameters are given.

The #include statements will be generated after
the system <include> statement and general
YumaPro include statements, but before the
YANG module specific include statements.";
      }

      leaf sil-nmda {
        type empty;
        description
          "If present, then the 2nd generation NMDA 'get' functions
will be generated for SIL or SIL-SA modes,
if code generation is being requested. Ignored otherwise.
The GET2 callbacks will be generated with extra NMDA
specific code for config=true data nodes. It is an error
if sil-nmda is selected but sil-get2 is not selected.";
      }

      leaf sil-sa {
        type empty;
        description
          "If present, then SIL-SA (subagent) code will be generated
instead of SIL (master-agent) code, if code generation
is being requested. Ignored otherwise.";
      }

      leaf simurls {
        type boolean;
        default "false";
        description
          "If 'true', and HTML translation is requested, then this
parameter will cause the format of URLs within links
to be generated in simplified form, for WEB development
engines such as CherryPy, which support this format.

Normal URL format (false):
   example.html?parm1=foo&parm2=bar#frag

Simplified URL format (true):
  example/foo/bar#frag
";
      }

      choice stats-report {
        default "statistics";
        case statistics {
          leaf stats {
            type enumeration {
              enum "none" {
                value 0;
                description
                  "No statistics reporting will be done.";
              }
              enum "brief" {
                value 1;
                description
                  "Brief statistics reporting will be done:
  - Complexity score
  - Total nodes
";
              }
              enum "basic" {
                value 2;
                description
                  "Basic statistics reporting will be done.";
              }
              enum "advanced" {
                value 3;
                description
                  "Advanced statistics reporting will be done.";
              }
              enum "all" {
                value 4;
                description
                  "All possible statistics reporting will be done.";
              }
            }
            default "none";
            description
              "Generate a statistics report for each input
module.

The following metrics are reported:
  ...
Developers: see ydump/yangstats.h";
          }

          leaf totals {
            type enumeration {
              enum "none" {
                value 0;
                description
                  "No statistics totals will be reported.";
              }
              enum "summary" {
                value 1;
                description
                  "Summary statistics totals will be
reported, based on the stats mode
that is requested.";
              }
              enum "summary-only" {
                value 2;
                description
                  "Only the summary statistics totals
will be reported, based on the stats
mode that is requested.  This mode
will cause all individual module
statistics reports to be generated,
and a summary for all input modules
will be generated instead.";
              }
            }
            default "none";
            description
              "Controls how stats totals are displayed.";
          }
        }  // case statistics
      }  // choice stats-report

      leaf tree-identifiers {
        type empty;
        description
          "Validate the file, write the list of object identifiers,
in tree format, that this [sub]module contains, then exit.

Each accessible object node is listed once,
including all child nodes.  Notifications and
RPC methods are considered top-level objects,
and have object identifiers as well as configuration
and state data..";
      }

      leaf unified {
        type boolean;
        default "false";
        description
          "If set to 'true', then submodules will be processed
within the main module, in a unified report,
instead of separately, one report for each file.

For translation purposes, this parameter will cause
any sub-modules to be treated as if they were defined in
the main module.  Actual definitions will be generated
instead of an 'include' directive, for each submodule.

If this mode is selected, then submodules entered
with the 'module' parameter will be ignored.

If 'false', a separate output file is generated for each
input file, so that XSD output and other reports
for a main module will not include information for
submodules.";
      }

      leaf urlstart {
        type string;
        description
          "If present, then this string will be used to prepend
to HREF links and URLs generated for SQL and HTML
translation.  It is expected to be a URL ending
with a directory path.  The trailing separator '/'
will be added if it is missing.

If not present (the default), then relative URLs,
starting with the file name will be generated instead.

For example, if this parameter is set to

   'http://example.com/public'

then the URL generated for the 'bar' type on line 53,
in the module FOO (version 2008-01-01) would be:

if versionnames=false:

   'http://example.com/public/FOO.html#bar.53'

OR

if versionnames=true (default):

   'http://example.com/public/FOO_2008-01-01.html#bar.53' ";
      }

      leaf versionnames {
        type boolean;
        default "true";
        description
          "If false, the default filenames will not contain
the module version string.
If true, the [sub]module name and version string
are both used to generate a default file name,
when the 'defnames' parameter is set to 'true'.";
      }

      uses ncxapp:NcxAppCommon;

      uses ncxapp:NewConfigParm;

      uses ncxapp:CommonFeatureParms;

      uses ncxapp:FeatureCodeParms;

      uses ncxapp:HomeParm;

      leaf xsd-schemaloc {
        type string;
        description
          "If present, then the schemaLocation attribute will
be generated during XSD translation.  This will be
done for the module being processed, and any modules
that are imported into that module.

If not present (the default), then the schemaLocation
attribute is not generated during XSD translation.
Relative URLs for include and import directives will
be generated, starting with the file name.

For example, if this parameter is set to

   'http://example.com/public'

then the schemaLocation XSD for the module test3
(version 10-19-2008) would be:

if versionnames=false:

  xsi:schemaLocation='http://netconfcentral.com/ns/test3
     http://example.com/public/test3.xsd'

OR

if versionnames=true (default):

  xsi:schemaLocation='http://netconfcentral.com/ns/test3
     http://example.com/public/test3_2008-10-19.xsd'
";
      }

      uses ywapp:YumaproHomeParm;

      uses ncxapp:ModuleParm;

      uses ncxapp:SubtreeParm;

      uses ncxapp:DeviationParm;

      uses ncxapp:OutputParm;

      uses ywapp:OcPatternParm;

      uses ncxapp:SubdirsParm;
    }  // container yangdump-pro
  }  // module yangdump-pro