From 987f59c07ae21b388e0221904111140b935a9568 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Martin=20Bj=C3=B6rklund?= Date: Wed, 1 Nov 2023 09:57:38 +0100 Subject: [PATCH] Updates for 2.6.0 release --- CHANGELOG.md | 26 + CONTRIBUTORS | 8 +- man/man1/json2xml.1 | 225 ++-- man/man1/pyang.1 | 2876 +++++++++++++++++------------------------- man/man1/yang2dsdl.1 | 674 ++++------ pyang/__init__.py | 4 +- 6 files changed, 1541 insertions(+), 2272 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 3aa0d8e8..88dfa155 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,29 @@ +* 2.6.0 - 2023-11-03 +``` + lots of improvements to the UML plugin + thanks to Nick Hancock + lots of improvements to build and test + thanks to @ubaumann + fix invalid regular expression on Windows + thanks to Jan Kundrát + fix script issues on Windows + thanks to Jan Kundrát + fix validation of when expressions for 1.1 modules + thanks to Derek Ingrouville + fixes for revision-date in depend output + thanks to Slavomir Mazur + + #845 - sid item status + #844 - tree max line length issue + #837 - test fixes + #821 - typo in jstree output + #818 - issue with decimal64 defaults in json2xml + #809 - revision-date parsed wrong if multiple "@" found in path + thanks to Michael Littlejohn + #729 - handle name scoping of 1.1 submodules in XPath expressions + #516 - crash in tree output +``` + * 2.5.3 - 2022-03-30 ``` added support for checking 'ancestor' and 'ancestor-or-self' XPATH axes diff --git a/CONTRIBUTORS b/CONTRIBUTORS index bbf9082f..1871c0dc 100644 --- a/CONTRIBUTORS +++ b/CONTRIBUTORS @@ -11,17 +11,22 @@ Fred Gan Joe Gladston Pravin Gohite Yan Gorelik +Nick Hancock Giles Heron +Derek Ingrouville Jozef Janitor Robin Jarry Mahesh Jethanandani Denys Knertser Mallikarjunarao Kosuri Miroslav Kovac +Jan Kundrát Balázs Lengyel +Michael Littlejohn Miroslav Los Ladislav Lhotka William Lupton +Slavomir Mazur Glenn Matthews Paul Merlo Ganesh Nalawade @@ -40,6 +45,7 @@ Nick Weeds Jonathan Yang Quentin Young Huaian Zhou +@cygnus2048 @gribok @lemikev -@cygnus2048 \ No newline at end of file +@ubaumann diff --git a/man/man1/json2xml.1 b/man/man1/json2xml.1 index 7f4a27f9..463c7c1f 100644 --- a/man/man1/json2xml.1 +++ b/man/man1/json2xml.1 @@ -1,167 +1,92 @@ -'\" t -.\" Title: json2xml -.\" Author: Ladislav Lhotka -.\" Generator: DocBook XSL Stylesheets v1.78.1 -.\" Date: 2022-03-30 -.\" Manual: pyang manual -.\" Source: json2xml-2.5.3 -.\" Language: English +.\" Automatically generated by Pandoc 2.9.2.1 .\" -.TH "JSON2XML" "1" "2022\-03\-30" "json2xml\-2\&.5\&.3" "pyang manual" -.\" ----------------------------------------------------------------- -.\" * Define some portability stuff -.\" ----------------------------------------------------------------- -.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.\" http://bugs.debian.org/507673 -.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html -.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.ie \n(.g .ds Aq \(aq -.el .ds Aq ' -.\" ----------------------------------------------------------------- -.\" * set default formatting -.\" ----------------------------------------------------------------- -.\" disable hyphenation -.nh -.\" disable justification (adjust text to left margin only) -.ad l -.\" ----------------------------------------------------------------- -.\" * MAIN CONTENT STARTS HERE * -.\" ----------------------------------------------------------------- -.SH "NAME" -json2xml \- translates JSON documents conforming to a YANG data model into XML\&. -.SH "SYNOPSIS" -.HP \w'\fBjson2xml\fR\ 'u -\fBjson2xml\fR [\-t\ \fItarget\fR] [\-o\ \fIoutput_file\fR] \fIdriver_file\fR \fIjson_file\fR -.HP \w'\fBjson2xml\fR\ 'u -\fBjson2xml\fR \-h | \-\-help -.SH "DESCRIPTION" -.PP -This program translates -\fIjson_file\fR -into XML using the procedure specified in -\m[blue]\fBRFC 7951\fR\m[]\&\s-2\u[1]\d\s+2\&. -.PP -The translation uses a second input file, -\fIdriver_file\fR, which contains a concise JSON representation of the YANG data model to which -\fIjson_file\fR -should conform, at least structurally\&. Normally, -\fIdriver_file\fR -is obtained as the -\fIjtox\fR -output of -\fBpyang\fR\&. -.PP -Using "\-" (hyphen) in place of -\fIjson_file\fR -instructs the program to read a JSON document from the standard input\&. -.PP -The -\fItarget\fR -argument specifies the document (root) element for the output XML document\&. This encapsulation is necessary because the input JSON document may contain multiple JSON objects at the top level\&. Supported values for the -\fItarget\fR -argument are: -.PP +.TH "JSON2XML" "1" "2023-11-03" "json2xml-2.6.0" "User Manual" +.hy +.SH NAME +.PP +json2xml - translates JSON documents conforming to a YANG data model +into XML. +.SH SYNOPSIS +.PP +\f[B]json2xml\f[R] [-t target] [-o \f[I]output_file\f[R]] +\f[I]driver_file\f[R] \f[I]json_file\f[R] +.PP +\f[B]json2xml\f[R] -h | --help +.SH DESCRIPTION +.PP +This program translates \f[I]json_file\f[R] into XML using the procedure +specified in \f[B]RFC 7951\f[R]. +.PP +The translation uses a second input file, \f[I]driver_file\f[R], which +contains a concise JSON representation of the YANG data model to which +\f[I]json_file\f[R] should conform, at least structurally. +Normally, \f[I]driver_file\f[R] is obtained as the \f[I]jtox\f[R] output +of \f[B]pyang\f[R]. +.PP +Using \[dq]-\[dq] (hyphen) in place of \f[I]json_file\f[R] instructs the +program to read a JSON document from the standard input. +.PP +The \f[I]target\f[R] argument specifies the document (root) element for +the output XML document. +This encapsulation is necessary because the input JSON document may +contain multiple JSON objects at the top level. +Supported values for the \f[I]target\f[R] argument are: +.TP data -.RS 4 -The document element will be \&. This is the default\&. -.RE -.PP +The document element will be . +This is the default. +.TP config -.RS 4 -The document element will be \&. -.RE -.PP -The XML prefix "nc" represents the standard NETCONF namespace with URI "urn:ietf:params:xml:ns:netconf:base:1\&.0"\&. -.SH "OPTIONS" -.PP -\fB\-t\fR \fItarget\fR, \fB\-\-target\fR \fItarget\fR -.RS 4 -Specifies the target type of the output XML document, i\&.e\&. its document element\&. The default is -\fBdata\fR\&. -.RE -.PP -\fB\-o\fR \fIoutput_file\fR, \fB\-\-output\fR \fIoutput_file\fR -.RS 4 -Write output to -\fIoutput_file\fR -instead of the standard output\&. -.RE -.PP -\fB\-h\fR, \fB\-\-help\fR -.RS 4 -Displays help screen and exits\&. -.RE -.SH "EXAMPLE" -.sp -.if n \{\ -.RS 4 -.\} -.nf -$ pyang \-f jtox \-o dhcp\&.jtox dhcp\&.yang -.fi -.if n \{\ -.RE -.\} -.sp -.if n \{\ -.RS 4 -.\} +The document element will be . +.PP +The XML prefix \[dq]nc\[dq] represents the standard NETCONF namespace +with URI \[dq]urn:ietf:params:xml:ns:netconf:base:1.0\[dq]. +.SH OPTIONS +.TP +\f[B]-t\f[R] \f[I]target\f[R], \f[B]target\f[R] \f[I]target\f[R] +Specifies the target type of the output XML document, i.e., its document +element. +The default is \f[B]data\f[R]. +.TP +\f[B]-o\f[R] \f[I]output_file\f[R], \f[B]--output\f[R] \f[I]output_file\f[R] +Write output to \f[I]output_file\f[R] instead of the standard output. +.TP +\f[B]-h\f[R], \f[B]--help\f[R] +Displays help screen and exits. +.SH EXAMPLES +.IP .nf -$ json2xml \-o dhcp\-data\&.xml dhcp\&.jtox dhcp\-data\&.json +\f[C] +$ pyang -f jtox -o dhcp.jtox dhcp.yang + +$ json2xml -o dhcp-data.xml dhcp.jtox dhcp-data.json +\f[R] .fi -.if n \{\ -.RE -.\} .PP -The first command generates the driver file -dhcp\&.jtox, which is then used for translating JSON file -dhcp\-data\&.json -to XML file -dhcp\-data\&.xml\&. -.SH "DIAGNOSTICS" -.PP -\fBjson2xml\fR -return codes have the following meaning: +The first command generates the driver file dhcp.jtox, which is then +used for translating JSON file dhcp-data.json to XML file dhcp-data.xml. +.SH DIAGNOSTICS .PP +\f[B]json2xml\f[R] return codes have the following meaning: +.TP 0 -.RS 4 No error (normal termination) -.RE -.PP +.TP 1 -.RS 4 One of the input files cannot be read -.RE -.PP +.TP 2 -.RS 4 Error in command line arguments -.RE -.PP +.TP 3 -.RS 4 JSON to XML translation failed -.RE -.SH "SEE ALSO" +.SH SEE ALSO .PP -\m[blue]\fBRFC 7951\fR\m[]\&\s-2\u[1]\d\s+2, -\fBpyang\fR(1), -\m[blue]\fBJSON\fR\m[]\&\s-2\u[2]\d\s+2\&. -.SH "AUTHOR" +\f[B]RFC 7951\f[R], \f[B]pyang\f[R](1) +.SH AUTHOR .PP -\fBLadislav Lhotka\fR <\&lhotka@nic\&.cz\&> -.br -CZ\&.NIC -.RS 4 -.RE -.SH "NOTES" -.IP " 1." 4 -RFC 7951 -.RS 4 -\%http://tools.ietf.org/html/rfc7951 -.RE -.IP " 2." 4 -JSON -.RS 4 -\%http://www.json.org/ -.RE +\f[B]Ladislav Lhotka\f[R] +.PD 0 +.P +.PD +CZ.NIC diff --git a/man/man1/pyang.1 b/man/man1/pyang.1 index 12634c18..606b96f3 100644 --- a/man/man1/pyang.1 +++ b/man/man1/pyang.1 @@ -1,1820 +1,1304 @@ -'\" t -.\" Title: pyang -.\" Author: Martin Björklund -.\" Generator: DocBook XSL Stylesheets v1.78.1 -.\" Date: 2022-03-30 -.\" Manual: pyang manual -.\" Source: pyang-2.5.3 -.\" Language: English +.\" Automatically generated by Pandoc 2.9.2.1 .\" -.TH "PYANG" "1" "2022\-03\-30" "pyang\-2\&.5\&.3" "pyang manual" -.\" ----------------------------------------------------------------- -.\" * Define some portability stuff -.\" ----------------------------------------------------------------- -.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.\" http://bugs.debian.org/507673 -.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html -.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.ie \n(.g .ds Aq \(aq -.el .ds Aq ' -.\" ----------------------------------------------------------------- -.\" * set default formatting -.\" ----------------------------------------------------------------- -.\" disable hyphenation -.nh -.\" disable justification (adjust text to left margin only) -.ad l -.\" ----------------------------------------------------------------- -.\" * MAIN CONTENT STARTS HERE * -.\" ----------------------------------------------------------------- -.SH "NAME" -pyang \- validate and convert YANG modules to various formats -.SH "SYNOPSIS" -.HP \w'\fBpyang\fR\ 'u -\fBpyang\fR [\-\-verbose] [\-\-canonical] [\-\-strict] [\-\-lint] [\-\-ietf] [\-\-lax\-quote\-checks] [\-\-lax\-xpath\-checks] [\-\-features\ \fIfeatures\fR] [\-\-exclude\-features\ \fIfeatures\fR] [\-\-max\-status\ \fImaxstatus\fR] [\-\-hello] [\-\-implicit\-hello\-deviations] [\-\-check\-update\-from\ \fIoldfile\fR] [\-o\ \fIoutfile\fR] [\-t\ \fItransform\fR] [\-f\ \fIformat\fR] [\-p\ \fIpath\fR] [\-W\ \fIwarning\fR] [\-E\ \fIerror\fR] \fIfile\fR... -.HP \w'\fBpyang\fR\ 'u -\fBpyang\fR [\-\-sid\-list] \-\-sid\-generate\-file {count | \fIentry\-point:size\fR} \fIyang\-filename\fR -.HP \w'\fBpyang\fR\ 'u -\fBpyang\fR [\-\-sid\-list] \-\-sid\-update\-file \fIsid\-filename\fR \fIyang\-filename\fR [\-\-sid\-extra\-range\ {count\ |\ \fIentry\-point:size\fR}] -.HP \w'\fBpyang\fR\ 'u -\fBpyang\fR [\-\-sid\-list] \-\-sid\-check\-file \fIsid\-filename\fR \fIyang\-filename\fR -.HP \w'\fBpyang\fR\ 'u -\fBpyang\fR \-h | \-\-help -.HP \w'\fBpyang\fR\ 'u -\fBpyang\fR \-v | \-\-version -.PP -One or more -\fIfile\fR -parameters may be given on the command line\&. They denote either YANG modules to be processed (in YANG or YIN syntax) or, using the -\fB\-\-hello\fR -switch, a server message conforming to -\m[blue]\fBRFC 6241\fR\m[]\&\s-2\u[1]\d\s+2 -and -\m[blue]\fBRFC 6020\fR\m[]\&\s-2\u[2]\d\s+2, which completely defines the data model \- supported YANG modules as well as features and capabilities\&. In the latter case, only one -\fIfile\fR -parameter may be present\&. -.PP -If no files are given, -\fBpyang\fR -reads input from stdin, which must be one module or a server message\&. -.SH "DESCRIPTION" -.PP -The -\fBpyang\fR -program is used to validate YANG modules (\m[blue]\fBRFC 6020\fR\m[]\&\s-2\u[2]\d\s+2 -and -\m[blue]\fBRFC 7950\fR\m[]\&\s-2\u[3]\d\s+2)\&. It is also used to convert YANG modules into equivalent YIN modules\&. From a valid module a hybrid DSDL schema (\m[blue]\fBRFC 6110\fR\m[]\&\s-2\u[4]\d\s+2) can be generated\&. -.PP -If no -\fIformat\fR -is given, the specified modules are validated, and the program exits with exit code 0 if all modules are valid\&. -.SH "OPTIONS" -.PP -\fB\-h\fR \fB\-\-help\fR -.RS 4 -Print a short help text and exit\&. -.RE -.PP -\fB\-v\fR \fB\-\-version\fR -.RS 4 -Print the version number and exit\&. -.RE -.PP -\fB\-e\fR \fB\-\-list\-errors\fR -.RS 4 -Print a listing of all error codes and messages pyang might generate, and then exit\&. -.RE -.PP -\fB\-\-print\-error\-code\fR -.RS 4 -On errors, print the symbolic error code instead of the error message\&. -.RE -.PP -\fB\-\-print\-error\-basename\fR -.RS 4 -On errors, print only the base file name independent of its module path location\&. -.RE -.PP -\fB\-Werror\fR -.RS 4 -Treat warnings as errors\&. -.RE -.PP -\fB\-Wnone\fR -.RS 4 -Do not print any warnings\&. -.RE -.PP -\fB\-W\fR \fIerrorcode\fR -.RS 4 -Treat -\fIerrorcode\fR -as a warning, even if -\fB\-Werror\fR -is given\&. -\fIerrorcode\fR -must be a warning or a minor error\&. -.sp -Use -\fB\-\-list\-errors\fR -to get a listing of all errors and warnings\&. -.sp -The following example treats all warnings except the warning for unused imports as errors: -.sp -.if n \{\ -.RS 4 -.\} +.TH "PYANG" "1" "2023-11-03" "pyang-2.6.0" "User Manual" +.hy +.SH NAME +.PP +pyang - validate and convert YANG modules to various formats +.SH SYNOPSIS +.PP +\f[B]pyang\f[R] [--verbose] [--canonical] [--strict] [--lint] [--ietf] +[--lax-quote-checks] [--lax-xpath-checks] [--features +\f[I]features\f[R]] [--exclude-features \f[I]features\f[R]] +[--max-status \f[I]maxstatus\f[R]] [--hello] +[--implicit-hello-deviations] [--check-update-from \f[I]oldfile\f[R]] +[-o \f[I]outfile\f[R]] [-t \f[I]transform\f[R]] [-f \f[I]format\f[R]] +[-p \f[I]path\f[R]] [-W \f[I]warning\f[R]] [-E \f[I]error\f[R]] +\f[I]file\f[R]\&... +.PP +\f[B]pyang\f[R] [--sid-list] --sid-generate-file {count | +\f[I]entry-point:size\f[R]} \f[I]yang-filename\f[R] +.PP +\f[B]pyang\f[R] [--sid-list] --sid-update-file \f[I]sid-filename\f[R] +\f[I]yang-filename\f[R] [--sid-extra-range count +\f[I]entry-point:size\f[R]] +.PP +\f[B]pyang\f[R] [--sid-list] --sid-check-file \f[I]sid-filename\f[R] +\f[I]yang-filename\f[R] +.PP +\f[B]pyang\f[R] -h | --help +.PP +\f[B]pyang\f[R] -v --version +.PP +One or more \f[I]file\f[R] parameters may be given on the command line. +They denote either YANG modules to be processed (in YANG or YIN syntax) +or, using the \f[B]--hello\f[R] switch, a server message +conforming to \f[B]RFC 6241\f[R] and \f[B]RFC 6020\f[R], which +completely defines the data model - supported YANG modules as well as +features and capabilities. +In the latter case, only one \f[I]file\f[R] parameter may be present. +.PP +If no files are given, \f[B]pyang\f[R] reads input from stdin, which +must be one module or a server message. +.SH DESCRIPTION +.PP +The \f[B]pyang\f[R] program is used to validate YANG modules (\f[B]RFC +6020\f[R] and \f[B]RFC 7950\f[R]). +It is also used to convert YANG modules into equivalent YIN modules. +From a valid module a hybrid DSDL schema (\f[B]RFC 6110\f[R]) can be +generated. +.PP +If no \f[I]format\f[R] is given, the specified modules are validated, +and the program exits with exit code 0 if all modules are valid. +.SH OPTIONS +.TP +\f[B]-h\f[R], \f[B]--help\f[R] +Print a short help text and exit. +.TP +\f[B]-v\f[R], \f[B]--version\f[R] +Print the version number and exit. +.TP +\f[B]-e\f[R], \f[B]--list-errors\f[R] +Print a listing of all error codes and messages pyang might generate, +and then exit. +.TP +\f[B]--print-error-code\f[R] +On errors, print the symbolic error code instead of the error message. +.TP +\f[B]--print-error-basename\f[R] +On errors, print only the base file name independent of its module path +location. +.TP +\f[B]-Werror\f[R] +Treat warnings as errors. +.TP +\f[B]-Wnone\f[R] +Do not print any warnings. +.TP +\f[B]-W\f[R] \f[I]errorcode\f[R] +Treat \f[I]errorcode\f[R] as a warning, even if \f[B]-Werror\f[R] is +given. +\f[I]errorcode\f[R] must be a warning or a minor error. +.RS +.PP +Use \f[B]--list-errors\f[R] to get a listing of all errors and warnings. +.PP +The following example treats all warnings except the warning for unused +imports as errors: +.IP .nf -$ pyang \-\-Werror \-W UNUSED_IMPORT +\f[C] +$ pyang --Werror -W UNUSED_IMPORT +\f[R] .fi -.if n \{\ -.RE -.\} .RE +.TP +\f[B]-E\f[R] \f[I]errorcode\f[R] +Treat the warning \f[I]errorcode\f[R] as an error. +.RS +.PP +Use \f[B]--list-errors\f[R] to get a listing of all errors and warnings. .PP -\fB\-E\fR \fIerrorcode\fR -.RS 4 -Treat the warning -\fIerrorcode\fR -as an error\&. -.sp -Use -\fB\-\-list\-errors\fR -to get a listing of all errors and warnings\&. -.sp -The following example treats only the warning for unused import as an error: -.sp -.if n \{\ -.RS 4 -.\} +The following example treats only the warning for unused import as an +error: +.IP .nf -$ pyang \-\-Werror \-W UNUSED_IMPORT +\f[C] +$ pyang --Werror -W UNUSED_IMPORT +\f[R] .fi -.if n \{\ -.RE -.\} .RE +.TP +\f[B]--ignore-error\f[R] \f[I]errorcode\f[R] +Ignore error \f[I]errorcode\f[R]. +.RS +.PP +Use with care. +Plugins that dont expect to be invoked if there are errors present may +crash. +.PP +Use \f[B]--list-errors\f[R] to get a listing of all errors and warnings. .PP -\fB\-\-ignore\-error\fR \fIerrorcode\fR -.RS 4 -Ignore error -\fIerrorcode\fR\&. -.sp -Use with care\&. Plugins that don\*(Aqt expect to be invoked if there are errors present may crash\&. -.sp -Use -\fB\-\-list\-errors\fR -to get a listing of all errors and warnings\&. -.sp The following example ignores syntax errors in patterns: -.sp -.if n \{\ -.RS 4 -.\} +.IP .nf -$ pyang \-\-ignore\-error PATTERN_ERROR +\f[C] +$ pyang --ignore-error PATTERN_ERROR +\f[R] .fi -.if n \{\ -.RE -.\} .RE +.TP +\f[B]--msg-template\f[R] \f[I]msg-template\f[R] +Print out error message in defined \f[I]msg-template\f[R]. +.RS +.PP +Template used to display error messages. +This is a python new-style format string used to format the message +information with keys file, line, code, type, and msg. .PP -\fB\-\-msg\-template\fR \fImsg\-template\fR -.RS 4 -Print out error message in defined -\fImsg\-template\fR\&. -.sp -Template used to display error messages\&. This is a python new\-style format string used to format the message information with keys file, line, code, type, and msg\&. -.sp The following example create a msg template in defined pattern: -.sp -.if n \{\ -.RS 4 -.\} +.IP .nf -$ pyang \-\-msg\-template=\*(Aq{file} || {line} || {type} || {level} || {code} || {msg}\*(Aq +\f[C] +$ pyang --msg-template={file} || {line} || {type} || {level} + || {code} || {msg} +\f[R] .fi -.if n \{\ -.RE -.\} .RE +.TP +\f[B]--ignore-errors\f[R] +Ignore all errors. +Use with care. +Plugins that dont expect to be invoked if there are errors present may +crash. +.TP +\f[B]--keep-comments\f[R] +This parameter has effect only if a plugin can handle comments. +.TP +\f[B]--canonical\f[R] +Validate the module(s) according to the canonical YANG order. +.TP +\f[B]--verify-revision-history\f[R] +Ensure that the revision history in the given module(s) is correct, by +checking that it can find the old revisions of the module(s) in the YANG +module search path. +.TP +\f[B]--strict\f[R] +Force strict YANG compliance. +Currently this checks that the deref() function is not used in XPath +expressions and leafrefs. +.TP +\f[B]--lint\f[R] +Validate the module(s) according to the generic YANG guideline as +specified in \f[B]RFC 8407\f[R]. +In addition, it checks that the module is in canonical order. +.TP +\f[B]--ietf\f[R] +Validate the module(s) like \f[B]--lint\f[R], and in addition verifies +that the namespace and module name follow the IETF conventions, and that +the module has the correct license text and \f[B]RFC 2119\f[R] / +\f[B]RFC 8174\f[R] boilerplate text. +.TP +\f[B]--lax-quote-checks\f[R] +Lax checks of backslashes in double quoted strings in YANG version 1 +modules. +\f[B]RFC 6020\f[R] does not clearly define how to handle backslahes +within double quoted strings, when the character after the backslash is +not one of the characters listed in Section 6.1.3 in \f[B]RFC 6020\f[R]. +.RS +.PP +Earlier versions of pyang silently accepted such escape sequences, but +the current version treats this as an error, just like it is defined in +YANG 1.1 \f[B]RFC 7950\f[R]. +Passing this flag to pyang makes pyang silently accept such escape +sequences. +.RE +.TP +\f[B]--lax-xpath-checks\f[R] +Lax checks of XPath expressions. +Specifically, do not generate an error if an XPath expression uses a +variable or an unknown function. +.TP +\f[B]-L\f[R] \f[B]--hello\f[R] +Interpret the input file or standard input as a server message. +In this case, no more than one \f[I]file\f[R] parameter may be given. +.TP +\f[B]--implicit-hello-deviations\f[R] +Attempt to parse all deviations from a supplied message. +Not all implementations provide deviations explicitly as modules. +This flag enables more logic to attempt to derive all deviations from +the message. +.TP +\f[B]--trim-yin\f[R] +In YIN input modules, remove leading and trailing whitespace from every +line in the arguments of the following statements: contact, description, +error-message, organization and reference. +This way, the XML-indented argument texts look tidy after translating +the module to the compact YANG syntax. +.TP +\f[B]--max-line-length\f[R] \f[I]maxlen\f[R] +Give a warning if any line is longer than \f[I]maxlen\f[R]. +The value 0 means no check (default). +.TP +\f[B]--max-identifier-length\f[R] \f[I]maxlen\f[R] +Give a error if any identifier is longer than_maxlen_. +.TP +\f[B]-t\f[R] \f[B]--transform\f[R] \f[I]transform\f[R] +Transform the module(s) after parsing them but before outputting them. +Multiple transformations can be given, and will be performed in the +order that they were specified. +The supported transformations are listed in TRANSFORMATIONS below. +.TP +\f[B]-f\f[R] \f[B]--format\f[R] \f[I]format\f[R] +Convert the module(s) into \f[I]format\f[R]. +Some translators require a single module, and some can translate +multiple modules at one time. +If no \f[I]outfile\f[R] file is specified, the result is printed on +stdout. +The supported formats are listed in OUTPUT FORMATS below. +.TP +\f[B]-o\f[R] \f[B]--output\f[R] \f[I]outfile\f[R] +Write the output to the file \f[I]outfile\f[R] instead of stdout. +.TP +\f[B]-F\f[R] \f[B]--features\f[R] \f[I]features\f[R] +\f[I]features\f[R] is a string of the form +\f[I]modulename\f[R]:[\f[I]feature\f[R](,\f[I]feature\f[R])*] +.RS +.PP +This option is used to prune the data model by removing all nodes that +are defined with a \[dq]if-feature\[dq] that is not listed as +\f[I]feature\f[R]. +This option affects all output formats. .PP -\fB\-\-ignore\-errors\fR -.RS 4 -Ignore all errors\&. Use with care\&. Plugins that don\*(Aqt expect to be invoked if there are errors present may crash\&. -.RE -.PP -\fB\-\-keep\-comments\fR -.RS 4 -This parameter has effect only if a plugin can handle comments\&. -.RE -.PP -\fB\-\-canonical\fR -.RS 4 -Validate the module(s) according to the canonical YANG order\&. -.RE -.PP -\fB\-\-verify\-revision\-history\fR -.RS 4 -Ensure that the revision history in the given module(s) is correct, by checking that it can find the old revisions of the module(s) in the YANG module search path\&. -.RE -.PP -\fB\-\-strict\fR -.RS 4 -Force strict YANG compliance\&. Currently this checks that the deref() function is not used in XPath expressions and leafrefs\&. -.RE -.PP -\fB\-\-lint\fR -.RS 4 -Validate the module(s) according to the generic YANG guideline as specified in -\m[blue]\fBRFC 8407\fR\m[]\&\s-2\u[5]\d\s+2\&. In addition, it checks that the module is in canonical order\&. -.RE -.PP -\fB\-\-ietf\fR -.RS 4 -Validate the module(s) like -\fB\-\-lint\fR, and in addition verifies that the namespace and module name follow the IETF conventions, and that the module has the correct license text and -\m[blue]\fBRFC 2119\fR\m[]\&\s-2\u[6]\d\s+2 -/ -\m[blue]\fBRFC 8174\fR\m[]\&\s-2\u[7]\d\s+2 -boilerplate text\&. -.RE -.PP -\fB\-\-lax\-quote\-checks\fR -.RS 4 -Lax checks of backslashes in double quoted strings in YANG version 1 modules\&. -\m[blue]\fBRFC 6020\fR\m[]\&\s-2\u[2]\d\s+2 -does not clearly define how to handle backslahes within double quoted strings, when the character after the backslash is not one of the characters listed in Section 6\&.1\&.3 in -\m[blue]\fBRFC 6020\fR\m[]\&\s-2\u[2]\d\s+2\&. -.sp -Earlier versions of pyang silently accepted such escape sequences, but the current version treats this as an error, just like it is defined in YANG 1\&.1 (\m[blue]\fBRFC 7950\fR\m[]\&\s-2\u[3]\d\s+2)\&. Passing this flag to pyang makes pyang silently accept such escape sequences\&. -.RE -.PP -\fB\-\-lax\-xpath\-checks\fR -.RS 4 -Lax checks of XPath expressions\&. Specifically, do not generate an error if an XPath expression uses a variable or an unknown function\&. -.RE -.PP -\fB\-L\fR \fB\-\-hello\fR -.RS 4 -Interpret the input file or standard input as a server message\&. In this case, no more than one -\fIfile\fR -parameter may be given\&. -.RE -.PP -\fB\-\-implicit\-hello\-deviations\fR -.RS 4 -Attempt to parse all deviations from a supplied message\&. Not all implementations provide deviations explicitly as modules\&. This flag enables more logic to attempt to derive all deviations from the message\&. -.RE +This option can be given multiple times, and may also be combined with +\f[B]--hello\f[R]. +The \f[B]--features\f[R] option overrides any supported features for a +module that are taken from the hello file. .PP -\fB\-\-trim\-yin\fR -.RS 4 -In YIN input modules, remove leading and trailing whitespace from every line in the arguments of the following statements: \*(Aqcontact\*(Aq, \*(Aqdescription\*(Aq, \*(Aqerror\-message\*(Aq, \*(Aqorganization\*(Aq and \*(Aqreference\*(Aq\&. This way, the XML\-indented argument texts look tidy after translating the module to the compact YANG syntax\&. -.RE +If this option is not given, nothing is pruned, i.e., it works as if all +features were explicitly listed. .PP -\fB\-\-max\-line\-length\fR \fImaxlen\fR -.RS 4 -Give a warning if any line is longer than -\fImaxlen\fR\&. The value 0 means no check (default)\&. -.RE +The \f[B]--exclude-features\f[R] option can be used for excluding a list +of named features. +\f[B]--features\f[R] and \f[B]--exclude-features\f[R] cant both be +specified for a given module. .PP -\fB\-\-max\-identifier\-length\fR \fImaxlen\fR -.RS 4 -Give a error if any identifier is longer than -\fImaxlen\fR\&. +For example, to view the tree output for a module with all if-featured +nodes removed, do: +.IP +.nf +\f[C] +$ pyang -f tree --features mymod: mymod.yang +\f[R] +.fi .RE +.TP +\f[B]-X\f[R] \f[B]--exclude-features\f[R] \f[I]features\f[R] +\f[I]features\f[R] is a string of the form +\f[I]modulename\f[R]:[\f[I]feature\f[R](,\f[I]feature\f[R])*] +.RS .PP -\fB\-t\fR \fB\-\-transform\fR \fItransform\fR -.RS 4 -Transform the module(s) after parsing them but before outputting them\&. Multiple transformations can be given, and will be performed in the order that they were specified\&. The supported transformations are listed in -TRANSFORMATIONS -below\&. -.RE +This option is used to prune the data model by removing all nodes that +are defined with a \[dq]if-feature\[dq] that is listed as +\f[I]feature\f[R]. +This option affects all output formats. .PP -\fB\-f\fR \fB\-\-format\fR \fIformat\fR -.RS 4 -Convert the module(s) into -\fIformat\fR\&. Some translators require a single module, and some can translate multiple modules at one time\&. If no -\fIoutfile\fR -file is specified, the result is printed on stdout\&. The supported formats are listed in -OUTPUT FORMATS -below\&. -.RE +This option can be given multiple times. +It cant be combined with \f[B]--hello\f[R]. .PP -\fB\-o\fR \fB\-\-output\fR \fIoutfile\fR -.RS 4 -Write the output to the file -\fIoutfile\fR -instead of stdout\&. -.RE +The \f[B]--features\f[R] option can be used for including all features +or a list of named features. +\f[B]--features\f[R] and \f[B]--exclude-features\f[R] cant both be +specified for a given module. .PP -\fB\-F\fR \fB\-\-features\fR \fIfeatures\fR -.RS 4 -\fIfeatures\fR -is a string of the form -\fImodulename\fR:[\fIfeature\fR(,\fIfeature\fR)*] -.sp -This option is used to prune the data model by removing all nodes that are defined with a "if\-feature" that is not listed as -\fIfeature\fR\&. This option affects all output formats\&. -.sp -This option can be given multiple times, and may also be combined with -\fB\-\-hello\fR\&. The -\fB\-\-features\fR -option overrides any supported features for a module that are taken from the hello file\&. -.sp -If this option is not given, nothing is pruned, i\&.e\&., it works as if all features were explicitly listed\&. -.sp -The -\fB\-\-exclude\-features\fR -option can be used for excluding a list of named features\&. -\fB\-\-features\fR -and -\fB\-\-exclude\-features\fR -can\*(Aqt both be specified for a given module\&. -.sp -For example, to view the tree output for a module with all if\-feature\*(Aqd nodes removed, do: -.sp -.if n \{\ -.RS 4 -.\} +For example, to view the tree output for a module with if-featured nodes +for the specified feature removed, do: +.IP .nf -$ pyang \-f tree \-\-features mymod: mymod\&.yang +\f[C] +$ pyang -f tree --exclude-features mymod:myfeat mymod.yang +\f[R] .fi -.if n \{\ -.RE -.\} .RE +.TP +\f[B]--max-status\f[R] \f[I]maxstatus\f[R] +\f[I]maxstatus\f[R] is one of:\f[I]current\f[R],\f[I]deprecated\f[R], or +\f[I]obsolete\f[R]. +.RS .PP -\fB\-X\fR \fB\-\-exclude\-features\fR \fIfeatures\fR -.RS 4 -\fIfeatures\fR -is a string of the form -\fImodulename\fR:[\fIfeature\fR(,\fIfeature\fR)*] -.sp -This option is used to prune the data model by removing all nodes that are defined with a "if\-feature" that is listed as -\fIfeature\fR\&. This option affects all output formats\&. -.sp -This option can be given multiple times\&. It can\*(Aqt be combined with -\fB\-\-hello\fR\&. -.sp -The -\fB\-\-features\fR -option can be used for including all features or a list of named features\&. -\fB\-\-features\fR -and -\fB\-\-exclude\-features\fR -can\*(Aqt both be specified for a given module\&. -.sp -For example, to view the tree output for a module with if\-feature\*(Aqd nodes for the specified feature removed, do: -.sp -.if n \{\ -.RS 4 -.\} -.nf -$ pyang \-f tree \-\-exclude\-features mymod:myfeat mymod\&.yang -.fi -.if n \{\ -.RE -.\} +This option is used to prune the data model by removing all nodes that +are defined with a \[dq]status\[dq] that is less than the given +\f[I]maxstatus\f[R]. +This option affects all output formats. .RE +.TP +\f[B]--deviation-module\f[R] \f[I]file\f[R] +This option is used to apply the deviations defined in \f[I]file\f[R]. +This option affects all output formats. +.RS .PP -\fB\-\-max\-status\fR \fImaxstatus\fR -.RS 4 -\fImaxstatus\fR -is one of: -\fIcurrent\fR, -\fIdeprecated\fR, or -\fIobsolete\fR\&. -.sp -This option is used to prune the data model by removing all nodes that are defined with a "status" that is less than the given -\fImaxstatus\fR\&. This option affects all output formats\&. -.RE +This option can be given multiple times. .PP -\fB\-\-deviation\-module\fR \fIfile\fR -.RS 4 -This option is used to apply the deviations defined in -\fIfile\fR\&. This option affects all output formats\&. -.sp -This option can be given multiple times\&. -.sp -For example, to view the tree output for a module with some deviations applied, do: -.sp -.if n \{\ -.RS 4 -.\} +For example, to view the tree output for a module with some deviations +applied, do: +.IP .nf -$ pyang \-f tree \-\-deviation\-module mymod\-devs\&.yang mymod\&.yang +\f[C] +$ pyang -f tree --deviation-module mymod-devs.yang mymod.yang +\f[R] .fi -.if n \{\ -.RE -.\} .RE +.TP +\f[B]-p\f[R] \f[B]--path\f[R] \f[I]path\f[R] +\f[I]path\f[R] is a colon (:) separated list of directories to search +for imported modules. +This option may be given multiple times. +.RS +.PP +By default, all directories (except \[dq].\[dq]) found in the path are +recursively scanned for modules. +This behavior can be disabled by giving the option +\f[B]--no-path-recurse\f[R]. .PP -\fB\-p\fR \fB\-\-path\fR \fIpath\fR -.RS 4 -\fIpath\fR -is a colon (:) separated list of directories to search for imported modules\&. This option may be given multiple times\&. -.sp -By default, all directories (except "\&.") found in the path are recursively scanned for modules\&. This behavior can be disabled by giving the option -\fB\-\-no\-path\-recurse\fR\&. -.sp The following directories are always added to the search path: -.sp -.RS 4 -.ie n \{\ -\h'-04' 1.\h'+01'\c -.\} -.el \{\ -.sp -1 -.IP " 1." 4.2 -.\} +.IP "1." 3 current directory +.IP "2." 3 +\f[B]$YANG_MODPATH\f[R] +.IP "3." 3 +\f[B]$HOME\f[R]/yang/modules +.IP "4." 3 +\f[B]\f[BI]Y\f[B]\f[BI]A\f[B]\f[BI]N\f[B]\f[BI]G\f[B]_\f[BI]I\f[B]\f[BI]N\f[B]\f[BI]S\f[B]\f[BI]T\f[B]\f[BI]A\f[B]\f[BI]L\f[B]\f[BI]L\f[B]\[u2005]*\[u2005]\[u2005]*\[u2005]/\f[BI]y\f[B]\f[BI]a\f[B]\f[BI]n\f[B]\f[BI]g\f[B]/\f[BI]m\f[B]\f[BI]o\f[B]\f[BI]d\f[B]\f[BI]u\f[B]\f[BI]l\f[B]\f[BI]e\f[B]\f[BI]s\f[B]\f[BI]O\f[B]\f[BI]R\f[B]\f[BI]i\f[B]\f[BI]f\f[B]\[u2005]*\[u2005]*YANG_INSTALL\f[R] +is unset /yang/modules (on Unix +systems: /usr/share/yang/modules) +.RE +.TP +\f[B]--no-path-recurse\f[R] +If this parameter is given, directories in the search path are not +recursively scanned for modules. +.TP +\f[B]--plugindir\f[R] \f[I]plugindir\f[R] +Load all YANG plugins found in the directory \f[I]plugindir\f[R]. +This option may be given multiple times. +.RS +.PP +List of directories to search for pyang plugins. +The following directories are always added to the search path: +.IP "1." 3 +pyang/plugins from where pyang is installed +.IP "2." 3 +\f[B]$PYANG_PLUGINPATH\f[R] .RE -.sp -.RS 4 -.ie n \{\ -\h'-04' 2.\h'+01'\c -.\} -.el \{\ -.sp -1 -.IP " 2." 4.2 -.\} -\fB$YANG_MODPATH\fR -.RE -.sp -.RS 4 -.ie n \{\ -\h'-04' 3.\h'+01'\c -.\} -.el \{\ -.sp -1 -.IP " 3." 4.2 -.\} -\fB$HOME\fR/yang/modules -.RE -.sp -.RS 4 -.ie n \{\ -\h'-04' 4.\h'+01'\c -.\} -.el \{\ -.sp -1 -.IP " 4." 4.2 -.\} -\fB$YANG_INSTALL\fR/yang/modules -OR if -\fB$YANG_INSTALL\fR -is unset -/yang/modules -(on Unix systems: -/usr/share/yang/modules) -.RE -.RE -.PP -\fB\-\-no\-path\-recurse\fR -.RS 4 -If this parameter is given, directories in the search path are not recursively scanned for modules\&. -.RE -.PP -\fB\-\-plugindir\fR \fIplugindir\fR -.RS 4 -Load all YANG plugins found in the directory -\fIplugindir\fR\&. This option may be given multiple times\&. -.sp -list of directories to search for pyang plugins\&. The following directories are always added to the search path: -.sp -.RS 4 -.ie n \{\ -\h'-04' 1.\h'+01'\c -.\} -.el \{\ -.sp -1 -.IP " 1." 4.2 -.\} -pyang/plugins -from where pyang is installed -.RE -.sp -.RS 4 -.ie n \{\ -\h'-04' 2.\h'+01'\c -.\} -.el \{\ -.sp -1 -.IP " 2." 4.2 -.\} -\fB$PYANG_PLUGINPATH\fR -.RE -.RE -.PP -\fB\-\-check\-update\-from\fR \fIoldfile\fR -.RS 4 +.TP +\f[B]--check-update-from\f[R] \f[I]oldfile\f[R] Checks that a new revision of a module follows the update rules given in -\m[blue]\fBRFC 6020\fR\m[]\&\s-2\u[2]\d\s+2 -and -\m[blue]\fBRFC 7950\fR\m[]\&\s-2\u[3]\d\s+2\&. -\fIoldfile\fR -is the old module and -\fIfile\fR -is the new version of the module\&. -.sp -If the old module imports or includes any modules or submodules, it is important that the the old versions of these modules and submodules are found\&. By default, the directory where -\fIoldfile\fR -is found is used as the only directory in the search path for old modules\&. Use the option -\fB\-\-check\-update\-from\-path\fR -to control this path\&. -.RE -.PP -\fB\-P\fR \fB\-\-check\-update\-from\-path\fR \fIoldpath\fR -.RS 4 -\fIoldpath\fR -is a colon (:) separated list of directories to search for imported modules\&. This option may be given multiple times\&. -.RE -.PP -\fB\-D\fR \fB\-\-check\-update\-from\-deviation\-module\fR \fIolddeviation\fR -.RS 4 -\fIolddeviation\fR -is an old deviation module of the old module -\fIoldfile\fR\&. This option may be given multiple times\&. For example, to check updates of a module with some deviations applied, do: -.sp -.if n \{\ -.RS 4 -.\} +\f[B]RFC 6020\f[R] and \f[B]RFC 7950\f[R]. +\f[I]oldfile\f[R] is the old module and \f[I]file\f[R] is the new +version of the module. +.RS +.PP +If the old module imports or includes any modules or submodules, it is +important that the the old versions of these modules and submodules are +found. +By default, the directory where \f[I]oldfile\f[R] is found is used as +the only directory in the search path for old modules. +Use the option +.RE +.TP +\f[B]--check-update-from-path\f[R] +to control this path. +.TP +\f[B]-P\f[R] \f[B]--check-update-from-path\f[R] \f[I]oldpath\f[R] +\f[I]oldpath\f[R] is a colon (:) separated list of directories to search +for imported modules. +This option may be given multiple times. +.TP +\f[B]-D\f[R] \f[B]--check-update-from-deviation-module\f[R] \f[I]olddeviation\f[R] +\f[I]olddeviation\f[R] is an old deviation module of the old module +\f[I]oldfile\f[R]. +This option may be given multiple times. +For example, to check updates of a module with some deviations applied, +do: +.RS +.IP .nf -$ pyang \-\-check\-update\-from\-deviation\-module oldmod\-devs\&.yang \-\-check\-update\-from oldmod\&.yang \e - \-\-deviation\-module newmod\-devs\&.yang newmod\&.yang +\f[C] +$ pyang --check-update-from-deviation-module oldmod-devs.yang \[rs] + --check-update-from oldmod.yang \[rs] + --deviation-module newmod-devs.yang newmod.yang +\f[R] .fi -.if n \{\ .RE -.\} -.RE -.PP -\fIfile\&.\&.\&.\fR -.RS 4 -These are the names of the files containing the modules to be validated, or the module to be converted\&. -.RE -.SH "TRANSFORMATIONS" -.PP -Installed -\fBpyang\fR -transformations are (like output formats) plugins and therefore may define their own options, or add new transformations to the -\fB\-t\fR -option\&. These options and transformations are listed in -\fBpyang \-h\fR\&. -.PP -\fIedit\fR -.RS 4 -Modify the supplied module(s) in various ways\&. This transform will usually be used with the -\fIyang\fR -output format\&. -.RE -.SH "EDIT TRANSFORM" -.PP -The -\fIedit\fR -transform modifies the supplied module(s) in various ways\&. It can, for example, replace top\-level -\fIdescription\fR -statements, update -\fIinclude\fR -statements and manage -\fIrevision\fR -statements\&. Unless otherwise noted below, it only modifies -\fIexisting\fR -statements\&. -.PP -Each -\fIedit\fR -transform string (non\-date) option value is either a plain string (which is taken literally) or a -\fI+\fR\-separated list of directives (whose expansions are concatenated with double\-linebreak separators, i\&.e\&. each directive results in one or more paragraphs)\&. -.PP -Each directive is either of the form -\fI@filename\fR -(which is replaced with the contents of the file; there is no search path; trailing whitespace is discarded) or of the form -\fI%keyword\fR\&. Any unrecognized directives are treated as plain strings\&. The following -\fI%\fR\-directives are currently supported: -.sp -.RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -.sp -1 -.IP \(bu 2.3 -.\} -\fI%SUMMARY\fR -: This expands to a "summary" of the original argument value\&. It\*(Aqs intended for use with top\-level -\fIdescription\fR -statements that typically consist of a hand\-crafted summary followed by copyrights, license and other boiler\-plate text\&. The summary is the text up to but not including the first line that (ignoring leading and trailing whitespace) starts with the word -\fICopyright\fR -followed by a space\&. -.RE -.sp -.RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -.sp -1 -.IP \(bu 2.3 -.\} -\fI%SUBST/old/new\fR -: This expands to the original argument value with all instances of -\fIold\fR -replaced with -\fInew\fR\&. There is no provision for replacing characters that contain forward slashes, and there is no terminating slash\&. -.RE -.sp -.RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -.sp -1 -.IP \(bu 2.3 -.\} -\fI%DELETE\fR -: This clears the output buffer and suppresses a check that would normally prevent overwriting an existing value (unless that value is the literal string -\fBTBD\fR)\&. -.RE -.PP -In the examples given below, it\*(Aqs assumed that there are -\fICONTACT\fR, -\fICONTEXT\fR, -\fILICENSE\fR, -\fIORGANIZATION\fR, -\fIREFERENCE\fR -and -\fIREVISION\fR -files in a top\-level project directory (which in this case is the parent of the directory in which -\fBpyang\fR -is being run)\&. These examples illustrate how the -\fIedit\fR -transform might be used with the -\fIyang\fR -output format to prepare YANG files for publication\&. +.TP +\f[I]file\&...\f[R] +These are the names of the files containing the modules to be validated, +or the module to be converted. +.SH TRANSFORMATIONS +.PP +Installed \f[B]pyang\f[R] transformations are (like output formats) +plugins and therefore may define their own options, or add new +transformations to the \f[B]-t\f[R] option. +These options and transformations are listed in \f[B]pyang -h\f[R]. +.TP +\f[I]edit\f[R] +Modify the supplied module(s) in various ways. +This transform will usually be used with the \f[I]yang\f[R] output +format. +.SH EDIT TRANSFORM +.PP +The \f[I]edit\f[R] transform modifies the supplied module(s) in various +ways. +It can, for example, replace top-level \f[I]description\f[R] statements, +update \f[I]include\f[R] statements and manage \f[I]revision\f[R] +statements. +Unless otherwise noted below, it only modifies \f[I]existing\f[R] +statements. +.PP +Each \f[I]edit\f[R] transform string (non-date) option value is either a +plain string (which is taken literally) or a \f[I]+\f[R]-separated list +of directives (whose expansions are concatenated with double-linebreak +separators, i.e., each directive results in one or more paragraphs). +.PP +Each directive is either of the form \f[I]\[at]filename\f[R] (which is +replaced with the contents of the file; there is no search path; +trailing whitespace is discarded) or of the form \f[I]%keyword\f[R]. +Any unrecognized directives are treated as plain strings. +The following \f[I]%\f[R]-directives are currently supported: +.IP \[bu] 2 +\f[I]%SUMMARY\f[R] : This expands to a \[dq]summary\[dq] of the original +argument value. +It\[cq]s intended for use with top-level \f[I]description\f[R] +statements that typically consist of a hand-crafted summary followed by +copyrights, license and other boiler-plate text. +The summary is the text up to but not including the first line that +(ignoring leading and trailing whitespace) starts with the word +\f[I]Copyright\f[R] followed by a space. +.IP \[bu] 2 +\f[I]%SUBST/old/new\f[R] : This expands to the original argument value +with all instances of \f[I]old\f[R] replaced with \f[I]new\f[R]. +There is no provision for replacing characters that contain forward +slashes, and there is no terminating slash. +.IP \[bu] 2 +\f[I]%DELETE\f[R] : This clears the output buffer and suppresses a check +that would normally prevent overwriting an existing value (unless that +value is the literal string \f[B]TBD\f[R]). +.PP +In the examples given below, it\[cq]s assumed that there are +\f[I]CONTACT\f[R], \f[I]CONTEXT\f[R], \f[I]LICENSE\f[R], +\f[I]ORGANIZATION\f[R], \f[I]REFERENCE\f[R] and \f[I]REVISION\f[R] files +in a top-level project directory (which in this case is the parent of +the directory in which \f[B]pyang\f[R] is being run). +These examples illustrate how the \f[I]edit\f[R] transform might be used +with the \f[I]yang\f[R] output format to prepare YANG files for +publication. .PP Edit transform specific options: +.TP +\f[B]--edit-yang-version\f[R] \f[I]version\f[R] +Set the YANG version (i.e., the \f[I]yang-version\f[R] statement\[cq]s +argument) to \f[I]version\f[R]. +This does nothing if the YANG module doesn\[cq]t already have a +\f[I]yang-version\f[R] statement. +.RS +.PP +Example: \f[B]--edit-yang-version 1.1\f[R]. +.RE +.TP +\f[B]--edit-namespace\f[R] \f[I]namespace\f[R] +Set the YANG namespace (i.e., the \f[I]namespace\f[R] statement\[cq]s +argument) to \f[I]namespace\f[R]. +This does nothing if the YANG module doesn\[cq]t already have a +\f[I]namespace\f[R] statement. +.RS +.PP +Example: \f[B]--edit-namespace %SUBST/acme-pacific-org/apo\f[R] +.RE +.TP +\f[B]--edit-update-import-dates\f[R] +Update any \f[I]import\f[R] (or \f[I]include\f[R]) +\f[I]revision-date\f[R] statements to match imported (or included) +modules and submodules. +If there isn\[cq]t already a \f[I]revision-date\f[R] statement, it will +be added. +.TP +\f[B]--edit-delete-import-dates\f[R] +Delete any \f[I]import\f[R] (or \f[I]include\f[R]) +\f[I]revision-date\f[R] statements. +.TP +\f[B]--edit-organization\f[R] \f[I]organization\f[R] +Set the organization (i.e., the \f[I]organization\f[R] statement\[cq]s +argument) to \f[I]organization\f[R]. +This does nothing if the YANG module doesn\[cq]t already have an +\f[I]organization\f[R] statement. +.RS +.PP +Example: \f[B]--edit-organization \[at]../ORGANIZATION\f[R] +.RE +.TP +\f[B]--edit-contact\f[R] \f[I]contact\f[R] +Set the contact info (i.e., the \f[I]contact\f[R] statement\[cq]s +argument) to \f[I]contact\f[R]. +This does nothing if the YANG module doesn\[cq]t already have a +\f[I]contact\f[R] statement. +.RS +.PP +Example: \f[B]--edit-contact \[at]../CONTACT\f[R] +.RE +.TP +\f[B]--edit-description\f[R] \f[I]description\f[R] +Set the top-level description (i.e., the top-level \f[I]description\f[R] +statement\[cq]s argument) to \f[I]description\f[R]. +This does nothing if the YANG module doesn\[cq]t already have a +\f[I]description\f[R] statement. +.RS +.PP +Example: \f[B]--edit-description +%SUMMARY+\[at]../LICENSE+\[at]../CONTEXT\f[R] +.RE +.TP +\f[B]--edit-delete-revisions-after\f[R] \f[I]prevdate\f[R] +Delete any \f[I]revision\f[R] statements after (i.e., that are more +recent than) the supplied \f[I]yyyy-mm-dd\f[R] revision date. +A typical use case is to supply the date of the previous release: any +revisions since then will be internal (e.g., developers often feel that +they should add revision statements for git commits) and are not wanted +in the next released version. +.RS +.PP +Example: \f[B]--edit-delete-revisions-after 2019-03-15\f[R] +.RE +.TP +\f[B]--edit-revision-date\f[R] \f[I]date\f[R] +Set the most recent revision date to the supplied \f[I]yyyy-mm-dd\f[R] +revision date. +This does nothing if the YANG module doesn\[cq]t already have at least +one \f[I]revision\f[R] statement. +If necessary, a new \f[I]revision\f[R] statement will be inserted before +any (remaining) existing revisions. +.RS +.PP +Example: \f[B]--edit-revision-date 2020-03-15\f[R] +.RE +.TP +\f[B]--edit-revision-description\f[R] \f[I]description\f[R] +Set the most recent revision description to \f[I]description\f[R]. +.RS +.PP +Example: \f[B]--edit-revision-description=%DELETE+\[at]../REVISION\f[R] +.RE +.TP +\f[B]--edit-revision-reference\f[R] \f[I]reference\f[R] +Set the most recent revision reference to \f[I]reference\f[R]. +.RS +.PP +Example: \f[B]--edit-revision-reference=%DELETE+\[at]../REFERENCE\f[R] +.RE +.SH OUTPUT FORMATS +.PP +Installed \f[B]pyang\f[R] plugins may define their own options, or add +new formats to the \f[B]-f\f[R] option. +These options and formats are listed in \f[B]pyang -h\f[R]. +.TP +\f[I]capability\f[R] +Capability URIs for each module of the data model. +.TP +\f[I]depend\f[R] +Makefile dependency rule for the module. +.TP +\f[I]dsdl\f[R] +Hybrid DSDL schema, see \f[B]RFC 6110\f[R]. +.TP +\f[I]identifiers\f[R] +All identifiers in the module. +.TP +\f[I]jsonxsl\f[R] +XSLT stylesheet for transforming XML instance documents to JSON. +.TP +\f[I]jstree\f[R] +HTML/JavaScript tree navigator. +.TP +\f[I]jtox\f[R] +Driver file for transforming JSON instance documents to XML. +.TP +\f[I]name\f[R] +Module name, and the name of the main module for a submodule. +.TP +\f[I]omni\f[R] +An applescript file that draws a diagram in \f[B]OmniGraffle\f[R]. +.TP +\f[I]sample-xml-skeleton\f[R] +Skeleton of a sample XML instance document. +.TP +\f[I]tree\f[R] +Tree structure of the module. +.TP +\f[I]flatten\f[R] +Print the schema nodes in CSV form. +.TP +\f[I]uml\f[R] +UML file that can be read by \f[B]plantuml\f[R] to generate UML +diagrams. +.TP +\f[I]yang\f[R] +Normal YANG syntax. +.TP +\f[I]yin\f[R] +The XML syntax of YANG. +.SH LINT CHECKER +.PP +The \f[I]lint\f[R] option validates that the module follows the generic +conventions and rules given in \f[B]RFC 8407\f[R]. +In addition, it checks that the module is in canonical order. +.PP +Options for the \f[I]lint\f[R] checker: +.TP +\f[B]--lint-namespace-prefix\f[R] \f[I]prefix\f[R] +Validate that the module\[cq]s namespace is of the form: +\[dq]\[dq]. +.TP +\f[B]--lint-modulename-prefix\f[R] \f[I]prefix\f[R] +Validate that the module\[cq]s name starts with \f[I]prefix\f[R]. +.TP +\f[B]--lint-ensure-hyphenated-names\f[R] +Validate that all identifiers use hyphenated style, i.e., no uppercase +letters or underscores. +.SH YANG SCHEMA ITEM IDENTIFIERS (SID) +.PP +YANG Schema Item iDentifiers (SID) are globally unique unsigned integers +used to identify YANG items. +SIDs are used instead of names to save space in constrained applications +such as COREconf. +This plugin is used to automatically generate and updated .sid files +used to persist and distribute SID assignments. +.PP +Options for generating, updating and checking .sid files: +.TP +\f[B]--sid-generate-file\f[R] +This option is used to generate a new .sid file from a YANG module. +.RS +.PP +Two arguments are required to generate a .sid file; the SID range +assigned to the YANG module and its definition file. +The SID range specified is a sub-range within a range obtained from a +registrar or a sub-range within the experimental range (i.e., 60000 to +99999). +The SID range consists of the first SID of the range, followed by a +colon, followed by the number of SID allocated to the YANG module. +The filename consists of the module name, followed by an \[at] symbol, +followed by the module revision, followed by the \[dq].yang\[dq] +extension. .PP -\fB\-\-edit\-yang\-version\fR \fIversion\fR -.RS 4 -Set the YANG version (i\&.e\&., the -\fIyang\-version\fR -statement\*(Aqs argument) to -\fIversion\fR\&. This does nothing if the YANG module doesn\*(Aqt already have a -\fIyang\-version\fR -statement\&. -.sp -Example: -\fB\-\-edit\-yang\-version 1\&.1\fR\&. -.RE -.PP -\fB\-\-edit\-namespace\fR \fInamespace\fR -.RS 4 -Set the YANG namespace (i\&.e\&., the -\fInamespace\fR -statement\*(Aqs argument) to -\fInamespace\fR\&. This does nothing if the YANG module doesn\*(Aqt already have a -\fInamespace\fR -statement\&. -.sp -Example: -\fB\-\-edit\-namespace %SUBST/acme\-pacific\-org/apo\fR -.RE -.PP -\fB\-\-edit\-update\-import\-dates\fR -.RS 4 -Update any -\fIimport\fR -(or -\fIinclude\fR) -\fIrevision\-date\fR -statements to match imported (or included) modules and submodules\&. If there isn\*(Aqt already a -\fIrevision\-date\fR -statement, it will be added\&. -.RE -.PP -\fB\-\-edit\-delete\-import\-dates\fR -.RS 4 -Delete any -\fIimport\fR -(or -\fIinclude\fR) -\fIrevision\-date\fR -statements\&. -.RE -.PP -\fB\-\-edit\-organization\fR \fIorganization\fR -.RS 4 -Set the organization (i\&.e\&. the -\fIorganization\fR -statement\*(Aqs argument) to -\fIorganization\fR\&. This does nothing if the YANG module doesn\*(Aqt already have an -\fIorganization\fR -statement\&. -.sp -Example: -\fB\-\-edit\-organization @\&.\&./ORGANIZATION\fR -.RE -.PP -\fB\-\-edit\-contact\fR \fIcontact\fR -.RS 4 -Set the contact info (i\&.e\&. the -\fIcontact\fR -statement\*(Aqs argument) to -\fIcontact\fR\&. This does nothing if the YANG module doesn\*(Aqt already have a -\fIcontact\fR -statement\&. -.sp -Example: -\fB\-\-edit\-contact @\&.\&./CONTACT\fR -.RE -.PP -\fB\-\-edit\-description\fR \fIdescription\fR -.RS 4 -Set the top\-level description (i\&.e\&. the top\-level -\fIdescription\fR -statement\*(Aqs argument) to -\fIdescription\fR\&. This does nothing if the YANG module doesn\*(Aqt already have a -\fIdescription\fR -statement\&. -.sp -Example: -\fB\-\-edit\-description %SUMMARY+@\&.\&./LICENSE+@\&.\&./CONTEXT\fR -.RE -.PP -\fB\-\-edit\-delete\-revisions\-after\fR \fIprevdate\fR -.RS 4 -Delete any -\fIrevision\fR -statements after (i\&.e\&. that are more recent than) the supplied -\fIyyyy\-mm\-dd\fR -revision date\&. A typical use case is to supply the date of the previous release: any revisions since then will be internal (e\&.g\&. developers often feel that they should add revision statements for git commits) and are not wanted in the next released version\&. -.sp -Example: -\fB\-\-edit\-delete\-revisions\-after 2019\-03\-15\fR -.RE -.PP -\fB\-\-edit\-revision\-date\fR \fIdate\fR -.RS 4 -Set the most recent revision date to the supplied -\fIyyyy\-mm\-dd\fR -revision date\&. This does nothing if the YANG module doesn\*(Aqt already have at least one -\fIrevision\fR -statement\&. If necessary, a new -\fIrevision\fR -statement will be inserted before any (remaining) existing revisions\&. -.sp -Example: -\fB\-\-edit\-revision\-date 2020\-03\-15\fR -.RE -.PP -\fB\-\-edit\-revision\-description\fR \fIdescription\fR -.RS 4 -Set the most recent revision description to -\fIdescription\fR\&. -.sp -Example: -\fB\-\-edit\-revision\-description=%DELETE+@\&.\&./REVISION\fR -.RE -.PP -\fB\-\-edit\-revision\-reference\fR \fIreference\fR -.RS 4 -Set the most recent revision reference to -\fIreference\fR\&. -.sp -Example: -\fB\-\-edit\-revision\-reference=%DELETE+@\&.\&./REFERENCE\fR -.RE -.SH "OUTPUT FORMATS" -.PP -Installed -\fBpyang\fR -plugins may define their own options, or add new formats to the -\fB\-f\fR -option\&. These options and formats are listed in -\fBpyang \-h\fR\&. -.PP -\fIcapability\fR -.RS 4 -Capability URIs for each module of the data model\&. -.RE -.PP -\fIdepend\fR -.RS 4 -Makefile dependency rule for the module\&. -.RE -.PP -\fIdsdl\fR -.RS 4 -Hybrid DSDL schema, see -\m[blue]\fBRFC 6110\fR\m[]\&\s-2\u[4]\d\s+2\&. -.RE -.PP -\fIidentifiers\fR -.RS 4 -All identifiers in the module\&. -.RE -.PP -\fIjsonxsl\fR -.RS 4 -XSLT stylesheet for transforming XML instance documents to JSON\&. -.RE -.PP -\fIjstree\fR -.RS 4 -HTML/JavaScript tree navigator\&. -.RE -.PP -\fIjtox\fR -.RS 4 -Driver file for transforming JSON instance documents to XML\&. -.RE -.PP -\fIname\fR -.RS 4 -Module name, and the name of the main module for a submodule\&. -.RE -.PP -\fIomni\fR -.RS 4 -An applescript file that draws a diagram in -\fBOmniGraffle\fR\&. -.RE -.PP -\fIsample\-xml\-skeleton\fR -.RS 4 -Skeleton of a sample XML instance document\&. -.RE -.PP -\fItree\fR -.RS 4 -Tree structure of the module\&. -.RE -.PP -\fIflatten\fR -.RS 4 -Print the schema nodes in CSV form\&. -.RE -.PP -\fIuml\fR -.RS 4 -UML file that can be read by -\fBplantuml\fR -to generate UML diagrams\&. -.RE -.PP -\fIyang\fR -.RS 4 -Normal YANG syntax\&. -.RE -.PP -\fIyin\fR -.RS 4 -The XML syntax of YANG\&. -.RE -.SH "LINT CHECKER" -.PP -The -\fIlint\fR -option validates that the module follows the generic conventions and rules given in -\m[blue]\fBRFC 8407\fR\m[]\&\s-2\u[5]\d\s+2\&. In addition, it checks that the module is in canonical order\&. -.PP -Options for the -\fIlint\fR -checker: -.PP -\fB\-\-lint\-namespace\-prefix\fR \fIprefix\fR -.RS 4 -Validate that the module\*(Aqs namespace is of the form: ""\&. -.RE -.PP -\fB\-\-lint\-modulename\-prefix\fR \fIprefix\fR -.RS 4 -Validate that the module\*(Aqs name starts with -\fIprefix\fR\&. -.RE -.PP -\fB\-\-lint\-ensure\-hyphenated\-names\fR -.RS 4 -Validate that all identifiers use hyphenated style, i\&.e\&., no uppercase letters or underscores\&. -.RE -.SH "YANG SCHEMA ITEM IDENTIFIERS (SID)" -.PP -YANG Schema Item iDentifiers (SID) are globally unique unsigned integers used to identify YANG items\&. SIDs are used instead of names to save space in constrained applications such as COREconf\&. This plugin is used to automatically generate and updated \&.sid files used to persist and distribute SID assignments\&. -.PP -Options for generating, updating and checking \&.sid files: -.PP -\fB\-\-sid\-generate\-file\fR -.RS 4 -This option is used to generate a new \&.sid file from a YANG module\&. -.sp -Two arguments are required to generate a \&.sid file; the SID range assigned to the YANG module and its definition file\&. The SID range specified is a sub\-range within a range obtained from a registrar or a sub\-range within the experimental range (i\&.e\&. 60000 to 99999)\&. The SID range consists of the first SID of the range, followed by a colon, followed by the number of SID allocated to the YANG module\&. The filename consists of the module name, followed by an @ symbol, followed by the module revision, followed by the "\&.yang" extension\&. -.sp This example shows how to generate the file -\fItoaster@2009\-11\-20\&.sid\fR\&. -.sp -.if n \{\ -.RS 4 -.\} +\f[I]toaster\[at]2009-11-20.sid\f[R]. +.IP .nf -$ pyang \-\-sid\-generate\-file 20000:100 toaster@2009\-11\-20\&.yang +\f[C] +$ pyang --sid-generate-file 20000:100 toaster\[at]2009-11-20.yang +\f[R] .fi -.if n \{\ -.RE -.\} .RE +.TP +\f[B]--sid-update-file\f[R] +Each time new items are added to a YANG module by the introduction of a +new revision of this module, its included sub-modules or imported +modules, the associated .sid file need to be updated. +This is done by using the \f[B]--sid-update-file\f[R] option. +.RS +.PP +Two arguments are required to generate a .sid file for an updated YANG +module; the previous .sid file generated for the YANG module and the +definition file of the updated module. +Both filenames follow the usual naming conversion consisting of the +module name, followed by an \[at] symbol, followed by the module +revision, followed by the extension. .PP -\fB\-\-sid\-update\-file\fR -.RS 4 -Each time new items are added to a YANG module by the introduction of a new revision of this module, its included sub\-modules or imported modules, the associated \&.sid file need to be updated\&. This is done by using the -\fB\-\-sid\-update\-file\fR -option\&. -.sp -Two arguments are required to generate a \&.sid file for an updated YANG module; the previous \&.sid file generated for the YANG module and the definition file of the updated module\&. Both filenames follow the usual naming conversion consisting of the module name, followed by an @ symbol, followed by the module revision, followed by the extension\&. -.sp This example shows how to generate the file -\fItoaster@2009\-12\-28\&.sid\fR -based on the SIDs already present in -\fItoaster@2009\-11\-20\&.sid\fR\&. -.sp -.if n \{\ -.RS 4 -.\} +\f[I]toaster\[at]2009-12-28.sid\f[R] based on the SIDs already present +in \f[I]toaster\[at]2009-11-20.sid\f[R]. +.IP .nf -$ pyang \-\-sid\-update\-file toaster@2009\-11\-20\&.sid \e -toaster@2009\-12\-28\&.yang +\f[C] +$ pyang --sid-update-file toaster\[at]2009-11-20.sid \[rs] + toaster\[at]2009-12-28.yang +\f[R] .fi -.if n \{\ -.RE -.\} .RE +.TP +\f[B]--sid-check-file\f[R] +The \f[B]--sid-check-file\f[R] option can be used at any time to verify +if a .sid file need to be updated. +.RS +.PP +Two arguments are required to verify a .sid file; the filename of the +\&.sid file to be checked and the corresponding definition file. .PP -\fB\-\-sid\-check\-file\fR -.RS 4 -The -\fB\-\-sid\-check\-file\fR -option can be used at any time to verify if a \&.sid file need to be updated\&. -.sp -Two arguments are required to verify a \&.sid file; the filename of the \&.sid file to be checked and the corresponding definition file\&. -.sp For example: -.sp -.if n \{\ -.RS 4 -.\} +.IP .nf -$ pyang \-\-sid\-check\-file toaster@2009\-12\-28\&.sid \e -toaster@2009\-12\-28\&.yang +\f[C] +$ pyang --sid-check-file toaster\[at]2009-12-28.sid \[rs] + toaster\[at]2009-12-28.yang +\f[R] .fi -.if n \{\ -.RE -.\} .RE -.PP -\fB\-\-sid\-list\fR -.RS 4 -The -\fB\-\-sid\-list\fR -option can be used before any of the previous options to obtains the list of SIDs assigned or validated\&. For example: -.sp -.if n \{\ -.RS 4 -.\} +.TP +\f[B]--sid-list\f[R] +The \f[B]--sid-list\f[R] option can be used before any of the previous +options to obtains the list of SIDs assigned or validated. +For example: +.RS +.IP .nf -$ pyang \-\-sid\-list \-\-sid\-generate\-file 20000:100 \e -toaster@2009\-11\-20\&.yang +\f[C] +$ pyang --sid-list --sid-generate-file 20000:100 \[rs] + toaster\[at]2009-11-20.yang +\f[R] .fi -.if n \{\ -.RE -.\} .RE +.TP +\f[B]--sid-extra-range\f[R] +If needed, an extra SID range can be assigned to an existing YANG module +during its update with the \f[B]--sid-extra-range\f[R] option. +.RS .PP -\fB\-\-sid\-extra\-range\fR -.RS 4 -If needed, an extra SID range can be assigned to an existing YANG module during its update with the -\fB\-\-sid\-extra\-range\fR -option\&. -.sp For example, this command generates the file -\fItoaster@2009\-12\-28\&.sid\fR -using the initial range(s) present in -\fItoaster@2009\-11\-20\&.sid\fR -and the extra range specified in the command line\&. -.sp -.if n \{\ -.RS 4 -.\} +\f[I]toaster\[at]2009-12-28.sid\f[R] using the initial range(s) present +in \f[I]toaster\[at]2009-11-20.sid\f[R] and the extra range specified in +the command line. +.IP .nf -$ pyang \-\-sid\-update\-file toaster@2009\-11\-20\&.sid \e -toaster@2009\-12\-28\&.yang \-\-sid\-extra\-range 20100:100 +\f[C] +$ pyang --sid-update-file toaster\[at]2009-11-20.sid \[rs] + toaster\[at]2009-12-28.yang --sid-extra-range 20100:100 +\f[R] .fi -.if n \{\ -.RE -.\} .RE +.TP +\f[I]count\f[R] +The number of SID required when generating or updating a .sid file can +be computed by specifying \[dq]\f[I]count\f[R]\[dq] as SID range. +.RS .PP -\fIcount\fR -.RS 4 -The number of SID required when generating or updating a \&.sid file can be computed by specifying "\fIcount\fR" as SID range\&. -.sp For example: -.sp -.if n \{\ -.RS 4 -.\} +.IP .nf -$ pyang \-\-sid\-generate\-file count toaster@2009\-11\-20\&.yang +\f[C] +$ pyang --sid-generate-file count \[rs] + toaster\[at]2009-11-20.yang +\f[R] .fi -.if n \{\ -.RE -.\} +.PP or: -.sp -.if n \{\ -.RS 4 -.\} +.IP .nf -$ pyang \-\-sid\-update\-file toaster@2009\-11\-20\&.sid \e -toaster@2009\-12\-28\&.yang \-\-sid\-extra\-range count +\f[C] +$ pyang --sid-update-file toaster\[at]2009-11-20.sid \[rs] + toaster\[at]2009-12-28.yang --sid-extra-range count +\f[R] .fi -.if n \{\ -.RE -.\} -.RE -.SH "CAPABILITY OUTPUT" -.PP -The -\fIcapability\fR -output prints a capability URL for each module of the input data model, taking into account features and deviations, as described in section 5\&.6\&.4 of -\m[blue]\fBRFC 6020\fR\m[]\&\s-2\u[2]\d\s+2\&. -.PP -Options for the -\fIcapability\fR -output format: -.PP -\fB\-\-capability\-entity\fR -.RS 4 -Write ampersands in the output as XML entities ("&")\&. .RE -.SH "DEPEND OUTPUT" -.PP -The -\fIdepend\fR -output generates a Makefile dependency rule for files based on a YANG module\&. This is useful if files are generated from the module\&. For example, suppose a \&.c file is generated from each YANG module\&. If the YANG module imports other modules, or includes submodules, the \&.c file needs to be regenerated if any of the imported or included modules change\&. Such a dependency rule can be generated like this: -.sp -.if n \{\ -.RS 4 -.\} +.SH CAPABILITY OUTPUT> +.PP +The \f[I]capability\f[R] output prints a capability URL for each module +of the input data model, taking into account features and deviations, as +described in section 5.6.4 of \f[B]RFC 6020\f[R]. +.PP +Options for the \f[I]capability\f[R] output format: +.TP +\f[B]--capability-entity\f[R] +Write ampersands in the output as XML entities (\[dq]&\[dq]). +.SH DEPEND OUTPUT +.PP +The \f[I]depend\f[R] output generates a Makefile dependency rule for +files based on a YANG module. +This is useful if files are generated from the module. +For example, suppose a .c file is generated from each YANG module. +If the YANG module imports other modules, or includes submodules, the .c +file needs to be regenerated if any of the imported or included modules +change. +Such a dependency rule can be generated like this: +.IP .nf -$ pyang \-f depend \-\-depend\-target mymod\&.c \e - \-\-depend\-extension \&.yang mymod\&.yang - mymod\&.c : ietf\-yang\-types\&.yang my\-types\&.yang +\f[C] +$ pyang -f depend --depend-target mymod.c \[rs] + --depend-extension .yang mymod.yang +mymod.c : ietf-yang-types.yang my-types.yang +\f[R] .fi -.if n \{\ -.RE -.\} -.PP -Options for the -\fIdepend\fR -output format: -.PP -\fB\-\-depend\-target\fR -.RS 4 -Makefile rule target\&. Default is the module name\&. -.RE -.PP -\fB\-\-depend\-extension\fR -.RS 4 -YANG module file name extension\&. Default is no extension\&. -.RE -.PP -\fB\-\-depend\-no\-submodules\fR -.RS 4 -Do not generate dependencies for included submodules\&. -.RE -.PP -\fB\-\-depend\-from\-submodules\fR -.RS 4 -Generate dependencies taken from all included submodules\&. -.RE .PP -\fB\-\-depend\-recurse\fR -.RS 4 -Recurse into imported modules and generate dependencies for their imported modules etc\&. -.RE -.PP -\fB\-\-depend\-include\-path\fR -.RS 4 -Include file path in the prerequisites\&. Note that if no -\fB\-\-depend\-extension\fR -has been given, the prerequisite is the filename as found, i\&.e\&., ending in "\&.yang" or "\&.yin"\&. -.RE -.PP -\fB\-\-depend\-ignore\-module\fR -.RS 4 -Name of YANG module or submodule to ignore in the prerequisites\&. This option can be given multiple times\&. -.RE -.SH "DSDL OUTPUT" -.PP -The -\fIdsdl\fR -output takes a data model consisting of one or more YANG modules and generates a hybrid DSDL schema as described in -\m[blue]\fBRFC 6110\fR\m[]\&\s-2\u[4]\d\s+2\&. The hybrid schema is primarily intended as an interim product used by -\fByang2dsdl\fR(1)\&. -.PP -The -\fIdsdl\fR -plugin also supports metadata annotations, if they are defined and used as described in -\m[blue]\fBRFC 7952\fR\m[]\&\s-2\u[8]\d\s+2\&. -.PP -Options for the -\fIdsdl\fR -output format: -.PP -\fB\-\-dsdl\-no\-documentation\fR -.RS 4 -Do not print documentation annotations -.RE -.PP -\fB\-\-dsdl\-no\-dublin\-core\fR -.RS 4 +Options for the \f[I]depend\f[R] output format: +.TP +\f[B]--depend-target\f[R] +Makefile rule target. +Default is the module name. +.TP +\f[B]--depend-extension\f[R] +YANG module file name extension. +Default is no extension. +.TP +\f[B]--depend-no-submodules\f[R] +Do not generate dependencies for included submodules. +.TP +\f[B]--depend-from-submodules\f[R] +Generate dependencies taken from all included submodules. +.TP +\f[B]--depend-recurse\f[R] +Recurse into imported modules and generate dependencies for their +imported modules etc. +.TP +\f[B]--depend-include-path\f[R] +Include file path in the prerequisites. +Note that if no \f[B]--depend-extension\f[R] has been given, the +prerequisite is the filename as found, i.e., ending in \[dq].yang\[dq] +or \[dq].yin\[dq]. +.TP +\f[B]--depend-ignore-module\f[R] +Name of YANG module or submodule to ignore in the prerequisites. +This option can be given multiple times. +.SH DSDL Output +.PP +The \f[I]dsdl\f[R] output takes a data model consisting of one or more +YANG modules and generates a hybrid DSDL schema as described in \f[B]RFC +6110\f[R]. +The hybrid schema is primarily intended as an interim product used by +\f[B]yang2dsdl\f[R](1). +.PP +The \f[I]dsdl\f[R] plugin also supports metadata annotations, if they +are defined and used as described in \f[B]RFC 7952\f[R]. +.PP +Options for the \f[I]dsdl\f[R] output format: +.TP +\f[B]--dsdl-no-documentation\f[R] Do not print Dublin Core metadata terms -.RE -.PP -\fB\-\-dsdl\-record\-defs\fR -.RS 4 -Record translations of all top\-level typedefs and groupings in the output schema, even if they are not used\&. This is useful for translating library modules\&. -.RE -.SH "JSONXSL OUTPUT" -.PP -The -\fIjsonxsl\fR -output generates an XSLT 1\&.0 stylesheet that can be used for transforming an XML instance document into JSON text as specified in -\m[blue]\fBRFC 7951\fR\m[]\&\s-2\u[9]\d\s+2\&. The XML document must be a valid instance of the data model which is specified as one or more input YANG modules on the command line (or via a message, see the -\fB\-\-hello\fR -option)\&. -.PP -The -\fIjsonxsl\fR -plugin also converts metadata annotations, if they are defined and used as described in -\m[blue]\fBRFC 7952\fR\m[]\&\s-2\u[8]\d\s+2\&. -.PP -The data tree(s) must be wrapped at least in either or element, where "nc" is the namespace prefix for the standard NETCONF URI "urn:ietf:params:xml:ns:netconf:base:1\&.0", or the XML instance document has to be a complete NETCONF RPC request/reply or notification\&. Translation of RPCs and notifications defined by the data model is also supported\&. -.PP -The generated stylesheet accepts the following parameters that modify its behaviour: -.sp -.RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -.sp -1 -.IP \(bu 2.3 -.\} -\fIcompact\fR: setting this parameter to 1 results in a compact representation of the JSON text, i\&.e\&. without any whitespace\&. The default is 0 which means that the JSON output is pretty\-printed\&. -.RE -.sp -.RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -.sp -1 -.IP \(bu 2.3 -.\} -\fIind\-step\fR: indentation step, i\&.e\&. the number of spaces to use for each level\&. The default value is 2 spaces\&. Note that this setting is only useful for pretty\-printed output (compact=0)\&. -.RE -.PP -The stylesheet also includes the file -jsonxsl\-templates\&.xsl -which is a part of -\fBpyang\fR -distribution\&. -.SH "JSTREE OUTPUT" -.PP -The -\fIjstree\fR -output grenerates an HTML/JavaScript page that presents a tree\-navigator to the given YANG module(s)\&. +.TP +\f[B]--dsdl-record-defs\f[R] +Record translations of all top-level typedefs and groupings in the +output schema, even if they are not used. +This is useful for translating library modules. +.SH JSONXSL OUTPUT +.PP +The \f[I]jsonxsl\f[R] output generates an XSLT 1.0 stylesheet that can +be used for transforming an XML instance document into JSON text as +specified in \f[B]RFC 7951\f[R]. +The XML document must be a valid instance of the data model which is +specified as one or more input YANG modules on the command line (or via +a message, see the \f[B]--hello\f[R] option). +.PP +The \f[I]jsonxsl\f[R] plugin also converts metadata annotations, if they +are defined and used as described in \f[B]RFC 7952\f[R]. +.PP +The data tree(s) must be wrapped at least in either or + element, where \[dq]nc\[dq] is the namespace prefix for the +standard NETCONF URI \[dq]urn:ietf:params:xml:ns:netconf:base:1.0\[dq], +or the XML instance document has to be a complete NETCONF RPC +request/reply or notification. +Translation of RPCs and notifications defined by the data model is also +supported. +.PP +The generated stylesheet accepts the following parameters that modify +its behaviour: +.IP \[bu] 2 +\f[I]compact\f[R]: setting this parameter to 1 results in a compact +representation of the JSON text, i.e., without any whitespace. +The default is 0 which means that the JSON output is pretty-printed. +.IP \[bu] 2 +\f[I]ind-step\f[R]: indentation step, i.e., the number of spaces to use +for each level. +The default value is 2 spaces. +Note that this setting is only useful for pretty-printed output +(compact=0). +.PP +The stylesheet also includes the file \f[I]jsonxsl-templates.xsl\f[R] +which is a part of \f[B]pyang\f[R] distribution. +.SH JSTREE OUTPUT +.PP +The \f[I]jstree\f[R] output grenerates an HTML/JavaScript page that +presents a tree-navigator to the given YANG module(s). .PP jstree output specific option: -.PP -\fB\-\-jstree\-no\-path\fR -.RS 4 -Do not include paths in the output\&. This option makes the page less wide\&. -.RE -.SH "JTOX OUTPUT" -.PP -The -\fIjtox\fR -output generates a driver file which can be used as one of the inputs to -\fBjson2xml\fR -for transforming a JSON document to XML as specified in -\m[blue]\fBRFC 7951\fR\m[]\&\s-2\u[9]\d\s+2\&. -.PP -The -\fIjtox\fR -output itself is a JSON document containing a concise representation of the data model which is specified as one or more input YANG modules on the command line (or via a message, see the -\fB\-\-hello\fR -option)\&. -.PP -See -\fBjson2xml\fR -manual page for more information\&. -.SH "OMNI OUTPUT" -.PP -The plugin generates an applescript file that draws a diagram in OmniGraffle\&. Requires OmniGraffle 6\&. Usage: -.sp .if n \{\ .RS 4 .\} .nf $ pyang \-f omni foo\&.yang \-o foo\&.scpt $ osascript foo\&.scpt .fi .if n \{\ .RE .\} +.TP +\f[B]--jstree-no-path\f[R] +Do not include paths in the output. +This option makes the page less wide. +.SH JTOX OUTPUT +.PP +The \f[I]jtox\f[R] output generates a driver file which can be used as +one of the inputs to \f[B]json2xml\f[R] for transforming a JSON document +to XML as specified in \f[B]RFC 7951\f[R]. +.PP +The \f[I]jtox\f[R] output itself is a JSON document containing a concise +representation of the data model which is specified as one or more input +YANG modules on the command line (or via a message, see the +\f[B]--hello\f[R] option). +.PP +See \f[B]json2xml\f[R] manual page for more information. +.SH OMNI OUTPUT +.PP +The plugin generates an applescript file that draws a diagram in +OmniGraffle. +Requires OmniGraffle 6. +Usage: +.IP +.nf +\f[C] + $ pyang -f omni foo.yang -o foo.scpt + $ osascript foo.scpt +\f[R] +.fi .PP omni output specific option: -.PP -\fB\-\-omni\-path\fR \fIpath\fR -.RS 4 -Subtree to print\&. The -\fIpath\fR -is a slash ("/") separated path to a subtree to print\&. For example "/nacm/groups"\&. -.RE -.SH "NAME OUTPUT" -.PP -The -\fIname\fR -output prints the name of each module in the input data model\&. For submodules, it also shows the name of the main module to which the submodule belongs\&. +.TP +\f[B]--omni-path\f[R] \f[I]path\f[R] +Subtree to print. +The \f[I]path\f[R] is a slash (\[dq]/\[dq]) separated path to a subtree +to print. +For example \[dq]/nacm/groups\[dq]. +.SH NAME OUTPUT +.PP +The \f[I]name\f[R] output prints the name of each module in the input +data model. +For submodules, it also shows the name of the main module to which the +submodule belongs. .PP name output specific option: -.PP -\fB\-\-name\-print\-revision\fR -.RS 4 -Print the name and revision in name@revision format\&. -.RE -.SH "SAMPLE-XML-SKELETON OUTPUT" -.PP -The -\fIsample\-xml\-skeleton\fR -output generates an XML instance document with sample elements for all nodes in the data model, according to the following rules: -.sp -.RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -.sp -1 -.IP \(bu 2.3 -.\} -An element is present for every leaf, container or anyxml\&. -.RE -.sp -.RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -.sp -1 -.IP \(bu 2.3 -.\} -At least one element is present for every leaf\-list or list\&. The number of entries in the sample is min(1, min\-elements)\&. -.RE -.sp -.RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -.sp -1 -.IP \(bu 2.3 -.\} -For a choice node, sample element(s) are present for each case\&. -.RE -.sp -.RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -.sp -1 -.IP \(bu 2.3 -.\} -Leaf, leaf\-list and anyxml elements are empty (but see the -\fB\-\-sample\-xml\-skeleton\-defaults\fR -option below)\&. -.RE -.PP -Note that the output document will most likely be invalid and needs manual editing\&. -.PP -Options specific to the -\fIsample\-xml\-skeleton\fR -output format: -.PP -\fB\-\-sample\-xml\-skeleton\-annotations\fR -.RS 4 -Add XML comments to the sample documents with hints about expected contents, for example types of leaf nodes, permitted number of list entries etc\&. -.RE -.PP -\fB\-\-sample\-xml\-skeleton\-defaults\fR -.RS 4 -Add leaf elements with defined defaults to the output with their default value\&. Without this option, the default elements are omitted\&. -.RE -.PP -\fB\-\-sample\-xml\-skeleton\-doctype=\fR\fB\fItype\fR\fR -.RS 4 -Type of the sample XML document\&. Supported values for -\fItype\fR -are -data -(default) and -config\&. This option determines the document element of the output XML document ( or in the NETCONF namespace) and also affects the contents: for -config, only data nodes representing configuration are included\&. -.RE -.PP -\fB\-\-sample\-xml\-skeleton\-path=\fR\fB\fIpath\fR\fR -.RS 4 -Subtree of the sample XML document to generate, including all ancestor elements\&. The -\fIpath\fR -is a slash ("/") separated list of data node names that specifies the path to a subtree to print\&. For example "/nacm/rule\-list/rule/rpc\-name"\&. -.RE -.SH "TREE OUTPUT" -.PP -The -\fItree\fR -output prints the resulting schema tree from one or more modules\&. Use -\fBpyang \-\-tree\-help\fR -to print a description on the symbols used by this format\&. +.TP +\f[B]--name-print-revision\f[R] +Print the name and revision in name\[at]revision format. +.SH SAMPLE-XML-SKELETON OUTPUT +.PP +The \f[I]sample-xml-skeleton\f[R] output generates an XML instance +document with sample elements for all nodes in the data model, according +to the following rules: +.IP \[bu] 2 +An element is present for every leaf, container or anyxml. +.IP \[bu] 2 +At least one element is present for every leaf-list or list. +The number of entries in the sample is min(1, +.IP \[bu] 2 +For a choice node, sample element(s) are present for each case. +.IP \[bu] 2 +Leaf, leaf-list and anyxml elements are empty (but see the +\f[B]--sample-xml-skeleton-defaults\f[R] option below). +.PP +Note that the output document will most likely be invalid and needs +manual editing. +.PP +Options specific to the \f[I]sample-xml-skeleton\f[R] output format: +.TP +\f[B]--sample-xml-skeleton-annotations\f[R] +Add XML comments to the sample documents with hints about expected +contents, for example types of leaf nodes, permitted number of list +entries etc. +.TP +\f[B]--sample-xml-skeleton-defaults\f[R] +Add leaf elements with defined defaults to the output with their default +value. +Without this option, the default elements are omitted. +.TP +\f[B]--sample-xml-skeleton-doctype=\f[R]_type_ +Type of the sample XML document. +Supported values for \f[I]type\f[R] are \f[B]data\f[R] (default) and +\f[B]config\f[R]. +This option determines the document element of the output XML document +( or in the NETCONF namespace) and also affects the +contents: for \f[B]config\f[R], only data nodes representing +configuration are included. +.TP +\f[B]--sample-xml-skeleton-path=\f[R]_path_ +Subtree of the sample XML document to generate, including all ancestor +elements. +The \f[I]path\f[R] is a slash (\[dq]/\[dq]) separated list of data node +names that specifies the path to a subtree to print. +For example \[dq]/nacm/rule-list/rule/rpc-name\[dq]. +.SH TREE OUTPUT +.PP +The \f[I]tree\f[R] output prints the resulting schema tree from one or +more modules. +Use \f[B]pyang --tree-help\f[R] to print a description on the symbols +used by this format. .PP Tree output specific options: -.PP -\fB\-\-tree\-help\fR -.RS 4 -Print help on symbols used in the tree output and exit\&. -.RE -.PP -\fB\-\-tree\-depth\fR \fIdepth\fR -.RS 4 -Levels of the tree to print\&. -.RE -.PP -\fB\-\-tree\-path\fR \fIpath\fR -.RS 4 -Subtree to print\&. The -\fIpath\fR -is a slash ("/") separated path to a subtree to print\&. For example "/nacm/groups"\&. All ancestors and the selected subtree are printed\&. -.RE -.PP -\fB\-\-tree\-print\-groupings\fR -.RS 4 -Print the top\-level groupings defined in the module\&. -.RE -.PP -\fB\-\-tree\-print\-structures\fR -.RS 4 -Print the ietf\-yang\-structure\-ext:structure structures defined in the module\&. -.RE -.PP -\fB\-\-tree\-print\-yang\-data\fR -.RS 4 -Print the ietf\-restconf:yang\-data structures defined in the module\&. -.RE -.PP -\fB\-\-tree\-line\-length\fR \fImaxlen\fR -.RS 4 -Try to break lines so they are no longer than -\fImaxlen\fR\&. This is a best effort algorithm\&. -.RE -.PP -\fB\-\-tree\-module\-name\-prefix\fR \fImaxlen\fR -.RS 4 -Use the module name (instead of the prefix) to prefix parameters and types\&. -.RE -.SH "FLATTEN OUTPUT" -.PP -The -\fIflatten\fR -output flattens provided YANG module and outputs the schema nodes and some of their properties in CSV format\&. +.TP +\f[B]--tree-help\f[R] +Print help on symbols used in the tree output and exit. +.TP +\f[B]--tree-depth\f[R] \f[I]depth\f[R] +Levels of the tree to print. +.TP +\f[B]--tree-path\f[R] \f[I]path\f[R] +Subtree to print. +The \f[I]path\f[R] is a slash (\[dq]/\[dq]) separated path to a subtree +to print. +For example \[dq]/nacm/groups\[dq]. +All ancestors and the selected subtree are printed. +.TP +\f[B]--tree-print-groupings\f[R] +Print the top-level groupings defined in the module. +.TP +\f[B]--tree-print-structures\f[R] +Print the ietf-yang-structure-ext:structure structures defined in the +module. +.TP +\f[B]--tree-print-yang-data\f[R] +Print the ietf-restconf:yang-data structures defined in the module. +.TP +\f[B]--tree-line-length\f[R] \f[I]maxlen\f[R] +Try to break lines so they are no longer than \f[I]maxlen\f[R]. +This is a best effort algorithm. +.TP +\f[B]--tree-module-name-prefix\f[R] \f[I]maxlen\f[R] +Use the module name (instead of the prefix) to prefix parameters and +types. +.SH FLATTEN OUTPUT +.PP +The \f[I]flatten\f[R] output flattens provided YANG module and outputs +the schema nodes and some of their properties in CSV format. .PP Flatten output specific options: -.PP -\fB\-\-flatten\-no\-header\fR -.RS 4 -Do not emit the CSV header\&. -.RE -.PP -\fB\-\-flatten\-keyword\fR -.RS 4 -Output the keyword\&. This will resolve as container, leaf, etc\&. -.RE -.PP -\fB\-\-flatten\-type\fR -.RS 4 -Output the top\-level type\&. This will resolve to a module\-prefixed type\&. -.RE -.PP -\fB\-\-flatten\-primitive\-type\fR -.RS 4 -Output the primitive type\&. This resolves to a YANG type such as uint64\&. -.RE -.PP -\fB\-\-flatten\-flag\fR -.RS 4 -Output flag property\&. Derives a flag \- for instance rw/ro for config, or x for RPC\&. -.RE -.PP -\fB\-\-flatten\-description\fR -.RS 4 -Output the description\&. -.RE -.PP -\fB\-\-flatten\-keys\fR -.RS 4 -Output whether the XPath is identified as a key\&. -\fIkey\fR -or null will be output per XPath\&. -.RE -.PP -\fB\-\-flatten\-keys\-in\-xpath\fR -.RS 4 -Output the XPath with keys in path\&. -.RE -.PP -\fB\-\-flatten\-prefix\-in\-xpath\fR -.RS 4 -Output the XPath with prefixes instead of modules\&. -.RE -.PP -\fB\-\-flatten\-qualified\-in\-xpath\fR -.RS 4 -Output the qualified XPath i\&.e\&. /module1:root/module1:node/module2:node/\&.\&.\&. -.RE -.PP -\fB\-\-flatten\-qualified\-module\-and\-prefix\-path\fR -.RS 4 -Output an XPath with both module and prefix i\&.e\&. /module1:prefix1:root/\&.\&.\&. This is -\fINOT\fR -a colloquial syntax of XPath\&. Emitted separately\&. -.RE -.PP -\fB\-\-flatten\-deviated\fR -.RS 4 -Output deviated nodes in the schema as well\&. -.RE -.PP -\fB\-\-flatten\-data\-keywords\fR -.RS 4 -Flatten all data keywords instead of only data definition keywords\&. -.RE -.PP -\fB\-\-flatten\-filter\-keyword\fR \fIkeyword\fR -.RS 4 -Filter output to only desired keywords\&. Keywords specified are what will be displayed in output\&. Can be specified more than once\&. -.RE -.PP -\fB\-\-flatten\-filter\-primitive\fR \fIprimitive_type\fR -.RS 4 -Filter output to only desired primitive types\&. Primitives specified are what will be displayed in output\&. Can be specified more than once\&. -.RE -.PP -\fB\-\-flatten\-filter\-flag\fR \fIchoice\fR -.RS 4 -Filter output to flag\&. -\fIrw\fR -for configuration data\&. -\fIro\fR -for non\-configuration data, output parameters to rpcs and actions, and notification parameters\&. -\fIw\fR -for input parameters to rpcs and actions\&. -\fIu\fR -for uses of a grouping\&. -\fIx\fR -for rpcs and actions\&. -\fIn\fR -for notifications\&. -.RE -.PP -\fB\-\-flatten\-csv\-dialect\fR \fIdialect\fR -.RS 4 -CSV dialect for output\&. excel | excel\-tab | unix -.RE -.PP -\fB\-\-flatten\-ignore\-no\-primitive\fR -.RS 4 -Ignore error if primitive is missing\&. -.RE -.PP -\fB\-\-flatten\-status\fR -.RS 4 -Output the status statement value\&. -.RE -.PP -\fB\-\-flatten\-resolve\-leafref\fR -.RS 4 -Output the XPath of the leafref target\&. -.RE -.SH "UML OUTPUT" -.PP -The -\fIuml\fR -output prints an output that can be used as input\-file to -\fBplantuml\fR -(http://plantuml\&.sourceforge\&.net) in order to generate a UML diagram\&. Note that it requires -\fBgraphviz\fR -(http://www\&.graphviz\&.org/)\&. -.PP -For large diagrams you may need to increase the Java heap\-size by the \-XmxSIZEm option, to java\&. For example: -\fBjava \-Xmx1024m \-jar plantuml\&.jar \&.\&.\&.\&.\fR -.PP -Options for the -\fIUML\fR -output format: -.PP -\fB\-\-uml\-classes\-only\fR -.RS 4 +.TP +\f[B]--flatten-no-header\f[R] +Do not emit the CSV header. +.TP +\f[B]--flatten-keyword\f[R] +Output the keyword. +This will resolve as container, leaf, etc. +.TP +\f[B]--flatten-type\f[R] +Output the top-level type. +This will resolve to a module-prefixed type. +.TP +\f[B]--flatten-primitive-type\f[R] +Output the primitive type. +This resolves to a YANG type such as uint64. +.TP +\f[B]--flatten-flag\f[R] +Output flag property. +Derives a flag - for instance rw/ro for config, or x for RPC. +.TP +\f[B]--flatten-description\f[R] +Output the description. +.TP +\f[B]--flatten-keys\f[R] +Output whether the XPath is identified as a key. +\f[I]key\f[R] or null will be output per XPath. +.TP +\f[B]--flatten-keys-in-xpath\f[R] +Output the XPath with keys in path. +.TP +\f[B]--flatten-prefix-in-xpath\f[R] +Output the XPath with prefixes instead of modules. +.TP +\f[B]--flatten-qualified-in-xpath\f[R] +Output the qualified XPath i.e., +/module1:root/module1:node/module2:node/\&... +.TP +\f[B]--flatten-qualified-module-and-prefix-path\f[R] +Output an XPath with both module and prefix i.e., +/module1:prefix1:root/\&... This is NOT a colloquial syntax of XPath. +Emitted separately. +.TP +\f[B]--flatten-deviated\f[R] +Flatten all data keywords instead of only data definition keywords. +.TP +\f[B]--flatten-filter-keyword\f[R] \f[I]keyword\f[R] +Filter output to only desired keywords. +Keywords specified are what will be displayed in output. +Can be specified more than once. +.TP +\f[B]--flatten-filter-primitive\f[R] \f[I]primitive_type\f[R] +Filter output to only desired primitive types. +Primitives specified are what will be displayed in output. +Can be specified more than once. +.TP +\f[B]--flatten-filter-flag\f[R] \f[I]choice\f[R] +Filter output to flag. +.RS +.IP \[bu] 2 +\f[I]rw\f[R] for configuration data. +.IP \[bu] 2 +\f[I]ro\f[R] for non-configuration data, output parameters to rpcs and +actions, and notification parameters. +.IP \[bu] 2 +\f[I]w\f[R] for input parameters to rpcs and actions. +.IP \[bu] 2 +\f[I]u\f[R] for uses of a grouping. +.IP \[bu] 2 +\f[I]x\f[R] for rpcs and actions. +.IP \[bu] 2 +\f[I]n\f[R] for notifications. +.RE +.TP +\f[B]--flatten-csv-dialect\f[R] \f[I]dialect\f[R] +CSV dialect for output. +\f[I]dialect\f[R] is one of \f[B]excel\f[R], \f[B]excel-tab\f[R], or +\f[B]unix\f[R]. +.TP +\f[B]--flatten-ignore-no-primitive\f[R] +Ignore error if primitive is missing. +.TP +\f[B]--flatten-status\f[R] +Output the status statement value. +.TP +\f[B]--flatten-resolve-leafref\f[R] +Output the XPath of the leafref target. +.SH UML OUTPUT +.PP +The \f[I]uml\f[R] output prints an output that can be used as input-file +to \f[B]plantuml\f[R] (http://plantuml.sourceforge.net) in order to +generate a UML diagram. +Note that it requires \f[B]graphviz\f[R] (http://www.graphviz.org/). +.PP +For large diagrams you may need to increase the Java heap-size by the +-XmxSIZEm option, to java. +For example: \f[B]java -Xmx1024m -jar plantuml.jar \&....\f[R] +.PP +Options for the \f[I]UML\f[R] output format: +.TP +\f[B]--uml-classes-only\f[R] Generate UML with classes only, no attributes -.RE -.PP -\fB\-\-uml\-split\-pages=\fR\fB\fIlayout\fR\fR -.RS 4 -Generate UML output split into pages, NxN, example 2x2\&. One \&.png file per page will be rendered\&. -.RE -.PP -\fB\-\-uml\-output\-directory=\fR\fB\fIdirectory\fR\fR -.RS 4 -Put the generated \&.png files(s) in the specified output directory\&. Default is "img/" -.RE -.PP -\fB\-\-uml\-title=\fR\fB\fItitle\fR\fR -.RS 4 -Set the title of the generated UML diagram, (default is YANG module name)\&. -.RE -.PP -\fB\-\-uml\-header=\fR\fB\fIheader\fR\fR -.RS 4 -Set the header of the generated UML diagram\&. -.RE -.PP -\fB\-\-uml\-footer=\fR\fB\fIfooter\fR\fR -.RS 4 -Set the footer of the generated UML diagram\&. -.RE -.PP -\fB\-\-uml\-long\-identifers\fR -.RS 4 -Use complete YANG schema identifiers for UML class names\&. -.RE -.PP -\fB\-\-uml\-no=\fR\fB\fIarglist\fR\fR -.RS 4 -This option suppresses specified arguments in the generated UML diagram\&. Valid arguments are: uses, leafref, identity, identityref, typedef, annotation, import, circles, stereotypes\&. Annotation suppresses YANG constructs rendered as annotations, examples module info, config statements for containers\&. Example \-\-uml\-no=circles,stereotypes,typedef,import -.RE -.PP -\fB\-\-uml\-truncate=\fR\fB\fIelemlist\fR\fR -.RS 4 -Leafref attributes and augment elements can have long paths making the classes too wide\&. This option will only show the tail of the path\&. Example \-\-uml\-truncate=augment,leafref\&. -.RE -.PP -\fB\-\-uml\-inline\-groupings\fR -.RS 4 -Render the diagram with groupings inlined\&. -.RE -.PP -\fB\-\-uml\-inline\-augments\fR -.RS 4 -Render the diagram with augments inlined\&. -.RE -.PP -\fB\-\-uml\-max\-enums=\fR\fB\fInumber\fR\fR -.RS 4 -Maximum of enum items rendered\&. -.RE -.PP -\fB\-\-uml\-filter\-file=\fR\fB\fIfile\fR\fR -.RS 4 -NOT IMPLEMENTED: Only paths in the filter file will be included in the diagram\&. A default filter file is generated by option \-\-filter\&. -.RE -.SH "YANG OUTPUT" -.PP -Options for the -\fIyang\fR -output format: -.PP -\fB\-\-yang\-canonical\fR -.RS 4 -Generate all statements in the canonical order\&. -.RE -.PP -\fB\-\-yang\-remove\-unused\-imports\fR -.RS 4 -Remove unused import statements from the output\&. -.RE -.PP -\fB\-\-yang\-remove\-comments\fR -.RS 4 -Remove all comments from the output\&. -.RE -.PP -\fB\-\-yang\-line\-length\fR \fIlen\fR -.RS 4 -Try to format each line with a maximum line length of -\fIlen\fR\&. Does not reformat long lines within strings\&. -.RE -.SH "YIN OUTPUT" -.PP -Options for the -\fIyin\fR -output format: -.PP -\fB\-\-yin\-canonical\fR -.RS 4 -Generate all statements in the canonical order\&. -.RE -.PP -\fB\-\-yin\-pretty\-strings\fR -.RS 4 -Pretty print strings, i\&.e\&. print with extra whitespace in the string\&. This is not strictly correct, since the whitespace is significant within the strings in XML, but the output is more readable\&. -.RE -.SH "YANG EXTENSIONS" -.PP -This section describes XPath functions that can be used in "must", "when", or "path" expressions in YANG modules, in addition to the core XPath 1\&.0 functions\&. -.PP -\fBpyang\fR -can be instructed to reject the usage of these functions with the parameter -\fI\-\-strict\fR\&. -.PP -\fBFunction:\fR\fInode\-set\fR\fBderef\fR(\fInode\-set\fR) -.PP -The -\fBderef\fR -function follows the reference defined by the first node in document order in the argument node\-set, and returns the nodes it refers to\&. -.PP -If the first argument node is an -\fBinstance\-identifier\fR, the function returns a node\-set that contains the single node that the instance identifier refers to, if it exists\&. If no such node exists, an empty node\-set is returned\&. -.PP -If the first argument node is a -\fBleafref\fR, the function returns a node\-set that contains the nodes that the leafref refers to\&. -.PP -If the first argument node is of any other type, an empty node\-set is returned\&. -.PP -The following example shows how a leafref can be written with and without the -\fBderef\fR -function: -.sp -.if n \{\ -.RS 4 -.\} +.TP +\f[B]--uml-split-pages=\f[R]_layout_ +Generate UML output split into pages, NxN, example 2x2. +One .png file per page will be rendered. +.TP +\f[B]--uml-output-directory=\f[R]_directory_ +Put the generated .png files(s) in the specified output directory. +Default is \[dq]img/\[dq] +.TP +\f[B]--uml-title=\f[R]_title_ +Set the title of the generated UML diagram, (default is YANG module +name). +.TP +\f[B]--uml-header=\f[R]_header_ +Set the header of the generated UML diagram. +.TP +\f[B]--uml-footer=\f[R]_footer_ +Set the footer of the generated UML diagram. +.TP +\f[B]--uml-long-identifers\f[R] +Use complete YANG schema identifiers for UML class names. +.TP +\f[B]--uml-no=\f[R]_arglist_ +Render the diagram with groupings inlined. +.TP +\f[B]--uml-inline-augments\f[R] +Render the diagram with augments inlined. +.TP +\f[B]--uml-max-enums=\f[BI]number\f[B]\f[R] +Maximum of enum items rendered. +.TP +\f[B]--uml-filter-file=\f[BI]file\f[B]\f[R] +NOT IMPLEMENTED: Only paths in the filter file will be included in the +diagram. +A default filter file is generated by option --filter. +.SH YANG OUTPUT +.PP +Options for the \f[I]yang\f[R] output format: +.TP +\f[B]--yang-canonical\f[R] +Generate all statements in the canonical order. +.TP +\f[B]--yang-remove-unused-imports\f[R] +Remove unused import statements from the output. +.TP +\f[B]--yang-remove-comments\f[R] +Remove all comments from the output. +.TP +\f[B]--yang-line-length\f[R] \f[I]len\f[R] +Try to format each line with a maximum line length of \f[I]len\f[R]. +Does not reformat long lines within strings. +.SH YIN OUTPUT +.PP +Options for the \f[I]yin\f[R] output format: +.TP +\f[B]--yin-canonical\f[R] +Generate all statements in the canonical order. +.TP +\f[B]--yin-pretty-strings\f[R] +Pretty print strings, i.e., print with extra whitespace in the string. +This is not strictly correct, since the whitespace is significant within +the strings in XML, but the output is more readable. +.SH YANG XPATH EXTENSIONS +.PP +This section describes XPath functions that can be used in +\[dq]must\[dq], \[dq]when\[dq], or \[dq]path\[dq] expressions in YANG +modules, in addition to the core XPath 1.0 functions. +.PP +\f[B]pyang\f[R] can be instructed to reject the usage of these functions +with the parameter \f[B]--strict\f[R]. +.TP +\f[B]Function:\f[R] \f[I]node-set\f[R] \f[B]deref\f[R](\f[I]node-set\f[R]) +The \f[B]deref\f[R] function follows the reference defined by the first +node in document order in the argument node-set, and returns the nodes +it refers to. +.RS +.PP +If the first argument node is an \f[B]instance-identifier\f[R], the +function returns a node-set that contains the single node that the +instance identifier refers to, if it exists. +If no such node exists, an empty node-set is returned. +.PP +If the first argument node is a \f[B]leafref\f[R], the function returns +a node-set that contains the nodes that the leafref refers to. +.PP +If the first argument node is of any other type, an empty node-set is +returned. +.PP +The following example shows how a leafref can be written with and +without the \f[B]deref\f[R] function: +.IP .nf +\f[C] /* without deref */ -leaf my\-ip { +leaf my-ip { type leafref { - path "/server/ip"; + path \[dq]/server/ip\[dq]; } } -leaf my\-port { +leaf my-port { type leafref { - path "/server[ip = current()/\&.\&./my\-ip]/port"; + path \[dq]/server[ip = current()/../my-ip]/port\[dq]; } } /* with deref */ -leaf my\-ip { +leaf my-ip { type leafref { - path "/server/ip"; + path \[dq]/server/ip\[dq]; } } -leaf my\-port { +leaf my-port { type leafref { - path "deref(\&.\&./my\-ip)/\&.\&./port"; + path \[dq]deref(../my-ip)/../port\[dq]; } } - +\f[R] .fi -.if n \{\ .RE -.\} -.SH "EXAMPLE" -.PP -The following example validates the standard YANG modules with derived types: -.sp -.if n \{\ -.RS 4 -.\} +.SH EXAMPLES +.PP +The following example validates the standard YANG modules with derived +types: +.IP .nf -$ pyang ietf\-yang\-types\&.yang ietf\-inet\-types\&.yang +\f[C] +$ pyang ietf-yang-types.yang ietf-inet-types.yang +\f[R] .fi -.if n \{\ -.RE -.\} .PP -The following example converts the ietf\-yang\-types module into YIN: -.sp -.if n \{\ -.RS 4 -.\} +The following example converts the ietf-yang-types module into YIN: +.IP .nf -$ pyang \-f yin \-o ietf\-yang\-types\&.yin ietf\-yang\-types\&.yang +\f[C] +$ pyang -f yin -o ietf-yang-types.yin ietf-yang-types.yang +\f[R] .fi -.if n \{\ -.RE -.\} .PP -The following example converts the ietf\-netconf\-monitoring module into a UML diagram: -.sp -.if n \{\ -.RS 4 -.\} +The following example converts the ietf-netconf-monitoring module into a +UML diagram: +.IP .nf - $ pyang \-f uml ietf\-netconf\-monitoring\&.yang > \e - ietf\-netconf\-monitoring\&.uml - $ java \-jar plantuml\&.jar ietf\-netconf\-monitoring\&.uml - $ open img/ietf\-netconf\-monitoring\&.png - +\f[C] +$ pyang -f uml ietf-netconf-monitoring.yang > \[rs] + ietf-netconf-monitoring.uml +$ java -jar plantuml.jar ietf-netconf-monitoring.uml +$ open img/ietf-netconf-monitoring.png +\f[R] .fi -.if n \{\ -.RE -.\} -.SH "ENVIRONMENT VARIABLES" -.PP -pyang searches for referred modules in the colon (:) separated path defined by the environment variable -\fB$YANG_MODPATH\fR -and in the directory -\fB$YANG_INSTALL\fR/yang/modules\&. -.PP -pyang searches for plugins in the colon (:) separated path defined by the environment variable -\fB$PYANG_PLUGINDIR\fR\&. -.SH "BUGS" -.sp -.RS 4 -.ie n \{\ -\h'-04' 1.\h'+01'\c -.\} -.el \{\ -.sp -1 -.IP " 1." 4.2 -.\} -The XPath arguments for the -\fImust\fR -and -\fIwhen\fR -statements are checked only for basic syntax errors\&. -.RE -.SH "AUTHORS" +.SH ENVIRONMENT VARIABLES .PP -\fBMartin Björklund\fR <\&mbj@tail\-f\&.com\&> -.br -Tail\-f Systems -.RS 4 -.RE +\f[B]pyang\f[R] searches for referred modules in the colon (:) separated +path defined by the environment variable \f[B]$YANG_MODPATH\f[R] and in +the directory \f[B]$YANG_INSTALL\f[R]/yang/modules. .PP -\fBLadislav Lhotka\fR <\&lhotka@nic\&.cz\&> -.br -CZ\&.NIC -.RS 4 -.RE +\f[B]pyang\f[R] searches for plugins in the colon (:) separated path +defined by the environment variable \f[B]$PYANG_PLUGINDIR\f[R]. +.SH BUGS .PP -\fBStefan Wallin\fR <\&stefan@tail\-f\&.com\&> -.br -Tail\-f Systems -.RS 4 -.RE -.SH "NOTES" -.IP " 1." 4 -RFC 6241 -.RS 4 -\%http://tools.ietf.org/html/rfc6241 -.RE -.IP " 2." 4 -RFC 6020 -.RS 4 -\%http://tools.ietf.org/html/rfc6020 -.RE -.IP " 3." 4 -RFC 7950 -.RS 4 -\%http://tools.ietf.org/html/rfc7950 -.RE -.IP " 4." 4 -RFC 6110 -.RS 4 -\%http://tools.ietf.org/html/rfc6110 -.RE -.IP " 5." 4 -RFC 8407 -.RS 4 -\%http://tools.ietf.org/html/rfc8407 -.RE -.IP " 6." 4 -RFC 2119 -.RS 4 -\%http://tools.ietf.org/html/rfc2119 -.RE -.IP " 7." 4 -RFC 8174 -.RS 4 -\%http://tools.ietf.org/html/rfc8174 -.RE -.IP " 8." 4 -RFC 7952 -.RS 4 -\%http://tools.ietf.org/html/rfc7952 -.RE -.IP " 9." 4 -RFC 7951 -.RS 4 -\%http://tools.ietf.org/html/rfc7951 -.RE +The XPath arguments for the \f[I]must\f[R] and \f[I]when\f[R] statements +are checked only for basic syntax errors. +.SH AUTHORS +.PP +See the file CONTRIBUTORS at https://github.com/mbj4668/pyang. diff --git a/man/man1/yang2dsdl.1 b/man/man1/yang2dsdl.1 index edcc0182..ee2c65a7 100644 --- a/man/man1/yang2dsdl.1 +++ b/man/man1/yang2dsdl.1 @@ -1,445 +1,273 @@ -'\" t -.\" Title: yang2dsdl -.\" Author: Ladislav Lhotka -.\" Generator: DocBook XSL Stylesheets v1.78.1 -.\" Date: 2022-03-30 -.\" Manual: pyang manual -.\" Source: yang2dsdl-2.5.3 -.\" Language: English +.\" Automatically generated by Pandoc 2.9.2.1 .\" -.TH "YANG2DSDL" "1" "2022\-03\-30" "yang2dsdl\-2\&.5\&.3" "pyang manual" -.\" ----------------------------------------------------------------- -.\" * Define some portability stuff -.\" ----------------------------------------------------------------- -.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.\" http://bugs.debian.org/507673 -.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html -.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.ie \n(.g .ds Aq \(aq -.el .ds Aq ' -.\" ----------------------------------------------------------------- -.\" * set default formatting -.\" ----------------------------------------------------------------- -.\" disable hyphenation -.nh -.\" disable justification (adjust text to left margin only) -.ad l -.\" ----------------------------------------------------------------- -.\" * MAIN CONTENT STARTS HERE * -.\" ----------------------------------------------------------------- -.SH "NAME" -yang2dsdl \- translates YANG data models to DSDL schemas and validates instance documents\&. -.SH "SYNOPSIS" -.HP \w'\fByang2dsdl\fR\ 'u -\fByang2dsdl\fR [\-t\ \fItarget\fR] [\-d\ \fIdir\fR] [\-b\ \fIbasename\fR] [\-j] [\-x] [\-c] [\-v\ \fIinstance\fR] \fIfile\fR... -.HP \w'\fByang2dsdl\fR\ 'u -\fByang2dsdl\fR \-L [\-t\ \fItarget\fR] [\-d\ \fIdir\fR] [\-b\ \fIbasename\fR] [\-j] [\-x] [\-c] [\-v\ \fIinstance\fR] \fIfile\fR -.HP \w'\fByang2dsdl\fR\ 'u -\fByang2dsdl\fR \-s [\-t\ \fItarget\fR] [\-d\ \fIdir\fR] \-b\ \fIbasename\fR [\-j] [\-x] [\-c] \-v\ \fIinstance\fR -.HP \w'\fByang2dsdl\fR\ 'u -\fByang2dsdl\fR \-h -.SH "DESCRIPTION" -.PP -This shell script facilitates the translation of a data model described by one or more input YANG modules to DSDL schemas (RELAX NG, Schematron and DSRL) for a selected instance XML document type, as described in -\m[blue]\fBRFC\ \&6110\fR\m[]\&\s-2\u[1]\d\s+2\&. Optionally, the script can validate an instance document of the given type against the schemas\&. -.PP -The input YANG module(s) may be given either directly as -\fIfile\fR -parameter(s) on the command line, or indirectly through a server message which also declares capabilities and features supported by the server\&. The latter alternative is indicated by the -\fB\-L\fR -switch, and only one -\fIfile\fR -parameter may be given in this case\&. -.PP -Input YANG module(s) may be expressed in YANG or YIN syntax\&. The output DSDL schemas are written to the directory -\fIdir\fR -(current directory by default)\&. Unless the option -\fB\-s\fR -is used, this directory must be writable\&. -.PP -Metadata annotations are also supported, if they are defined and used as described in -\m[blue]\fBRFC\ \&7952\fR\m[]\&\s-2\u[2]\d\s+2\&. -.PP -The script can be executed by any shell interpreter compatible with POSIX\&.2, such as -\fBbash\fR(1) -or -\fBdash\fR(1)\&. -.PP -The -\fItarget\fR -argument specifies the type of the target instance document\&. Supported values are: -.PP +.TH "YANG2DSDL" "1" "2023-11-03" "yang2dsdl-2.6.0" "User Manual" +.hy +.SH NAME +.PP +yang2dsdl - translates YANG data models to DSDL schemas and validates +instance documents. +.SH SYNOPSIS +.PP +\f[B]yang2dsdl\f[R] [-t \f[I]target\f[R]] [-d \f[I]dir\f[R]] [-b +\f[I]basename\f[R]] [-j] [-x] [-c] [-v \f[I]instance\f[R]] +\f[I]file\f[R]\&... +.PP +\f[B]yang2dsdl\f[R] -L [-t \f[I]target\f[R]] [-d \f[I]dir\f[R]] [-b +\f[I]basename\f[R]] [-j] [-x] [-c] [-v \f[I]instance\f[R]] +\f[I]file\f[R]\&... +.PP +\f[B]yang2dsdl\f[R] -s [-t \f[I]target\f[R]] [-d \f[I]dir\f[R]] [-b +\f[I]basename\f[R]] [-j] [-x] [-c] [-v \f[I]instance\f[R]] +.PP +\f[B]yang2dsdl\f[R] -h +.SH DESCRIPTION +.PP +This shell script facilitates the translation of a data model described +by one or more input YANG modules to DSDL schemas (RELAX NG, Schematron +and DSRL) for a selected instance XML document type, as described in +\f[B]RFC\ 6110\f[R]. +Optionally, the script can validate an instance document of the given +type against the schemas. +.PP +The input YANG module(s) may be given either directly as \f[I]file\f[R] +parameter(s) on the command line, or indirectly through a server +message which also declares capabilities and features supported by the +server. +The latter alternative is indicated by the \f[B]-L\f[R] switch, and only +one \f[I]file\f[R] parameter may be given in this case. +.PP +Input YANG module(s) may be expressed in YANG or YIN syntax. +The output DSDL schemas are written to the directory \f[I]dir\f[R] +(current directory by default). +Unless the option \f[B]-s\f[R] is used, this directory must be writable. +.PP +Metadata annotations are also supported, if they are defined and used as +described in \f[B]RFC\ 7952\f[R]. +.PP +The script can be executed by any shell interpreter compatible with +POSIX.2, such as \f[B]bash\f[R](1) or \f[B]dash\f[R](1). +.PP +The \f[I]target\f[R] argument specifies the type of the target instance +document. +Supported values are: +.TP data -.RS 4 -Datastore contents (configuration and state data) encapsulated in document element\&. -.RE -.PP +Datastore contents (configuration and state data) encapsulated in + document element. +.TP config -.RS 4 -A configuration datastore contents encapsulated in document element\&. -.RE -.PP -get\-reply -.RS 4 -A complete NETCONF message containing a reply to the operation\&. -.RE -.PP -get\-data\-reply -.RS 4 -A complete NETCONF message containing a reply to the operation\&. -.RE -.PP -get\-config\-reply -.RS 4 -A complete NETCONF message containing a reply to the operation\&. -.RE -.PP -edit\-config -.RS 4 -A complete NETCONF message containing an request\&. Only the RELAX NG schema is generated for this target\&. -.RE -.PP +A configuration datastore contents encapsulated in document +element. +.TP +get-reply +A complete NETCONF message containing a reply to the operation. +.TP +get-data-reply +A complete NETCONF message containing a reply to the +operation. +.TP +get-config-reply +A complete NETCONF message containing a reply to the +operation. +.TP +edit-config +A complete NETCONF message containing an request. +Only the RELAX NG schema is generated for this target. +.TP rpc -.RS 4 -An RPC request defined in an input YANG module\&. -.RE -.PP -rpc\-reply -.RS 4 -An RPC reply defined in an input YANG module\&. -.RE -.PP +An RPC request defined in an input YANG module. +.TP +rpc-reply +An RPC reply defined in an input YANG module. +.TP notification -.RS 4 -An event notification defined in an input YANG module\&. -.RE -.PP -The output schemas are contained in the following four files whose names depend on the arguments -\fIbasename\fR -and -\fItarget\fR: -.PP -\fIbasename\fR\-\fItarget\fR\&.rng -.RS 4 -RELAX NG schema for the target document type\&. -.RE -.PP -\fIbasename\fR\-gdefs\-config\&.rng, \fIbasename\fR\-gdefs\-edit\&.rng, \fIbasename\fR\-gdefs\&.rng -.RS 4 -Auxiliary RELAX NG schema containing global named pattern definitions\&. The first is generated for "config" and "get\-config\-reply" targets, the second for "edit\-config" and the third for the remaining targets\&. -.RE -.PP -\fIbasename\fR\-\fItarget\fR\&.sch -.RS 4 -Schematron schema for the target document type\&. Not generated for the "edit\-config" target\&. -.RE -.PP -\fIbasename\fR\-\fItarget\fR\&.dsrl -.RS 4 -DSRL schema for the target document type\&. Not generated for the "edit\-config" target\&. -.RE +An event notification defined in an input YANG module. +.PP +The output schemas are contained in the following four files whose names +depend on the arguments \f[I]basename\f[R] and \f[I]target\f[R]: +.TP +\f[I]basename\f[R]-\f[I]target\f[R].rng +RELAX NG schema for the target document type. +.TP +\f[I]basename\f[R]-gdefs-config.rng, \f[I]basename\f[R]-gdefs-edit.rng, \f[I]basename\f[R]-gdefs.rng +Auxiliary RELAX NG schema containing global named pattern definitions. +The first is generated for \[lq]config\[rq] and +\[lq]get-config-reply\[rq] targets, the second for \[lq]edit-config\[rq] +and the third for the remaining targets. +.TP +\f[I]basename\f[R]-\f[I]target\f[R].sch +Schematron schema for the target document type. +Not generated for the \[lq]edit-config\[rq] target. +.TP +\f[I]basename\f[R]-\f[I]target\f[R].dsrl +DSRL schema for the target document type. +Not generated for the \[lq]edit-config\[rq] target. .PP Optional validation of an XML document stored in the file -\fIinstance\fR -proceeds as follows: -.sp -.RS 4 -.ie n \{\ -\h'-04' 1.\h'+01'\c -.\} -.el \{\ -.sp -1 -.IP " 1." 4.2 -.\} -Grammatical and datatype constraints are checked using the RELAX NG schema\&. -.RE -.sp -.RS 4 -.ie n \{\ -\h'-04' 2.\h'+01'\c -.\} -.el \{\ -.sp -1 -.IP " 2." 4.2 -.\} -The DSRL schema is used for adding default values together with ancestor containers to the instance document where necessary\&. -.RE -.sp -.RS 4 -.ie n \{\ -\h'-04' 3.\h'+01'\c -.\} -.el \{\ -.sp -1 -.IP " 3." 4.2 -.\} -Semantic constraints are checked using the Schematron schema\&. The skeleton implementation of -\m[blue]\fBISO Schematron\fR\m[]\&\s-2\u[3]\d\s+2 -by Rick Jelliffe is included in the distribution and used for this purpose\&. -.RE -.PP -Steps -2 -and -3 -are not performed for the "edit\-config" target, or if step -1 -reports any errors\&. -.PP -Option -\fB\-s\fR -may be used together with -\fB\-v\fR -for validating an instance document without generating the schemas\&. This assumes that the schemas are already present in the directory selected by the -\fB\-d\fR -option (current directory by default)\&. In this case, the basename of the schemas must be specified using -\fB\-b\fR\fIbasename\fR -and the input YANG modules need not be given\&. Also, if the DSRL or Schematron schema is missing, the corresponding step is skipped\&. -.PP -The script uses programs from the libxml2 suite \- -\fBxmllint\fR(1) for RELAX NG validation and -\fBxsltproc\fR(1) for performing XSLT transformations\&. Alternatively, -\fBjing\fR(1) can be used for RELAX NG validation (option -\fB\-j\fR)\&. If necessary, the script could be easily modified for use with other RELAX NG validators and/or XSLT1 processors supporting EXSLT\&. -.SH "OPTIONS" -.PP -\fB\-b\fR \fIbasename\fR -.RS 4 -Specifies the basename of files in which the output schemas are stored\&. The default is the concatenation of the names of all input YANG modules connected with the underscore character "_"\&. This option is mandatory if -\fB\-s\fR -is used\&. -.RE -.PP -\fB\-d\fR \fIdir\fR -.RS 4 -Specifies the directory for output files\&. By default they are stored in the current directory\&. -.RE -.PP -\fB\-h\fR -.RS 4 -Displays help screen and exits\&. -.RE -.PP -\fB\-j\fR -.RS 4 -Uses -\fBjing\fR(1) for RELAX NG validation instead of the default -\fBxmllint\fR(1)\&. -.RE -.PP -\fB\-L\fR -.RS 4 -Interpret the -\fIfile\fR -parameter as the name of a file containing a server message\&. In this case, exactly one -\fIfile\fR -parameter must be given\&. -.RE -.PP -\fB\-s\fR -.RS 4 -Performs just validation, without (re)generating the schemas\&. This option is only allowed together with -\fB\-v\fR -and -\fB\-b\fR\fIbasename\fR -must also be specified\&. -.RE -.PP -\fB\-t\fR \fItarget\fR -.RS 4 -Specifies the target XML document type using one of the following strings as explained above: -\fBdata\fR -(default), -\fBconfig\fR, -\fBget\-reply\fR, -\fBget\-data\-reply\fR, -\fBget\-config\-reply\fR, -\fBedit\-config\fR, -\fBrpc\fR, -\fBrpc\-reply\fR -or -\fBnotification\fR\&. -.RE -.PP -\fB\-v\fR \fIinstance\fR -.RS 4 -Validates an instance XML document contained in file -\fIinstance\fR\&. -.RE -.PP -\fB\-x\fR -.RS 4 -Try to translate modules written in unsupported YANG versions\&. If the module doesn\*(Aqt use any constructs introduced after YANG version 1, this may work\&. This option may produce unexpected results\&. Use at own risk\&. -.RE -.PP -\fB\-c\fR -.RS 4 -Use only definitions with status "current" in the YANG module\&. -.RE -.SH "FILES" -.PP -/usr/local/share/yang/xslt/gen\-relaxng\&.xsl -.RS 4 -XSLT stylesheet generating RELAX NG schemas\&. -.RE -.PP -/usr/local/share/yang/xslt/gen\-schematron\&.xsl -.RS 4 -XSLT stylesheet generating Schematron schemas\&. -.RE -.PP -/usr/local/share/yang/xslt/gen\-dsrl\&.xsl -.RS 4 -XSLT stylesheet generating DSRL schemas\&. -.RE -.PP -/usr/local/share/yang/xslt/gen\-common\&.xsl -.RS 4 -Common templates for all three XSLT generators\&. -.RE -.PP -/usr/local/share/yang/xslt/dsrl2xslt\&.xsl -.RS 4 -Translates a subset of DSRL containing only specification of default contents to an XSLT stylesheet\&. -.RE -.PP -/usr/local/share/yang/xslt/svrl2text\&.xsl -.RS 4 -Translates an SVRL report to plain text\&. -.RE -.PP -/usr/local/share/yang/schema/relaxng\-lib\&.rng -.RS 4 -RELAX NG library of common NETCONF elements\&. -.RE -.PP -/usr/local/share/yang/schema/edit\-config\-attributes\&.rng -.RS 4 -RELAX NG definitions of attributes\&. -.RE -.SH "ENVIRONMENT VARIABLES" -.PP -\fBPYANG_XSLT_DIR\fR -.RS 4 -Alternative directory for XSLT stylesheets\&. The default is installation dependent\&. -.RE -.PP -\fBPYANG_RNG_LIBDIR\fR -.RS 4 -Alternative directory for the RELAX NG library\&. The default is installation dependent\&. -.RE -.PP -\fBXSLT_OPTS\fR -.RS 4 -Options to pass to the XSLT processor when generating the DSDL schemas\&. This is mainly useful for debugging\&. -.RE -.SH "EXAMPLES" -.sp -.if n \{\ -.RS 4 -.\} +\f[I]instance\f[R] proceeds as follows: +.IP "1." 3 +Grammatical and datatype constraints are checked using the RELAX NG +schema. +.IP "2." 3 +The DSRL schema is used for adding default values together with ancestor +containers to the instance document where necessary. +.IP "3." 3 +Semantic constraints are checked using the Schematron schema. +The skeleton implementation of \f[B]ISO Schematron\f[R] by Rick Jelliffe +is included in the distribution and used for this purpose. +.PP +Steps 3 and 3 are not performed for the \[lq]edit-config\[rq] target, or +if step 1 reports any errors. +.PP +Option \f[B]-s\f[R] may be used together with \f[B]-v\f[R] for +validating an instance document without generating the schemas. +This assumes that the schemas are already present in the directory +selected by the \f[B]-d\f[R] option (current directory by default). +In this case, the basename of the schemas must be specified using +\f[B]-b\f[R] \f[I]basename\f[R] and the input YANG modules need not be +given. +Also, if the DSRL or Schematron schema is missing, the corresponding +step is skipped. +.PP +The script uses programs from the libxml2 suite - \f[B]xmllint\f[R](1) +for RELAX NG validation and \f[B]xsltproc\f[R](1) for performing XSLT +transformations. +Alternatively, \f[B]jing\f[R](1) can be used for RELAX NG validation +(option \f[B]-j\f[R]). +If necessary, the script could be easily modified for use with other +RELAX NG validators and/or XSLT1 processors supporting EXSLT. +.SH OPTIONS +.TP +\f[B]-b\f[R] \f[I]basename\f[R] +Specifies the basename of files in which the output schemas are stored. +The default is the concatenation of the names of all input YANG modules +connected with the underscore character \[dq]_\[dq]. +This option is mandatory if \f[B]-s\f[R] is used. +.TP +\f[B]-d\f[R] \f[I]dir\f[R] +Specifies the directory for output files. +By default they are stored in the current directory. +.TP +\f[B]-h\f[R] +Displays help screen and exits. +.TP +\f[B]-j\f[R] +Uses \f[B]jing\f[R](1) for RELAX NG validation instead of the default +\f[B]xmllint\f[R](1). +.TP +\f[B]-L\f[R] +Interpret the \f[I]file\f[R] parameter as the name of a file containing +a server message. +In this case, exactly one \f[I]file\f[R] parameter must be given. +.TP +\f[B]-s\f[R] +Performs just validation, without (re)generating the schemas. +This option is only allowed together with \f[B]-v\f[R] and \f[B]-b\f[R] +\f[I]basename\f[R] must also be specified. +.TP +\f[B]-t\f[R] \f[I]target\f[R] +Specifies the target XML document type using one of the following +strings as explained above: \f[B]data\f[R] (default), \f[B]config\f[R], +\f[B]get-reply\f[R], \f[B]get-data-reply\f[R], +\f[B]get-config-reply\f[R], \f[B]edit-config\f[R], \f[B]rpc\f[R], +\f[B]rpc-reply\f[R] or \f[B]notification\f[R]. +.TP +\f[B]-v\f[R] \f[I]instance\f[R] +Validates an instance XML document contained in file \f[I]instance\f[R]. +.TP +\f[B]-x\f[R] +Try to translate modules written in unsupported YANG versions. +If the module doesn\[cq]t use any constructs introduced after YANG +version 1, this may work. +This option may produce unexpected results. +Use at own risk. +.TP +\f[B]-c\f[R] +Use only definitions with status \[lq]current\[rq] in the YANG module. +.SH FILES +.TP +/usr/local/share/yang/xslt/gen-relaxng.xsl +XSLT stylesheet generating RELAX NG schemas. +.TP +/usr/local/share/yang/xslt/gen-schematron.xsl +XSLT stylesheet generating DSRL schemas. +.TP +/usr/local/share/yang/xslt/gen-common.xsl +Common templates for all three XSLT generators. +.TP +/usr/local/share/yang/xslt/dsrl2xslt.xsl +Translates a subset of DSRL containing only specification of default +contents to an XSLT stylesheet. +.TP +/usr/local/share/yang/xslt/svrl2text.xsl +Translates an SVRL report to plain text. +.TP +/usr/local/share/yang/schema/relaxng-lib.rng +RELAX NG library of common NETCONF elements. +.TP +/usr/local/share/yang/schema/edit-config-attributes.rng +RELAX NG definitions of attributes. +.SH ENVIRONMENT VARIABLES +.TP +\f[B]PYANG_XSLT_DIR\f[R] +Alternative directory for XSLT stylesheets. +The default is installation dependent. +.TP +\f[B]PYANG_RNG_LIBDIR\f[R] +Alternative directory for the RELAX NG library. +The default is installation dependent. +.TP +\f[B]XSLT_OPTS\f[R] +Options to pass to the XSLT processor when generating the DSDL schemas. +This is mainly useful for debugging. +.SH EXAMPLES +.IP .nf -$ yang2dsdl \-v dhcp\-data\&.xml dhcp\&.yang +\f[C] +$ yang2dsdl -v dhcp-data.xml dhcp.yang +\f[R] .fi -.if n \{\ -.RE -.\} .PP -This command generates the DSDL schemas for the datastore contents (default -\fIdata\fR -target) as defined by the -dhcp\&.yang -module and validates an instance document stored in the -dhcp\-data\&.xml -file\&. -.sp -.if n \{\ -.RS 4 -.\} +This command generates the DSDL schemas for the datastore contents +(default \f[I]data\f[R] target) as defined by dhcp.yang module and +validates an instance document stored in the dhcp-data.xml file. +.IP .nf -$ yang2dsdl \-t rpc rpc\-rock\&.yang +\f[C] +$ yang2dsdl -t rpc rpc-rock.yang +\f[R] .fi -.if n \{\ -.RE -.\} .PP -This command generates DSDL schemas for the choice of input parts (requests) of all RPC operations defined in the module -rpc\-rock\&.yang\&. -.SH "DIAGNOSTICS" -.PP -\fByang2dsdl\fR -return codes have the following meaning: +This command generates DSDL schemas for the choice of input parts +(requests) of all RPC operations defined in the module rpc-rock.yang. +.SH DIAGNOSTICS .PP +\f[B]yang2dsdl\f[R] return codes have the following meaning: +.TP 0 -.RS 4 No error (normal termination) -.RE -.PP +.TP 1 -.RS 4 Error in input parameters -.RE -.PP +.TP 2 -.RS 4 Error in DSDL schema generation -.RE -.PP +.TP 3 -.RS 4 Instance validation failed -.RE -.SH "BUGS" -.sp -.RS 4 -.ie n \{\ -\h'-04' 1.\h'+01'\c -.\} -.el \{\ -.sp -1 -.IP " 1." 4.2 -.\} -The logic of command\-line arguments may not be able to distinguish replies to different RPC requests, for example if the replies have the same top\-level element\&. -.RE -.SH "SEE ALSO" -.PP -\fBpyang\fR(1), -\fBxsltproc\fR(1), -\fBxmllint\fR(1), -\m[blue]\fBRFC\ \&6110\fR\m[]\&\s-2\u[1]\d\s+2, -\m[blue]\fBDSDL\fR\m[]\&\s-2\u[4]\d\s+2, -\m[blue]\fBRELAX NG\fR\m[]\&\s-2\u[5]\d\s+2, -\m[blue]\fBISO Schematron\fR\m[]\&\s-2\u[3]\d\s+2\&. -.SH "AUTHOR" -.PP -\fBLadislav Lhotka\fR <\&lhotka@nic\&.cz\&> -.br -CZ\&.NIC -.RS 4 -.RE -.SH "NOTES" -.IP " 1." 4 -RFC\ \&6110 -.RS 4 -\%http://tools.ietf.org/html/rfc6110 -.RE -.IP " 2." 4 -RFC\ \&7952 -.RS 4 -\%http://tools.ietf.org/html/rfc7952 -.RE -.IP " 3." 4 -ISO Schematron -.RS 4 -\%http://www.schematron.com -.RE -.IP " 4." 4 -DSDL -.RS 4 -\%http://www.dsdl.org/ -.RE -.IP " 5." 4 -RELAX NG -.RS 4 -\%http://www.relaxng.org/ -.RE +.SH BUGS +.IP "1." 3 +The logic of command-line arguments may not be able to distinguish +replies to different RPC requests, for example if the replies have the +same top-level element. +.SH SEE ALSO +.PP +\f[B]pyang\f[R](1), \f[B]xsltproc\f[R](1), \f[B]xmllint\f[R](1), +\f[B]RFC 61110\f[R]. +.SH AUTHOR +.PP +\f[B]Ladislav Lhotka\f[R] +.PD 0 +.P +.PD +CZ.NIC diff --git a/pyang/__init__.py b/pyang/__init__.py index cfee11cf..74254465 100644 --- a/pyang/__init__.py +++ b/pyang/__init__.py @@ -1,4 +1,4 @@ """The pyang library for parsing, validating, and converting YANG modules""" -__version__ = '2.5.3' -__date__ = '2022-03-30' +__version__ = '2.6.0' +__date__ = '2023-11-03'