module yangdump {
yang-version 1;
namespace "http://netconfcentral.org/ns/yangdump";
prefix "yd";
import yuma-ncx {
prefix "ncx";
}
import yuma-app-common {
prefix "ncxapp";
}
organization "Netconf Central";
contact
"Andy Bierman <andy at netconfcentral.org>";
description
"yangdump 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) YUMA_MODPATH environment var (or set by modpath parameter)
3) $HOME/modules directory
4) $YUMA_HOME/modules directory
5) $YUMA_INSTALL/modules directory OR
default install module location, '/usr/share/yuma/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.
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
";
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.";
}
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 server instrumentation library H file.";
}
enum "c" {
value 7;
description
"Generate server instrumentation library C file.";
}
enum "yin" {
value 8;
description "Convert YANG to YIN format.";
}
enum "tg2" {
value 9;
description
"Convert YANG to Turbogears 2 Source code files.";
}
}
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 {
description
"CLI Parameter Set for the YANG Converter Application.";
leaf config {
type string;
description
"The name of the configuration file to use.
Any parameter except this one can be set in the config file.
The default config file will be not be checked if this
parameter is present.";
}
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-list deviation {
type yt:NcModuleSpec;
description
"YANG deviation file.
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.
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 with the module name and 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
";
}
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 feature-code-default {
type enumeration {
enum "static" {
value 0;
description
"The default behavior for feature behavior
is to use statically defined features at
compile-time.";
}
enum "dynamic" {
value 1;
description
"The default behavior for feature behavior
is to use dynamically defined features at
load-time.";
}
}
default "dynamic";
description
"The default feature code generation type.";
}
leaf-list feature-disable {
type yt:FeatureSpec;
description
"Identifies a feature which should be considered
disabled.";
}
leaf-list feature-dynamic {
type yt:FeatureSpec;
description
"Identifies a feature which is configured to be a
static feature, and therefore set at compile time.";
}
leaf-list feature-enable {
type yt:FeatureSpec;
description
"Identifies a feature which should be considered
enabled.";
}
leaf feature-enable-default {
type boolean;
default "true";
description
"If true, then features will be enabled by default.
If false, then features will be disabled by default.";
}
leaf-list feature-static {
type yt:FeatureSpec;
description
"Identifies a feature which is configured to be a
static feature, and therefore set at compile time.";
}
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 help {
type empty;
description "Print program help file and exit.";
}
choice help-mode {
default "normal";
leaf brief {
type empty;
description "Show brief help text";
}
leaf full {
type empty;
description "Show full help text";
}
leaf normal {
type empty;
description "Show normal help text";
}
} // choice help-mode
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 indent {
type yt:IndentType;
description
"Number of spaces to indent (0..9) in formatted output.";
}
leaf log {
type string;
description
"Filespec for the log file to use instead of STDOUT.";
}
leaf log-append {
type empty;
description
"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.";
}
leaf log-level {
type yt:NcDebugType;
description
"Sets the debug logging level for the program.";
}
leaf modpath {
type yt:NcPathList;
description
"Directory search path for YANG or YIN modules.
Overrides the YUMA_MODPATH environment variable.";
}
leaf-list module {
type yt:NcModuleSpec;
description "YANG source module name to use.";
}
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 output {
type string;
description
"Output directory or file name to use.
Default is STDOUT if none specified and the
'defnames' parameter is also set to 'false'.
If this parameter represents an existing directory,
then the 'defnames' parameter will be set to 'true' 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
If this parameter is present, and identifies
an existing directory, then any translation output
files will be generated in that directory. If that
parameter identifies a file, then that one file will
be used for output.
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.";
}
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 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 subdirs {
type boolean;
default "true";
description
"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.";
}
leaf-list subtree {
type yt:NcPathSpec;
description
"Path specification of the directory subtree to use.
All of the YANG source modules contained in the
specified directory sub-tree will be processed.
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.
~/some/path ==> <my-home-dir>/some/path
~fred/some/path ==> <fred-home-dir>/some/path
$workdir/some/path ==> <workdir-env-var>/some/path";
}
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 version {
type empty;
description "Print program version string and exit.";
}
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'.";
}
leaf warn-idlen {
type uint32 {
range "0 | 8 .. 1023";
}
default "64";
description
"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.";
}
leaf warn-linelen {
type uint32 {
range "0 | 40 .. 4095";
}
default "72";
description
"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.";
}
leaf-list warn-off {
type uint32 {
range "400 .. 899";
}
description
"Control whether the specified warning number will be
generated and counted in the warning total for the
module being parsed.";
}
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'
";
}
leaf yuma-home {
type string;
description
"Directory for the yuma project root to use.
If present, this directory location will
override the 'YUMA_HOME' environment variable,
if it is present. If a zero-length string is
entered, then the YUMA_HOME environment variable
will be ignored.";
}
ncx:cli;
ncx:default-parm "module";
} // container yangdump
} // module yangdump
