yangdump-pro(1)

NAME
yangdump-pro - validate YANG modules and convert them other formats.

SYNOPSIS

   yangdump-pro (module=value | subtree=value)+ [parameter=value...]

   yangdump-pro  --help [brief | normal | full]

   yangdump-pro  --version

   yangdump-pro  --show-errors

DESCRIPTION
yangdump-pro provides validation and translation of YANG data models. Information about a module or submodule can be generated as well. This version of yangdump-pro supports the YANG data modeling language defined in RFC 7950.

NOTE: This program is the same as yangdump-sdk starting in release 21.10-4. Either program can be used for code generation. The yangdump-sdk program has been removed starting in release 22.10T-9.

Refer to the online user manual for full details on using the yangdump-pro application:

https://docs.yumaworks.com/en/latest/yangdump/index.html

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 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 listing of all the accessible object identifiers that the file contains, in tree format, use the tree-identifiers parameter.

USAGE
Parameters can be entered in any order, and have the form:

   [start] name [separator [value]]

where:

    start == 0, 1, or 2 dashes (foo, -foo, --foo)

    name == parameter name

         Parameter name completion will be attempted
         if a partial name is entered.

    separator == whitespace or equals sign (foo=bar, foo bar)

    value == string value for the parameter.

         Strings with whitespace need to be double quoted
         (--foo="some string")

Some examples of valid command line parameters:

   foo=3
   -foo=3
   --foo=3
   foo 3
   foo=fred
   --foo "fred flintstone"

Partial parameter names can be entered if they are unique.

OPTIONS

--config=filespec
    The name of the configuration file to use. The default config file is /etc/yumapro/yangdump-pro.conf will be not be checked if this parameter is present.

--no-config
    If present, then no configuration file will be loaded, even if the default configuration file is present.

--defnames=boolean
    If true, output to a file with the default name for the format, in the current directory. The default value is 'false'.

    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.

--dependencies
    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.

--deviation=string
     This parameter identifies a YANG module that should only be checked for deviation statements for external modules. These will be collected and applied to the real module(s) being processed.

    Deviations are applied as patches to the target module. Since they are not identified in the target module at all (ala imports), they have to be specified explicitly, so they will be correctly processed. Zero or more instances of this parameter are allowed.

--doxygen-headers=boolean
    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. The default is 'true'.

--exports
    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.

--feature-code-default=enumeration
    If 'dynamic' (the default), then dynamic SIL feature code will be generated by default. If 'static', then static SIL feature code will be generated by default. If false, then features will be disabled by default.

--feature-disable=module:feature
    Identifies a feature which should be considered disabled.

--feature-dynamic=module:feature
    Identifies a dynamic feature for SIL code generation purposes. Zero or more entries are allowed.

--feature-enable-default=boolean
    If true (the default), then features will be enabled by default. If false, then features will be disabled by default.

--feature-enable=module:feature
    Identifies a feature which should be considered enabled. Zero or more entries are allowed.

--feature-static=module:feature
    Identifies a static feature for SIL code generation purposes. Zero or more entries are allowed.

--format=string
    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 translation formats are available:

        xsd:  XSD 1.0
       html:  XHTML 1.0
       yang:  Canonical YANG (in progress)
       copy:  Validate, and copy with a new name
        yin:  YIN format
          c:  Combined YumaPro and User SIL C module
          h:  Combined YumaPro and User SIL H file
         bc:  Wrapper module for a SIL Bundle C module
         bh:  Wrapper module for a SIL Bundle H file
         uc:  User part of a split SIL C module
         uh:  User part of a split SIL H file
         yc:  YumaPro part of a split SIL C module
         yh:  YumaPro part of a split SIL H file

--help
    Print this help text and exit. The help-mode choice (--brief, --normal, or --full) may also be present to control the amount of help text printed.

--home=dirspec
    Directory specification for the home directory to use instead of HOME.

--html-div
    If 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.

--html-toc=string
    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.

--identifiers
    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..

--indent=number
    Number of spaces to indent (0..9) in formatted output. The default is 2 spaces.

--lang-errors
    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.

--log=filespec
    Filespec for the log file to use instead of STDOUT. If this string begins with a '~' character, then a username is expected to follow or a directory separator character. If it begins with a '$' character, then an environment variable name is expected to follow.

--log-append
    If present, the log will be appended not over-written. If not, the log will be over-written. Only meaningful if the log parameter is also present.

--log-level=enumeration
    Sets the debug logging level for the program.

--megarange-action=string
    Specifies the action to perform using the megarange-file parameter file.

    The following actions are defined:

                 - template: generate a megarange.json template file

                 - new: generate the data for an initial control file using
                   the header information.  Uses 350 SIDs per
                   allocation.

                 - autonew: Automatically generate the header and data
                   an initial control file and SID file set.

                 - new-sid: generate all the initial SID files

                 The following operations are planned for a future release:

                 - update: generate the updated data for an existing
                   control file using the header and data information

                 - autoupdate: generate the updated data and SID files
                   for an existing control file and set of SID files
                   using the header and data information.

                 - update-sid: generate all the updated SID files
                   based on the specified megarange file.

--megarange-file=string
    Specifies a YANG Megarange file for a YANG repo. The string contains a filespec for the Megarange control file to be used for megarange parameter input.

--modpath=list
    Directory search path for YANG and YIN files. Overrides the YUMAPRO_MODPATH environment variable.

--module=string
    YANG or YIN source module name to validate and convert.

    If this string represents a filespec, ending with the .yang or .yin extension, then only that file location will be checked.

    If this string represents a module name, then the module search path will be checked for a file the .yang or .yin extension.

    If this string begins with a '~' character, then a username is expected to follow or a directory separator character. If it begins with a '$' character, then an environment variable name is expected to follow.

          ~/some/path ==> <my-home-dir>/some/path

          ~fred/some/path ==> <fred-home-dir>/some/path

          $workdir/some/path ==> <workdir-env-var>/some/path

--modversion
    Validate the file, write the [sub]module name, version and source filespec, then exit.

--objview=string
    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. Values:

       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.

--output=filespec
    Output file name to use. Default is STDOUT if none specified and the defname parameter is also missing.

    If this parameter represents an existing directory, then the defnames parameter will be assumed by default, and the translation output file(s) will be generated in the specified directory.

    If this parameter represents a file name, then the defnames parameter will be ignored, and all translation output will be directed to the specified file.

    If this string begins with a '~' character, then a username is expected to follow or a directory separator character. If it begins with a '$' character, then an environment variable name is expected to follow.

          ~/some/path ==> <my-home-dir>/some/path

          ~fred/some/path ==> <fred-home-dir>/some/path

          $workdir/some/path ==> <workdir-env-var>/some/path

--quiet-mode
    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. The default is not present.

--show-errors
    If present, list each error or warning number and its default message string. The program will exit after this is done.

--sid-finalize
    If present, generate a final published YANG SID file. Argument is the same as pyang parameter. If missing then an unstable SID file will be generated.

--sid-generate-file=string
    If present, generate a YANG SID file for a YANG module. Argument is the same as pyang parameter.

    The string follows the format:

        [range-start]:[range-size]

    If the range starts at 10000 and the range size is 50 then the string 10000:50 would be used.

    There must be one --module parameter entered or the request will be rejected with an error.

--sil-bundle=string
    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.

    Generate a SIL bundle. Create combined SIL code for multiple YANG modules at once. Needed to support automatic generation of augment-stmt code. If the format parameter is present, then it must be equal to one of the 'C' or 'H' formats. If not set, then all files in the SIL bundle will be created. Forces defnames parameter to true.

--sil-edit2
    If present, then the 2nd generation 'edit' functions will be generated for SIL or SIL-SA modes instead of other generation 'edit' functions, if code generation is being requested. The EDIT1 callbacks are now deprecated. The default is to use edit3 mode so set this parameter to enable edit2 mode.

--sil-edit3
    If present, then the 3rd generation 'edit' functions will be generated for SIL or SIL-SA modes instead of other generation 'edit' functions, if code generation is being requested. The default is to use this mode so this parameter can be omitted.

--sil-get2
    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 GET1 callbacks are now deprecated. A warning will be generated if this parameter is not used for code generation.

--sil-include=filename
    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. Zero or more instances of this parameter are allowed.

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

--sil-nmda
    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.

--sil-sa
    If present, then SIL-SA (subagent) code will be generated instead of SIL (master-agent) code, if code generation is being requested. Ignored otherwise.

--simurls=boolean
    If true, and if 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. The default is false.

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

       Simplified URL format:
         example/foo/bar#frag

--stats=enumeration
    Controls YANG usage statistics report generation.
       enum values:
          none: (default)
             No statistics reporting will be done.
          brief:
            Brief statistics reporting will be done:
              - Complexity score
              - Total nodes
          basic:
             Basic statistics reporting will be done.
          advanced:
             Advanced statistics reporting will be done.
          all:
             All possible statistics reporting will be done.

--subdirs=boolean
    If false, the file search paths for modules, scripts, and data files will not include sub-directories if they exist in the specified path.

    If true, then these file search paths will include sub-directories, if present. Any directory name beginning with a dot (.) character, or named CVS, will be ignored. This is the default mode.

--subtree=string
    Path specification of the directory subtree to convert. All of the YANG and YIN source modules contained in the specified directory sub-tree will be processed.

    If the format parameter is present, then one file with the default name will be generated for each YANG or YIN file found in the sub-tree.

    Note that symbolic links are not followed during the directory traversal. Only real directories will be searched and regular files will be checked as modules. Processing will continue to the next file if a module contains errors.

    If this string begins with a '~' character, then a username is expected to follow or a directory separator character. If it begins with a '$' character, then an environment variable name is expected to follow.

    This parameter may be present zero or more times.

          ~/some/path ==> <my-home-dir>/some/path

          ~fred/some/path ==> <fred-home-dir>/some/path

          $workdir/some/path ==> <workdir-env-var>/some/path

--totals=enumeration
    Controls summary YANG usage statistics report generation. Must be used with the '--stats' parameter.
       enum values:
          none: (default)
             No summary statistics reporting will be done.
          summary:
             Summary statistics totals will be
             reported, based on the stats mode
             that is requested.
          summary-only
             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.

--tree-identifiers
    Validate the file, write the hierarchy of node names 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..

--unified=boolean
    If 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 false (the default), then 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.

    If this parameter is set to true, then submodules entered with the module parameter will be ignored.

--urlstart=string
    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://acme.com/public'

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

      if no-versionnames set:

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

       OR

      if no-versionnames not set (default):

       'http://acme.com/public/FOO_2008-01-01.html#bar.53'

--version
    Print yangdump-pro version string and exit.

--versionnames=boolean
    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 output parameter is used. This flag will cause filenames and links to be generated which do not contain the version string. The default value is true.

--warn-error=boolean
    Control whether all warnings are elevated to errors. The default value is false.

--warn-idlen=number
     Control whether identifier length warnings will be generated. The value zero disables all identifier length checking. If non-zero, then a warning will be generated if an identifier is defined which has a length is greater than this amount. range: 0 | 8 .. 1023. The default value is 64.

--warn-linelen=number
    Control whether line length warnings will be generated. The value zero disables all line length checking. If non-zero, then a warning will be generated if the line length is greater than this amount. Tab characters are counted as 8 spaces. range: 0 | 40 .. 4095. The default value is 72.

--warn-off=number
    Control whether the specified warning number will be generated and counted in the warning total for the module being parsed. range: 1000 ..1999. This parameter may be entered zero or more times.

--warn-off-yang=boolean
    Control whether all YANG warnings are enabled or disabled.

--warn-up=number
    Control whether the specified warning number will be elevated to an error and counted in the error total for the module being parsed. range: 1000 .. 1999. This parameter may be entered zero or more times.

--with-ocpattern=boolean
    If true, then OpenConfig patterns will be checked. If the module name starts with the string 'openconfig-' then all pattern statements within that module are treated as POSIX patterns, not YANG patterns. If false, then the pattern statements in all modules will be checked as YANG patterns. The default value is false.

--with-yang-metadata=boolean
    If 'true' then the YANG compiler will load the 'ietf-yang-metadata' module and use any md:annotation statements that are found.

    If 'false' then this module will not be loaded and all 'md:annotation' statements will be ignored.

    Note that enabling this parameter will cause a YANG module to be rejected with errors if any annotations are found which do not conform to the definition in RFC 7952.

    This parameter must be entered in the command line to have any effect. Do not use this parameter in a config file since this is too late in the initialization process to change the setting. The default is true. Introduced in 25.10-3.

--xsd-schemaloc=string
    If present, then this string will be used to prepend to output XSD filenames, when generating schemaLocation clauses. It is expected to be a URL ending with a directory path. The trailing separator '/' will be added if it is missing. This parameter is also prepended to URLs generated fpr include and import directives within the XSD.

    If not present (the default), then the schemaLocation element 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://acme.com/public'

    then the schemaLocation XSD for the module FOO (version 01-01-2008) would be:

       if no-versionnames set:

          'http://acme.com/public/FOO.xsd'

      OR

       if no-versionnames not set (default):

          'http://acme.com/public/FOO_2008-01-01.xsd'

--yumapro-home=string
    Directory for the YumaPro project root to use. If present, this directory location will override the YUMAPRO_HOME environment variable, if it is present. If a zero-length string is entered, then the YUMAPRO_HOME environment variable will be ignored.

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, version, or show-errors parameters is entered, one of these input file parameters is mandatory. Each of these parameters may be entered multiple times. The default parameter for yangdump-pro is 'module', so these commands are equivalent:

   yangdump-pro --module=foo

   yangdump-pro foo

Note that 'foo' must not match another parameter name. If it does, the module parameter name must be used for that module. For example,

   yangdump-pro --module=help

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 parameter)
  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.

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 to use instead.

The defname parameter can be used to generate a default filename in the current directory for the output.

   E.g., the default XSD filename is <name>_<version>.xsd.

This is the default mode when subtree input mode is selected.

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
     debug3: print very verbose debugging trace info
     debug4: print maximum debugging trace info

ENVIRONMENT
The following optional environment variables can be used to control module search behavior:

HOME
    The user's home directory (e.g., /home/andy)

YUMAPRO_HOME
    The root of the user's YumaPro work directory (e.g., /home/andy/swdev/netconf)

YUMAPRO_INSTALL
    The root of the directory that yangdump-pro is installed on this system (default is, /usr/share/yumapro)

YUMAPRO_MODPATH
    Colon-separated list of directories to search for modules and submodules.

    (e.g.: './workdir/modules:/home/andy/test-modules')

    The modpath parameter will override this environment variable, if both are present.

CONFIGURATION FILES

yangdump-pro.conf
    YANG config file The default is: /etc/yumapro/yangdump-pro.conf

    An ASCII configuration file format is supported to store command line parameters.

    The config parameter is used to specify a specific config file, otherwise the default config file will be checked.

       - A hash mark until EOLN is treated as a comment
       - All text is case-sensitive
       - Whitespace within a line is not significant
       - Whitespace to end a line is significant/
         Unless the line starts a multi-line string,
         an escaped EOLN (backslash EOLN) is needed
         to enter a leaf on multiple lines.
       - For parameters that define lists, the key components
         are listed just after the parameter name, without
         any name,  e.g.,

                interface eth0 {
                  # name = eth0 is not listed inside the braces
                  ifMtu 1500
                  ifName mySystem
                }

    A config file can contain any number of parameter sets for different programs.

    Each program must have its own section, identifies by its name:

         # this is a comment
         yangdump-pro {
            log-level debug
            output "~/swdev/testfiles"
         }

         netconfd-pro {
            ...
         }

FILES
The following data files must be present in the module search path in order for this program to function:

  * YANG module library
    default: /usr/share/yumapro/modules/

DIAGNOSTICS
Internal diagnostics may generate the following type of message if any bugs are detected at runtime:

    [E0]
         filename.c:linenum error-number (error-msg)

AUTHOR
YumaWorks, Inc., <support at yumaworks dot com>

SEE ALSO
netconfd-pro(1) yangcli-pro(1) yangdiff-pro(1)