Skip to content

Navigation Menu

Sign in
Sign up

Include default values in the spec #34

Discussion options

As brought up in #16 it would be useful to include the default values for non-required fields in the spec.

I think for most fields some general rules can be formulated, but especially the arity field should have an non-null default

General Rules

  • Boolean fields default to false
  • Array fields default to an empty array
  • Object fields default to a object filled with the default values of the specified type (i.e. the conventions field in the Document object defaults to a Conventions object with it's default values)

Argument Object / arity

I think in most CLIs, the default case for arguments is that an argument is optional and may appear once, so a sensible default for an argument's arity may be

{
 "minimum": 0,
 "maximum": 1
}
You must be logged in to vote

Replies: 3 comments 3 replies

Comment options

An 'option' appearing once is IMO a bit up for discussion though - it's quite common for repeated uses of an option to either

  • accrue/increase some logical counter (as in POSIX-style -v/-vv/-vvvvvvv scenarios)
  • be overwritten in a 'last one wins' manner (as in --foo a --foo b => --foo b effectively)

and I'm sure there are other strategies that I'm missing as well. How do these modalities interact with Arity?
You must be logged in to vote
2 replies
Comment options

In my understanding, the arity field is currently only there for arguments but not for options.

However, I think it makes sense to have an arity on the Option object as well and I think there would need to be different default arities for options vs arguments.

I've opened up a separate discussion regarding the Option arity here: #35

Comment options

I don't think arity on the Option Object will do any good here since they only will take the values 0:1, 1:1, or 1:*.

I'm also starting to think that perhaps having an argument property on the Option Object is the wrong way to go here as well, since it makes things a bit difficult to understand and follow, and not sure if it really helps any use cases. I will open a new discussion around that.

Scenarios

The scenarios I can think of (that @baronfel mentioned as well) is:

  1. Only one option with the same name is allowed per command.
  2. Repeatable use of an option is allowed. If the option only takes one value (ex. arity is 0:1 or 1:1) then:
    1. That's an error.
    2. The last one wins.
    3. The first one wins. Never seen this personally, but might exist.

Special case

Then it's the scenario with the -v, -vv, and -vvv which accrue/increase some logical counter that @baronfel mentioned,
but I would be OK not supporting this initially in the spec.
Comment options

Here's a proposal for default values:

Document Object

Field Name Type Default Value Description
opencli string REQUIRED The OpenCLI version number
info CliInfo Object REQUIRED Information about the CLI
conventions Conventions Object The conventions used by the CLI
arguments [Argument Object] Root command arguments
options [Option Object] Root command options
commands [Command Object] Root command sub commands
exitCodes [ExitCode Object] Root command exit codes
examples [string] Examples of how to use the CLI
interactive bool false Indicates whether or not the command requires interactive input
metadata [Metadata Object] Custom metadata

CliInfo Object

Field Name Type Default Value Description
title string REQUIRED The application title
summary string A short summary of the application
description string A description of the application
contact Contact Object The contact information
license License Object The application license
version string REQUIRED The application version

Conventions Object

Field Name Type Default Value Description
groupOptions bool true Whether or not grouping of short options are allowed
optionArgumentSeparator string U+0020 (space) The option argument separator

Contact Object

Field Name Format Default Value Description
name string The identifying name of the contact person/organization
url string The URI for the contact information. This MUST be in the form of a URI
email string The email address of the contact person/organization. This MUST be in the form of an email address

License Object

Field Name Type Default Value Description
name string The license name
identifier string The SPDX license identifier

Command Object

Field Name Type Default Value Description
name string REQUIRED The command name
aliases [string] The command aliases
options [Option Object] The command's options
arguments [Argument Object] The command's arguments
commands [Command Object] The command's sub commands
exitCodes [ExitCode Object] The command's exit codes
description string The command description
hidden bool false Whether or not the command is hidden
examples [string] Examples of how to use the command
interactive bool false Indicates whether or not the command requires interactive input
metadata [Metadata Object] Custom metadata

Argument Object

Field Name Type Default Value Description
name string REQUIRED The argument name
required bool false Whether or not the argument is required
arity Arity Object The argument arity. Arity defines the minimum and maximum number of argument values
acceptedValues [string] A list of accepted values
group string The argument group
decription string The argument description
hidden bool false Whether or not the argument is hidden
metadata [Metadata Object] Custom metadata

Option Object

Field Name Type Default Value Description
name string REQUIRED The option name
required bool false Whether or not the option is required
aliases [string] The option's aliases
arguments [Argument] The option's arguments
group string The option group
description string The option description
recursive bool false Specifies whether the option is accessible from the immediate parent command and, recursively, from its subcommands
hidden bool false Whether or not the option is hidden
metadata [Metadata Object] Custom metadata

Arity Object

Field Name Type Default Value Description
minimum int 1 The minimum number of values allowed
maximum int 1 The maximum number of values allowed. If not specified (nil), unlimited number of items are allowed

ExitCode Object

Field Name Type Default Value Description
code int REQUIRED The exit code
description string The exit code description

Metadata Object

Field Name Type Default Value Description
name string REQUIRED The metadata name
value object The metadata value
You must be logged in to vote
0 replies
Comment options

Created issue: #58

You must be logged in to vote
1 reply
Comment options

Added in #59

Answer selected by patriksvensson
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

AltStyle によって変換されたページ (->オリジナル) /