yanglint DOC update examples
Fixes #1873
diff --git a/tools/lint/examples/README.md b/tools/lint/examples/README.md
index 4b1d972..604591c 100644
--- a/tools/lint/examples/README.md
+++ b/tools/lint/examples/README.md
@@ -1,5 +1,3 @@
-YANGLINT IS NOT YET PREPARED FOR USE, EXAMPLES MAY NOT WORK YET!!!
-
# YANGLINT - Interactive Mode Examples
This text provides several use-case of the `yanglint(1)` interactive
@@ -16,15 +14,16 @@
> help
Available commands:
help Display commands description
- add Add a new model
- print Print model
+ add Add a new module from a specific file
+ load Load a new schema from the searchdirs
+ print Print a module
data Load, validate and optionally print instance data
- xpath Get data nodes satisfying an XPath expression
- list List all the loaded models
- feature Print/enable/disable all/specific features of models
- searchpath Set the search path for models
- clear Clear the context - remove all the loaded models
+ list List all the loaded modules
+ feature Print all features of module(s) with their state
+ searchpath Print/set the search path(s) for schemas
+ clear Clear the context - remove all the loaded modules
verb Change verbosity
+ debug Display specific debug message groups
quit Quit the program
? Display commands description
exit Quit the program
@@ -33,7 +32,12 @@
combination with the command name you are interested in:
```
> help searchpath
-searchpath <model-dir-path>
+Usage: searchpath [--clear] [<modules-dir-path> ...]
+ Set paths of directories where to search for imports and
+ includes of the schema modules. The current working directory
+ and the path of the module being added is used implicitly.
+ The 'load' command uses these paths to search even for the
+ schema modules to be loaded.
```
The input files referred in this document are available together with this
@@ -56,11 +60,13 @@
Output:
```
-List of the loaded models (mod-set-id 5):
- ietf-inet-types@2013-07-15
- ietf-yang-types@2013-07-15
- ietf-yang-library@2015-07-03
- module1
+List of the loaded models:
+ i ietf-yang-metadata@2016-08-05
+ I yang@2022-06-16
+ i ietf-inet-types@2013-07-15
+ i ietf-yang-types@2013-07-15
+ I ietf-yang-schema-mount@2019-01-14
+ I module1
```
Command and its output:
@@ -68,7 +74,7 @@
```
> add module1b.yang
libyang[0]: Two different modules ("module1" and "module1b") have the same namespace "urn:yanglint:module".
-libyang[0]: Module "module1b" parsing failed.
+libyang[0]: Parsing module "module1b" failed.
```
## Yang Data Model Validation
@@ -98,8 +104,8 @@
```
> add module2.yin
-libyang[0]: Missing argument "name" to keyword "type".
-libyang[0]: Module "module1" parsing failed.
+libyang[0]: Unexpected attribute "value" of "type" element. (path: Line number 8.)
+libyang[0]: Parsing module "module2" failed.
```
Similarly, there is a typo in `module2.yang`.
@@ -119,15 +125,11 @@
```
> add module3.yang
-libyang[0]: Schema node "a" not found (../c/a).
-libyang[0]: Path is related to the previous error message. (path: /module3:m)
-libyang[0]: Module "module3" parsing failed.
+libyang[1]: Schema node "a" for parent "/module3:c" not found; in expr "../c/a" with context node "/module3:m".
```
-Note that libyang does not provide line numbers of the error. Instead it tries to
-print the path to the related node. in some cases (as this one) it is not able
-to print the path immediately so the path (to the node `m` which refers node which
-does not exist) is printed in the second message.
+Note that libyang prints only a warning in this case because it is not
+specified that XPath expressions must refer to existing nodes.
## Data Validation
@@ -155,21 +157,17 @@
data (with at least all the mandatory nodes as required by the loaded schemas),
but without the status data. More examples of different data types will follow.
-To handle unknown data as error, use strict mode (`-s` option).
-
Command and its output:
```
-> data -t config -s datastore.xml
-libyang[0]: Unknown element "interfaces". (path: /)
-Failed to parse data.
+> data -t config datastore.xml
+libyang[0]: No module with namespace "urn:ietf:params:xml:ns:yang:ietf-interfaces" in the context. (path: Line number 20.)
+YANGLINT[E]: Failed to parse input data file "datastore.xml".
```
Note that in case of working with complete datastore including the status data
(no `-t` option is specified), `yanglint(1)` has to add status data from its
-internal `ietf-yang-library` module. Using the `-s` option in this case forces
-validation in time of parsing the input file so it is expected to include also
-the mandatory status data from the `ietf-yang-library` module.
+internal `ietf-yang-library` module.
**RPC and RPC-reply**
@@ -188,19 +186,19 @@
> data -t rpc rpc.xml
```
-Reply to this RPC can be validated too, but it must be specified, to which
-RPC it is a reply to, because it is not included in the reply itself.
+Reply to this RPC can be validated too, but it must be nested in the original
+RPC element.
Command and its output:
```
-> data -t rpcreply rpc-reply.xml rpc.xml
+> data -t reply ../tools/lint/examples/rpc-reply.xml
```
**action and action-reply**
Actions are validated the same way as RPCs except you need to be careful
-about the input file structure.
+about the input file structure. No NETCONF-specific envelopes are expected.
Preparation
@@ -266,7 +264,7 @@
Command and its output:
```
-> data -t config -s datastore.xml
+> data -t config datastore.xml
```
**Different data content types**
@@ -288,8 +286,8 @@
```
> data -t edit config-missing-key.xml
-libyang[0]: Invalid (mixed names) opening (nam) and closing (name) element tags. (path: /nacm/groups/group/nam)
-Failed to parse data.
+libyang[0]: Node "nam" not found as a child of "group" node. (path: Schema location "/ietf-netconf-acm:nacm/groups/group", data location "/ietf-netconf-acm:group", line number 19.)
+YANGLINT[E]: Failed to parse input data file "config-missing-key.xml".
```
**State information in edit-config XML**
@@ -298,8 +296,8 @@
```
> data -t edit config-unknown-element.xml
-libyang[0]: Unknown element "denied-operations". (path: /ietf-netconf-acm:nacm/denied-operations)
-Failed to parse data.
+libyang[0]: Unexpected data state node "denied-operations" found. (path: Schema location "/ietf-netconf-acm:nacm/denied-operations", data location "/ietf-netconf-acm:nacm", line number 24.)
+YANGLINT[E]: Failed to parse input data file "config-unknown-element.xml".
```
**Missing required element in NETCONF data**
@@ -308,8 +306,8 @@
```
> data data-missing-key.xml
-libyang[0]: Missing required element "name" in "rule". (path: /ietf-netconf-acm:nacm/rule-list[name='almighty']/rule)
-Failed to parse data.
+libyang[0]: List instance is missing its key "name". (path: Schema location "/ietf-netconf-acm:nacm/rule-list/rule", data location "/ietf-netconf-acm:rule", line number 10.)
+YANGLINT[E]: Failed to parse input data file "data-missing-key.xml".
```
**Malformed XML**
@@ -318,16 +316,16 @@
```
> data data-malformed-xml.xml
-libyang[0]: Invalid (mixed names) opening (nam) and closing (rule) element tags. (path: /nacm/rule-list/rule/nam)
-Failed to parse data.
+libyang[0]: Node "nam" not found as a child of "rule" node. (path: Schema location "/ietf-netconf-acm:nacm/rule-list/rule", data location "/ietf-netconf-acm:rule", line number 8.)
+YANGLINT[E]: Failed to parse input data file "data-malformed-xml.xml".
```
Command and its output:
```
> data data-malformed-xml2.xml
-libyang[0]: Invalid (mixed names) opening (module-name) and closing (name) element tags. (path: /nacm/rule-list/rule/name/module-name)
-Failed to parse data.
+libyang[0]: Child element "module-name" inside a terminal node "name" found. (path: Schema location "/ietf-netconf-acm:nacm/rule-list/rule/name", data location "/ietf-netconf-acm:name", line number 7.)
+YANGLINT[E]: Failed to parse input data file "data-malformed-xml2.xml".
```
**Bad value**
@@ -336,8 +334,8 @@
```
> data data-out-of-range-value.xml
-libyang[0]: Invalid value "-1" in "denied-operations" element. (path: /ietf-netconf-acm:nacm/denied-operations)
-Failed to parse data.
+libyang[0]: Value "-1" is out of type uint32 min/max bounds. (path: Schema location "/ietf-netconf-acm:nacm/denied-operations", data location "/ietf-netconf-acm:nacm", line number 24.)
+YANGLINT[E]: Failed to parse input data file "data-out-of-range-value.xml".
```
## Validation of "when" Statement in Data
@@ -355,12 +353,10 @@
```
> data data-acm.xml
+libyang[0]: When condition "../denied-operations > 0" not satisfied. (path: Schema location "/ietf-netconf-acm-when:nacm/denied-data-writes", data location "/ietf-netconf-acm-when:nacm/denied-data-writes".)
+YANGLINT[E]: Failed to parse input data file "data-acm.xml".
```
-The command succeeds. It is because `yanglint(1)` (via `libyang`) performs
-autodeletion - the not satisfied `when` condition in `denied-data-writes`
-causes its automatic (silent) deletion.
-
## Printing a Data Model
Preparation:
@@ -377,95 +373,35 @@
```
> print ietf-netconf-acm
module: ietf-netconf-acm
- +--rw nacm
- +--rw enable-nacm? boolean <true>
- +--rw read-default? action-type <permit>
- +--rw write-default? action-type <deny>
- +--rw exec-default? action-type <permit>
- +--rw enable-external-groups? boolean <true>
- +--ro denied-operations ietf-yang-types:zero-based-counter32
- +--ro denied-data-writes ietf-yang-types:zero-based-counter32
- +--ro denied-notifications ietf-yang-types:zero-based-counter32
- +--rw groups
- | +--rw group* [name]
- | +--rw name group-name-type
- | +--rw user-name* user-name-type
- +--rw rule-list* [name]
- +--rw name string
- +--rw group* union
- +--rw rule* [name]
- +--rw name string
- +--rw module-name? union <*>
- +--rw (rule-type)?
- | +--:(protocol-operation)
- | | +--rw rpc-name? union
- | +--:(notification)
- | | +--rw notification-name? union
- | +--:(data-node)
- | +--rw path node-instance-identifier
- +--rw access-operations? union <*>
- +--rw action action-type
- +--rw comment? string
->
-```
-
-**Obtain information about model**
-
-Command and its output:
-
-```
-> print -f info ietf-netconf-acm
-Module: ietf-netconf-acm
-Namespace: urn:ietf:params:xml:ns:yang:ietf-netconf-acm
-Prefix: nacm
-Desc: NETCONF Access Control Model.
-
- Copyright (c) 2012 IETF Trust and the persons identified as
- authors of the code. All rights reserved.
-
- Redistribution and use in source and binary forms, with or
- without modification, is permitted pursuant to, and subject
- to the license terms contained in, the Simplified BSD
- License set forth in Section 4.c of the IETF Trust's
- Legal Provisions Relating to IETF Documents
- (http://trustee.ietf.org/license-info).
-
- This version of this YANG module is part of RFC 6536; see
- the RFC itself for full legal notices.
-Reference:
-Org: IETF NETCONF (Network Configuration) Working Group
-Contact: WG Web: <http://tools.ietf.org/wg/netconf/>
- WG List: <mailto:netconf@ietf.org>
-
- WG Chair: Mehmet Ersue
- <mailto:mehmet.ersue@nsn.com>
-
- WG Chair: Bert Wijnen
- <mailto:bertietf@bwijnen.net>
-
- Editor: Andy Bierman
- <mailto:andy@yumaworks.com>
-
- Editor: Martin Bjorklund
- <mailto:mbj@tail-f.com>
-YANG ver: 1.0
-Deviated: no
-Implement: yes
-URI:
-Revisions: 2012-02-22
-Includes:
-Imports: yang:ietf-yang-types
-Typedefs: user-name-type
- matchall-string-type
- access-operations-type
- group-name-type
- action-type
- node-instance-identifier
-Idents:
-Features:
-Augments:
-Deviation:
-Data: container "nacm"
+ +--rw nacm
+ +--rw enable-nacm? boolean
+ +--rw read-default? action-type
+ +--rw write-default? action-type
+ +--rw exec-default? action-type
+ +--rw enable-external-groups? boolean
+ +--ro denied-operations yang:zero-based-counter32
+ +--ro denied-data-writes yang:zero-based-counter32
+ +--ro denied-notifications yang:zero-based-counter32
+ +--rw groups
+ | +--rw group* [name]
+ | +--rw name group-name-type
+ | +--rw user-name* user-name-type
+ +--rw rule-list* [name]
+ +--rw name string
+ +--rw group* union
+ +--rw rule* [name]
+ +--rw name string
+ +--rw module-name? union
+ +--rw (rule-type)?
+ | +--:(protocol-operation)
+ | | +--rw rpc-name? union
+ | +--:(notification)
+ | | +--rw notification-name? union
+ | +--:(data-node)
+ | +--rw path node-instance-identifier
+ +--rw access-operations? union
+ +--rw action action-type
+ +--rw comment? string
```
**Print information about specific model part**
@@ -473,58 +409,19 @@
Command and its output:
```
-> print -f info -t /ietf-netconf-acm:nacm/ietf-netconf-acm:enable-nacm ietf-netconf-ac
-Leaf: enable-nacm
-Module: ietf-netconf-acm
-Desc: Enables or disables all NETCONF access control
- enforcement. If 'true', then enforcement
- is enabled. If 'false', then enforcement
- is disabled.
-Reference:
-Config: read-write
-Status: current
-Mandatory: no
-Type: boolean
-Units:
-Default: true
-If-feats:
-When:
-Must:
-NACM: default-deny-all
-```
-
-## Query using NETCONF data
-
-Preparation:
-
-```
-> clear
-> add ietf-netconf-acm.yang
-```
-
-**Print all `user-name` elements that occure in data**
-
-Command and its output:
-
-```
-> xpath -e //ietf-netconf-acm:user-name data-acm.xml
-Result:
- Leaflist "user-name" (val: smith)
- Leaflist "user-name" (val: smith)
- Leaflist "user-name" (val: doe)
-
-```
-
-**Print all data that satisfies condition**
-
-Command and its output:
-
-```
-> xpath -e //ietf-netconf-acm:user-name[text()="smith"] data-acm.xml
-Result:
- Leaflist "user-name" (val: smith)
- Leaflist "user-name" (val: smith)
-
+> print -f info -P /ietf-netconf-acm:nacm/ietf-netconf-acm:enable-nacm ietf-netconf-acm
+leaf enable-nacm {
+ ietf-netconf-acm:default-deny-all;
+ type boolean;
+ default "true";
+ config true;
+ status current;
+ description
+ "Enables or disables all NETCONF access control
+ enforcement. If 'true', then enforcement
+ is enabled. If 'false', then enforcement
+ is disabled.";
+}
```
## Usage of `feature` in Yang
@@ -534,7 +431,7 @@
```
> clear
> add ietf-interfaces.yang
-> add ietf-ip.yang
+> add ietf-ip.yang -F ietf-ip:*
> add iana-if-type.yang
```
@@ -542,7 +439,10 @@
Command and its output:
```
-> feature -e * ietf-ip
+> feature ietf-ip
+ietf-ip features:
+ ipv4-non-contiguous-netmasks (on)
+ ipv6-privacy-autoconf (on)
> data -f json -t config data-ip.xml
{
"ietf-interfaces:interfaces": {
@@ -569,4 +469,3 @@
}
}
```
-
diff --git a/tools/lint/examples/action-reply.xml b/tools/lint/examples/action-reply.xml
index 5a4788e..e6fc284 100644
--- a/tools/lint/examples/action-reply.xml
+++ b/tools/lint/examples/action-reply.xml
@@ -1 +1,8 @@
-<leaf3 xmlns="urn:module4">some_output</leaf3>
+<cont1 xmlns="urn:module4">
+ <list>
+ <leaf1>key_val</leaf1>
+ <act>
+ <leaf3>some_output</leaf3>
+ </act>
+ </list>
+</cont1>
diff --git a/tools/lint/examples/action.xml b/tools/lint/examples/action.xml
index b0bd411..661fecf 100644
--- a/tools/lint/examples/action.xml
+++ b/tools/lint/examples/action.xml
@@ -1,10 +1,8 @@
-<action xmlns="urn:ietf:params:xml:ns:yang:1">
- <cont1 xmlns="urn:module4">
- <list>
- <leaf1>key_val</leaf1>
- <act>
- <leaf2>some_input</leaf2>
- </act>
- </list>
- </cont1>
-</action>
+<cont1 xmlns="urn:module4">
+ <list>
+ <leaf1>key_val</leaf1>
+ <act>
+ <leaf2>some_input</leaf2>
+ </act>
+ </list>
+</cont1>
diff --git a/tools/lint/examples/config-missing-key.xml b/tools/lint/examples/config-missing-key.xml
index 16854d5..c30c2b0 100644
--- a/tools/lint/examples/config-missing-key.xml
+++ b/tools/lint/examples/config-missing-key.xml
@@ -1,8 +1,8 @@
-<nacm xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-acm" xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0">
+<nacm xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-acm">
<rule-list>
<name>almighty</name>
<group>almighty</group>
- <group nc:operation="create">test</group>
+ <group>test</group>
<rule>
<name>almighty</name>
<module-name>*</module-name>
diff --git a/tools/lint/examples/config-unknown-element.xml b/tools/lint/examples/config-unknown-element.xml
index 87c79ee..66ae880 100644
--- a/tools/lint/examples/config-unknown-element.xml
+++ b/tools/lint/examples/config-unknown-element.xml
@@ -1,8 +1,8 @@
-<nacm xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-acm" xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0">
+<nacm xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-acm">
<rule-list>
<name>almighty</name>
<group>almighty</group>
- <group nc:operation="create">test</group>
+ <group>test</group>
<rule>
<name>almighty</name>
<module-name>*</module-name>
diff --git a/tools/lint/examples/data-acm.xml b/tools/lint/examples/data-acm.xml
index 87c79ee..66ae880 100644
--- a/tools/lint/examples/data-acm.xml
+++ b/tools/lint/examples/data-acm.xml
@@ -1,8 +1,8 @@
-<nacm xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-acm" xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0">
+<nacm xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-acm">
<rule-list>
<name>almighty</name>
<group>almighty</group>
- <group nc:operation="create">test</group>
+ <group>test</group>
<rule>
<name>almighty</name>
<module-name>*</module-name>
diff --git a/tools/lint/examples/data-malformed-xml.xml b/tools/lint/examples/data-malformed-xml.xml
index fd800ad..908d79b 100644
--- a/tools/lint/examples/data-malformed-xml.xml
+++ b/tools/lint/examples/data-malformed-xml.xml
@@ -1,8 +1,8 @@
-<nacm xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-acm" xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0">
+<nacm xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-acm">
<rule-list>
<name>almighty</name>
<group>almighty</group>
- <group nc:operation="create">test</group>
+ <group>test</group>
<rule>
<nam>almighty
<module-name>*</module-name>
diff --git a/tools/lint/examples/data-malformed-xml2.xml b/tools/lint/examples/data-malformed-xml2.xml
index 1837264..8d0e5f4 100644
--- a/tools/lint/examples/data-malformed-xml2.xml
+++ b/tools/lint/examples/data-malformed-xml2.xml
@@ -1,8 +1,8 @@
-<nacm xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-acm" xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0">
+<nacm xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-acm">
<rule-list>
<name>almighty</name>
<group>almighty</group>
- <group nc:operation="create">test</group>
+ <group>test</group>
<rule>
<name>almighty<module-name></name> *</module-name>
<access-operations>*</access-operations>
diff --git a/tools/lint/examples/data-missing-key.xml b/tools/lint/examples/data-missing-key.xml
index d3ccd53..2e9684d 100644
--- a/tools/lint/examples/data-missing-key.xml
+++ b/tools/lint/examples/data-missing-key.xml
@@ -1,8 +1,8 @@
-<nacm xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-acm" xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0">
+<nacm xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-acm">
<rule-list>
<name>almighty</name>
<group>almighty</group>
- <group nc:operation="create">test</group>
+ <group>test</group>
<rule>
<module-name>*</module-name>
<access-operations>*</access-operations>
diff --git a/tools/lint/examples/data-out-of-range-value.xml b/tools/lint/examples/data-out-of-range-value.xml
index 83a0d65..2af5ba9 100644
--- a/tools/lint/examples/data-out-of-range-value.xml
+++ b/tools/lint/examples/data-out-of-range-value.xml
@@ -1,8 +1,8 @@
-<nacm xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-acm" xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0">
+<nacm xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-acm">
<rule-list>
<name>almighty</name>
<group>almighty</group>
- <group nc:operation="create">test</group>
+ <group>test</group>
<rule>
<name>almighty</name>
<module-name>*</module-name>
diff --git a/tools/lint/examples/ietf-netconf-acm-when.yang b/tools/lint/examples/ietf-netconf-acm-when.yang
index df8f801..902fcbf 100644
--- a/tools/lint/examples/ietf-netconf-acm-when.yang
+++ b/tools/lint/examples/ietf-netconf-acm-when.yang
@@ -1,4 +1,4 @@
-module ietf-netconf-acm-when2 {
+module ietf-netconf-acm-when {
namespace "urn:ietf:params:xml:ns:yang:ietf-netconf-acm";
prefix nacm;
diff --git a/tools/lint/examples/rpc-reply.xml b/tools/lint/examples/rpc-reply.xml
index 20469dd..54aab3e 100644
--- a/tools/lint/examples/rpc-reply.xml
+++ b/tools/lint/examples/rpc-reply.xml
@@ -1,3 +1,5 @@
-<cont2 xmlns="urn:module4">
- <leaf6/>
-</cont2>
+<rpc xmlns="urn:module4">
+ <cont2>
+ <leaf6/>
+ </cont2>
+</rpc>