module yuma-app-common {

    yang-version 1;
    namespace "http://netconfcentral.org/ns/yuma-app-common";
    prefix "appcmn";

    import yuma-types { prefix "yt"; }

    organization "Netconf Central";

    contact
        "Andy Bierman <andy at netconfcentral.org>";

    description
       "Common CLI parameters used in all yuma applications.

     Copyright (c) 2010 - 2012 Andy Bierman and the persons
     identified as authors of the code.  All rights reserved.

     Copyright (c) 2012 - 2026 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 2026-01-30 {
       description
         "Change 'protocols' yang-api bit status to obsolete to
          remove from tab key";
    }

    revision 2017-07-25 {
       description
         "Add warn-up and warn-error parameters";
    }

    revision 2017-02-04 {
       description
         "Deprecate yang-api protocol support.
          Update 'restconf' bit to reference RFC 8040";
    }

    revision 2015-09-14 {
       description
         "Add new protocol parameter values 'yang-api'
          and 'restconf'";
    }

    revision 2015-03-29 {
       description
         "Fix the warn-off parameter";
    }

    revision 2012-08-16 {
       description
         "Split yuma-home into its own grouping YumaHomeParm";
    }

    revision 2011-10-06 {
       description
         "Add HomeParm grouping.
          Split CommonFeatureParms from NcxAppCommon grouping.";
    }

    revision 2011-04-24 {
       description
         "Remove empty featureParms grouping.
          Add ProtocolsParm grouping.";
    }

    revision 2011-01-28 {
       description
         "Add OutputParm grouping";
    }

    revision 2010-12-18 {
       description
         "Change warn-linelen default value to 0 to turn it off";
    }

    revision 2010-01-25 {
       description
         "Allow revision date in module parm for 0.10 release.";
    }

    revision 2010-01-14 {
       description "Initial version for 0.9.9 release.";
    }

    typedef CliWithDefaultsType {
        description "Add 'none' to standard enumerations";
        type enumeration {
            enum none;
            enum report-all;
            enum report-all-tagged;
            enum trim;
            enum explicit;
        }
    }

    grouping CliWithDefaultsParm {
        leaf with-defaults {
            type CliWithDefaultsType;
            description "Include default data nodes";
        }
    }

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

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

    grouping DatapathParm {
        leaf datapath {
          description
             "Internal file search path for config files.
              Overrides the YUMA_DATAPATH environment variable.";
          type yt:NcPathList;
        }
    }

    grouping RunpathParm {
        leaf runpath {
          description
             "Internal file search path for executable modules.
              Overrides the YUMA_RUNPATH environment variable.";
          type yt:NcPathList;
        }
    }

    grouping NcxAppCommon {

        leaf help {
          description "Print program help file and exit.";
          type empty;
        }

        uses HelpMode;

        uses IndentParm;

	leaf log {
          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.";
          type string;
        }

	leaf log-append {
          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.";
          type empty;
        }

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


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

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

        leaf warn-error {
          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.";
          type boolean;
          default false;
        }

        leaf warn-idlen {
          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.";
          type uint32 {
            range "0 | 8 .. 1023";
          }
          default 64;
        }

        leaf warn-linelen {
          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.";
          type uint32 {
            range "0 | 40 .. 4095";
          }
          // default 72;
          default 0;
        }

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

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

    }

    grouping YumaHomeParm {
        leaf yuma-home {
          description
             "Directory for the yuma project root to use.
              If present, this directory location will
              override the 'YUMA_HOME' environment variable,
              if it is present.  If a zero-length string is
              entered, then the YUMA_HOME environment variable
              will be ignored.";
          type string;
        }
    }

    grouping ConfigParm {
        leaf config {
          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.";
           type string;
        }
    }

    grouping NewConfigParm {
        choice config-choice {
          leaf config {
            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.";
             type string;
          }
          leaf no-config {
            description
              "Do not the default .conf file even if it exists.";
            type empty;
          }
        }
    }

    grouping CommonFeatureParms {

        leaf feature-enable-default {
          description
            "If true, then features will be enabled by default.
             If false, then features will be disabled by default.";
          type boolean;
          default true;
        }

        leaf-list feature-enable {
          description
            "Identifies a feature which should be considered
             enabled.";
          type yt:FeatureSpec;
        }

        leaf-list feature-disable {
          description
            "Identifies a feature which should be considered
             disabled.";
          type yt:FeatureSpec;
        }
    }

    grouping FeatureCodeParms {
        leaf feature-code-default {
          description
            "The default feature code generation type.";
          type enumeration {
            enum static {
              description
                "The default behavior for feature behavior
                 is to use statically defined features at
                 compile-time.";
            }
            enum dynamic {
              description
                "The default behavior for feature behavior
                 is to use dynamically defined features at
                 load-time.";
            }
          }
          default dynamic;
        }

        leaf-list feature-static {
          description
            "Identifies a feature which is configured to be a
             static feature, and therefore set at compile time.";
          type yt:FeatureSpec;
        }

        leaf-list feature-dynamic {
          description
            "Identifies a feature which is configured to be a
             static feature, and therefore set at compile time.";
          type yt:FeatureSpec;
        }
    }

    grouping ModuleParm {
        leaf-list module {
            description
              "YANG source module name to use.";
            type yt:NcModuleSpec;
        }
    }

    grouping SubtreeParm {
        leaf-list subtree {
            description
              "Path specification of the directory subtree to use.
               All of the YANG source modules contained in the
               specified directory sub-tree will be processed.

               Note that symbolic links are not followed
               during the directory traversal.  Only real directories
               will be searched and regular files will be checked as
               modules.  Processing will continue to the next file
               if a module contains errors.

               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";

            type yt:NcPathSpec;
        }
    }

    grouping DeviationParm {
        leaf-list deviation {
            description
              "YANG deviation file.

               This parameter identifies a YANG module that
               should only be checked for deviation statements
               for external modules.  These will be collected
               and applied to the real module(s) being processed.

               Deviations are applied as patches to the target module.
               Since they are not identified in the target module at
               all (ala imports), they have to be specified
               explicitly, so they will be correctly processed.

               If this string represents a filespec,
	       ending with the '.yang' or '.yin' extension,
	       then only that file location will be checked.

               If this string represents a module name, then
               the module search path will be checked for
               a file with the module name and the '.yang'
               or '.yin' extension.

               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
             ";
            type yt:NcModuleSpec;
        }
    }

    grouping SubdirsParm {
	leaf subdirs {
          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.";
          type boolean;
          default true;
        }
    }

    grouping OutputParm {
        leaf output {
          description
            "Output directory or file name to use.
             Default is STDOUT if none specified and the
             'defnames' parameter is also set to 'false'.

             For yangdump, if this parameter represents an existing
             directory, then the 'defnames' parameter will be set
             to 'true' by default, and the translation output file(s)
             will be generated in the specified directory.

             For yangdump, if this parameter represents a file name,
             then the 'defnames' parameter will be ignored,
             and all translation output will be directed
             to the specified file.

             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

             If this parameter is present, and identifies
             an existing directory, then any translation output
             files will be generated in that directory.  If that
             parameter identifies a file, then that one file will
             be used for output.

             For yangdump, if the 'format' parameter is present,
             then one file with the default name will be generated
             for each YANG or YIN file found in the sub-tree.";

          type string;
        }
    }

    grouping ProtocolsParm {
        leaf protocols {
           description
             "Specifies which protocol versions the program or session
              will attempt to use. Empty set is not allowed.";
           must ". != ''";
           type bits {
              bit netconf1.0 {
                 description "RFC 4741 base:1.0";
                 position 0;
              }
              bit netconf1.1 {
                 description "RFC 6241 base:1.1";
                 position 1;
              }
              bit yang-api {
                 description "YANG-API protocol";
                 reference "draft-bierman-netconf-yang-api-01.txt";
                 position 2;
                 status obsolete;
              }
              bit restconf {
                 description "RESTCONF Protocol";
                 reference "RFC 8040";
                 position 3;
              }
           }
           /* default "netconf1.0 netconf1.1"; */
        }
    }

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

}
