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 "; 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. 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: .. If the 'versionnames=false' parameter is used, then the default filename will have the form: . 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 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."; } typedef FormatType { description "Conversion Output Formats."; type enumeration { enum xsd { description "Convert YANG to XSD"; } enum sql { description "Convert YANG to SQL history collection (TBD)"; } enum sqldb { description "Convert YANG to SQL input for netconfcentral.org database."; } enum html { description "Convert YANG to HTML documentation format."; } enum yang { description "Convert YANG to canonical YANG format."; } enum copy { description "Copy and rename the YANG file to canonical name format."; } enum h { description "Generate combined server instrumentation library H file. Compatible with version 1 'h' format"; } enum c { description "Generate combined server instrumentation library C file. Compatible with version 1 'c' format"; } enum cpp_test { description "Generate combined server instrumentation library CPP file for testing purposes."; } enum uh { description "Generate server instrumentation library user callback H file."; } enum uc { description "Generate server instrumentation library user callback C file."; } enum yh { description "Generate split server instrumentation library user callback H file."; } enum yc { description "Generate server instrumentation library user callback H file."; } enum yin { description "Convert YANG to YIN format."; } enum tg2 { description "Convert YANG to Turbogears 2 Source code files."; } } } typedef TocType { description "Requested table of contents type."; type enumeration { enum none; enum plain; enum menu; } default "menu"; } typedef ObjViewType { description "Requested view format for objects."; type enumeration { enum raw { description "output includes augment and uses clauses, not the expanded results of those clauses."; } enum cooked { description "output does not include augment or uses clauses, just the objects generated from those clauses (if any)."; } } default "raw"; } container yangdump { ncx:cli; ncx:default-parm module; description "CLI Parameter Set for the YANG Converter Application."; uses ncxapp:NcxAppCommon; uses ncxapp:CommonFeatureParms; uses ncxapp:FeatureCodeParms; uses ncxapp:HomeParm; uses ncxapp:ModuleParm; uses ncxapp:SubtreeParm; uses ncxapp:DeviationParm; uses ncxapp:OutputParm; leaf defnames { 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."; type boolean; default false; } leaf format { 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."; type FormatType; } leaf modversion { description "Validate the file, write the [sub]module name, version and source filespec, then exit."; type empty; } leaf exports { 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."; type empty; } leaf dependencies { 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."; type empty; } leaf identifiers { 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.."; type empty; } leaf html-div { description "If 'true', and HTML translation is requested, then this parameter will cause the output to be a single
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 element will be generated instead."; type boolean; default false; } leaf html-toc { 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."; type TocType; } leaf objview { 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."; type ObjViewType; } leaf show-errors { description "If present, list each error or warning number and its default message string. The program will exit after this is done."; type empty; } leaf simurls { 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 "; type boolean; default false; } uses ncxapp:SubdirsParm; choice stats-report { default statistics; case statistics { leaf stats { description "Generate a statistics report for each input module. The following metrics are reported: ... Developers: see ydump/yangstats.h"; type enumeration { enum none { description "No statistics reporting will be done."; } enum brief { description "Brief statistics reporting will be done: - Complexity score - Total nodes "; } enum basic { description "Basic statistics reporting will be done."; } enum advanced { description "Advanced statistics reporting will be done."; } enum all { description "All possible statistics reporting will be done."; } } default "none"; } leaf totals { description "Controls how stats totals are displayed."; type enumeration { enum none { description "No statistics totals will be reported."; } enum summary { description "Summary statistics totals will be reported, based on the stats mode that is requested."; } enum summary-only { 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"; } } } leaf tree-identifiers { 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.."; type empty; } leaf unified { 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."; type boolean; default false; } leaf urlstart { 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' "; type string; } leaf versionnames { 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'."; type boolean; default true; } leaf xsd-schemaloc { 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' "; type string; } } }