diclipy/dependencies/clap/manual/structure_of_input.mdown

User input

When your program is invoked, user usually gives it some input in form of options (some of them with arguments attached) and simple arguments.

Here, I will explain how CLAP interprets, analyzes and processes user input before it expose it to you in form that is easy to work with.

---

 

Structure of input

Whole input is contained in argv variable but is logically divided into two main sections: input and operands. As of version 0.7.1 they are not really split during input analysis but there is a special method _getinput() which will extract only the input part of argv.

General structure is shown below (foo is the name of example program):

foo [options [option-arguments]]... [--] [arguments]...

input

This part consists of options (switches) and their arguments. It's finished when CLAP encounters a breaker (special two-hyphen string (--) meaning: terminate input analyzing HERE because from now on only arguments will follow), or a non-option and non-option-argument string. Only this part is checked for mistakes since arguments are too program-specific and CLAP leaves their validation to users.

operands

Everything that follows first non-option and non-option-argument string or breaker.

---

 

Input items types

CLAP divides user input into three types:

• options (or switches),
• option-arguments,
• operands.

---

 

1. Options (switches)

Options are strings that hold special meaning defined by the programmer or creator of UI. They can (but doesn't have to) request fixed-length lists of arguments of different types to be passed to them.

Options are recognized using regular expressions (see the code in clap/base.py to check the exact regexp used) and there are two types of them with the same functionality but with different rules for appearance:

• short options: one-character preceded by single hyphen, e.g. -o,
• long options: two or more characters preceded by two hyphens, e.g. --output,

---

1.1 Short options

Short options are one-character switches. Usually they have long aliases which are more descriptive but entering just one character saves keystrokes.

Short option is a string starting with single hyphen (-) immediately followed by a single letter or number (the name of the short option). Name cannot be another hyphen - two hyphens (--) are special string used to tell a program that it's input is finished and from now on only non-option arguments will follow.

Abbreviations

Note to programmers: if you want to enable your users to use abbreviations you must first format the input using Formatter() object (clap.formater.Formatter()) because parser is not able to understand them.

Short options are useful for users who memorized some part of the program's interface as they can be passed in abbreviated form. This means that such input:

foo -a -b -c -d

can be abbreviated to:

foo -abcd

and will still hold the same functionality.

However, when a short option requests some argument it is not possible to connect it with others unless it's the last one. This means that input showed below:

foo -a -b -c spam -d

cannot be abbreviated to input of such form (it would even raise an exception):

foo -abcd spam

but can be abbreviated to:

foo -abdc spam

---

1.2 Long options

Long options are two-or-more character switches. Their names can contain hyphens, letters and numbers.

Long options are more descriptive but they lack the abbreviation feature of short options.

---

 

2. Option-arguments

These are non-option strings which can be mixed with options and won't terminate input parsing. List of arguments for an option is a list of callback functions taking one argument.

Example: option --point requires two float arguments (X and Y axis) it should be defined as:

parser.add(short='p', long='point', arguments=[float, float])

#   some code

x, y = parser.get('--point')

Multiple arguments are returned as tuples, single as single objects.

Callback functions

You can pass any single-argument function as a type but keep in mind that there are few rules:

• user must supply valid value for it,
• on invalid data it should raise ValueError or return default value,

It's safe to use basic types: str, int and float.

There is no way to turn off the conversion - if you want general type option and decide later what to do with it use str type as it won't get converted in any way (only conversion will be from string to string).

Variable-length arguments list

Currently there is no way to define a variable-length list of arguments.

Optional arguments

Optional arguments are not yet implemented. There is no fixed time when they'll be.