module yangdiff-pro {

    yang-version 1.1;

    namespace
      "http://yumaworks.com/ns/yangdiff-pro";

    prefix ydipro;

    import yuma-types {
      prefix nt;
    }
    import yuma-ncx {
      prefix ncx;
    }
    import yuma-app-common {
      prefix ncxapp;
    }
    import yumaworks-app-common {
      prefix ywapp;
    }

    organization "YumaWorks, Inc.";

    contact
      "Support <support at yumaworks.com>";

    description
      "yangdiff-pro 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-pro.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

     Copyright (c) 2008 - 2011 YumaWorks, Inc. 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 BSD 3-Clause License
     http://opensource.org/licenses/BSD-3-Clause";

    revision "2011-10-06" {
      description "Add --home parameter,";
    }

    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-pro {
      ncx:cli;
      description
        "CLI Parameter Set for the YANG Module Compare Application.";
      choice config-choice {
        leaf config {
          type string;
          description
            "The name of the configuration file to use.
Any parameter except this one can be set in the config file.
The default config file will be not be checked if this
parameter is present.";
        }
        leaf no-config {
          type empty;
          description
            "Do not the default .conf file even if it exists.";
        }
      }  // choice config-choice

      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 help {
        type empty;
        description
          "Print program help file and exit.";
      }

      choice help-mode {
        default "normal";
        leaf brief {
          type empty;
          description "Show brief help text";
        }
        leaf full {
          type empty;
          description "Show full help text";
        }
        leaf normal {
          type empty;
          description
            "Show normal help text";
        }
      }  // choice help-mode

      leaf home {
        type string {
          length "1..max";
        }
        description
          "Directory specification for the home directory
to use instead of HOME.";
      }

      leaf indent {
        type yt:IndentType;
        description
          "Number of spaces to indent (0..9) in formatted output.";
      }

      leaf log {
        type string;
        description
          "Filespec for the log file to use instead of STDOUT.

If this parameter is used on the command line then
the --log-append parameter must also be present
on the command line if append mode is desired.";
      }

      leaf log-append {
        type empty;
        description
          "If present, the log will be appended not over-written.
If not, the log will be over-written.
Only meaningful if the 'log' parameter is
also present.";
      }

      leaf log-level {
        type yt:NcDebugType;
        description
          "Sets the debug logging level for the program.";
      }

      leaf modpath {
        type yt:NcPathList;
        description
          "Directory search path for YANG or YIN modules.
Overrides the YUMA_MODPATH environment variable.";
      }

      leaf 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-pro.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";
      }

      leaf subdirs {
        type boolean;
        default "true";
        description
          "If false, the file search paths for modules, scripts,
and data files will not include sub-directories if they
exist in the specified path.

If true, then these file search paths will include
sub-directories, if present.  Any directory name beginning
with a dot '.' character, or named 'CVS', will be ignored.";
      }

      leaf version {
        type empty;
        description
          "Print program version string and exit.";
      }

      leaf warn-error {
        type boolean;
        default "false";
        description
          "Control whether all warnings are upgraded to errors.
If 'true' then all warnings will be treated as errors
unless a warn-off parameter is set to disable a
specific warning.";
      }

      leaf warn-idlen {
        type uint32 {
          range "0 | 8 .. 1023";
        }
        default "64";
        description
          "Control whether identifier length warnings will be
generated.  The value zero disables all identifier
length checking.  If non-zero, then a warning will
be generated if an identifier is defined which
has a length is greater than this amount.";
      }

      leaf warn-linelen {
        type uint32 {
          range "0 | 40 .. 4095";
        }
        default "0";
        description
          "Control whether line length warnings will be
generated.  The value zero disables all line length
checking.  If non-zero, then a warning will
be generated if the line length is greater than
this amount.  Tab characters are counted as 8 spaces.";
      }

      leaf-list warn-off {
        type uint32 {
          range "1000 .. 1999";
        }
        description
          "Control whether the specified warning number will be
generated and counted in the warning total for the
module being parsed.";
      }

      leaf-list warn-up {
        type uint32 {
          range "1000 .. 1999";
        }
        description
          "Control whether the specified warning number will be
upgraded to an error and counted in the error total
for the module being parsed.";
      }

      leaf yumapro-home {
        type string;
        description
          "Directory for the yumapro project root to use.
If present, this directory location will
override the 'YUMAPRO_HOME' environment variable,
if it is present.  If a zero-length string is
entered, then the YUMAPRO_HOME environment variable
will be ignored.";
      }
    }  // container yangdiff-pro
  }  // module yangdiff-pro