module yangdiff {
yang-version 1;
namespace "http://netconfcentral.org/ns/yangdiff";
prefix "ydi";
import yuma-types {
prefix "nt";
}
import yuma-ncx {
prefix "ncx";
}
import yuma-app-common {
prefix "ncxapp";
}
organization "Netconf Central";
contact
"Andy Bierman <andy at netconfcentral.org>";
description
"yangdiff compares the semantics and syntax between
two revisions of the same YANG module. The
conceptual data model is compared, not the
individual files.
For example, unless statement order is significant,
changing the order is not considered a change, and
is not reported. Reformatted test (whitespace changes)
are also not reported.
If a data type definition is changed in form,
but not content, then a 'modify type' message
will be generated, but no additional sub-fields
will be reported.
INPUT FILES
To compare one module, use the 'old' and 'new'
parameters to specify YANG module files,
each with a filespec string ending with the '.yang'
file extension. The filespecs must represent
different files. If the 'old' parameter represents
a directory, then this directory will be searched
for the 'new' filename.
To compare all the modules in a subtree, use the
'old' and 'new' parameters to specify a directory
to be searched for YANG modules to be processed.
In this mode, each new module is compared to
a corresponding file within the 'old' subtree.
Also, dependency and include files
will be kept separate, for each subtree.
Unless the 'help' or 'version' parameters is entered,
the 'old' and 'new' parameters must be present.
SEARCH PATH
When a module name is entered as input, or when a
module or submodule name is specified in an import or include
statement within the file, the following search algorithm
is used to find the file:
1) if the parameter for the file that generated the
search request represents a subtree, search that
subtree first.
2) file is in the current directory
3) YANG_MODPATH environment var (or set by modpath parameter)
4) $HOME/modules directory
5) $YANG_HOME/modules directory
6) $YANG_INSTALL/modules directory OR
default install module location, '/usr/share/yang/modules'
By default, the entire directory tree for all locations
(except step 1) will be searched, not just the specified
directory. The 'subdirs' parameter can be used to
prevent sub-directories from being searched.
Any directory name beginning with a dot character '.'
will be skipped. Also, any directory named 'CVS' will
be skipped in directory searches.
OUTPUT MODES
By default, any comparison output will be sent to STDOUT.
The 'output' parameter can be used to specify the
full filespec of the output file, or a
complete directory specification to be combined
with the default filename (yangdiff.log).
ERROR LOGGING
By default, warnings and errors are sent to STDOUT.
A log file can be specified instead with the 'log' parameter.
Existing log files can be reused with the 'logappend'
parameter, otherwise log files are overwritten.
The logging level can be controlled with the 'log-level'
parameter. The default log level is 'info'. The
log-levels are additive:
off: suppress all errors (not recommended!)
A program return code of '1' indicates some error.
error: print errors
warn: print warnings
info: print generally interesting trace info
debug: print general debugging trace info
debug2: print verbose debugging trace info
";
revision "2009-04-10" {
description
"Moved common parameters to ncx-app-common";
}
revision "2008-08-17" {
description "Initial version";
}
typedef DiffType {
type enumeration {
enum "terse" {
value 0;
}
enum "normal" {
value 1;
}
enum "revision" {
value 2;
}
}
default "normal";
description "Type of comparison output requested.";
}
container yangdiff {
description
"CLI Parameter Set for the YANG Module Compare Application.";
leaf difftype {
type DiffType;
description
"The type of comparison output requested.
Allowed values are 'terse', 'normal', and 'revision'.
The basic format is:
[add/delete/modify] field-name [field-value]
The 'terse' option will include the names
of the top-level fields that are different.
A foo --> Added foo in new revision
D foo --> Deleted foo in new revision
M foo --> Modified foo in new revision (value too long)
M foo from '0' to '1' --> Modified foo in new revision
The 'normal' option will also include any changes
for any nested fields or objects. This is the default
option.
The 'revision' option will generate the differences report
in YANG revision-stmt format. For example:
revision <todays-date> {
description
"
- Added import baxtypes
- Changed contact to 'support@acme.com'
- Modified container myobjects
- Added list first-list";
} ";
}
leaf header {
type boolean;
default "true";
description
"If false, the header clauses will be skipped, and any
differences between the module headers will not be reported.
Only object definitions will be compared.
If true, then header clauses will be compared,
along will all the object definitions.";
}
leaf new {
type nt:NcModuleSpec;
description
"If this parameter indicates a filename, then it
represents the YANG source module name
to compare as the newer of the two revisions.
If this parameter indicates a directory
(and the 'old' parameter indicates a filename),
then it will be used to to search for a
file with the same name as the 'new' parameter.
If the 'old' parameter identifies a directory
as well (and the 'subdirs' parameter is 'false'),
then the modules within the 'new' directory will be
compared to files with the same name in the 'old'
directory. If the 'subdirs' parameter is 'true',
then all sub-directories within the 'src'
directory will also be checked.
If this string begins with a '~' character,
then a username is expected to follow or
a directory separator character. If it begins
with a '$' character, then an environment variable
name is expected to follow.
~/some/path ==> <my-home-dir>/some/path
~fred/some/path ==> <fred-home-dir>/some/path
$workdir/some/path ==> <workdir-env-var>/some/path
This parameter must be present unless the 'help'
or 'version' parameters are used.";
}
leaf old {
type nt:NcModuleSpec;
description
"The older of the two revisions to compare.
If this parameter indicates a filename, then it
represents the YANG source module name
to compare as the older of the two revisions.
If this parameter indicates a directory,
then it will be used to to search for a
file with the same name as identified by
the 'new' parameter.
If this string begins with a '~' character,
then a username is expected to follow or
a directory separator character. If it begins
with a '$' character, then an environment variable
name is expected to follow.
~/some/path ==> <my-home-dir>/some/path
~fred/some/path ==> <fred-home-dir>/some/path
$workdir/some/path ==> <workdir-env-var>/some/path
This parameter must be present unless the 'help'
or 'version' parameters are used.";
}
leaf output {
type string;
description
"Output directory or file name to use.
The default is STDOUT if none is specified.
If this parameter represents an existing directory,
then the default comparison output file (yangdiff.log)
will be generated in the specified directory.
If this parameter represents a file name,
then all comparison output will be directed
to the specified file. If the file already exists,
it will be overwritten.
If this string begins with a '~' character,
then a username is expected to follow or
a directory separator character. If it begins
with a '$' character, then an environment variable
name is expected to follow.
~/some/path ==> <my-home-dir>/some/path
~fred/some/path ==> <fred-home-dir>/some/path
$workdir/some/path ==> <workdir-env-var>/some/path";
}
uses ncxapp:NcxAppCommon;
uses ncxapp:SubdirsParm;
ncx:cli;
} // container yangdiff
} // module yangdiff
