Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
  • 4 commits
  • 8 files changed
  • 0 commit comments
  • 2 contributors
View
1  AUTHORS
@@ -13,3 +13,4 @@
* rbeagrie - https://bitbucket.org/rbeagrie
* Miguel Angel Garcia - http://magmax.org
* Roland Puntaier - roland <dot> puntaier <at> gmail <dot> com
+ * Vincent Férotin - vincent <dot> ferotin <at> gmail <dot> com
View
2  doc/cmd_other.rst
@@ -10,6 +10,8 @@ The example below is used to manage a very simple C project.
+.. _cmd-help:
+
help
-------
View
85 doc/cmd_run.rst
@@ -92,12 +92,12 @@ parameters
It is possible to pass option parameters to the task through the command line.
-Just add a 'params' field to the task dictionary. `params` must be a list of
+Just add a ``params`` field to the task dictionary. ``params`` must be a list of
dictionaries where every entry is an option parameter. Each parameter must
define a name, and a default value. It can optionally define a "short" and
"long" names to be used from the command line (it follows unix command line
-conventions). It may also specify a type the parameter should be converted to.
-
+conventions). It may also specify additional attributes, such as
+`type` and `help` (see :ref:`below <parameters-attributes>`).
See the example:
@@ -123,6 +123,85 @@ For cmd-actions use python string substitution notation:
mycmd -c --other value xxx
+
+.. _parameters-attributes:
+
+All parameters attributes
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Here is the list of all attributes ``param`` accepts:
+
+``name``
+ Name of the parameter, identifier used as name of the the parameter
+ on python code.
+ It should be unique among others.
+
+ :required: True
+ :type: `str`
+
+``default``
+ Default value used when it is set through command-line.
+
+ :required: True
+
+``short``
+ Short parameter form, used for e.g. ``-p value``.
+
+ :required: optional
+ :type: `str`
+
+``long``
+ Long parameter form, used for e.g. ``--parameter value``
+ when it differs from its `name`.
+
+ :required: optional
+ :type: `str`
+
+``type``
+ Actually it can be any python callable.
+ It coverts the string value received from command line to whatever
+ value to be used on python code.
+
+ If the ``type`` is ``bool`` the parameter is treated as an *option flag*
+ where no value should be specified, value is set to ``True``.
+ Example: ``doit mytask --flag``.
+
+ :required: optional
+ :type: `callable` (e.g. a `function`)
+ :default: `str`
+
+``help``
+ Help message associated to this parameter, shown when
+ :ref:`help <cmd-help>` is called for this task,
+ e.g. ``doit help mytask``.
+
+ :required: optional
+ :type: `str`
+
+``inverse``
+ [only for `bool` parameter]
+ Set inverse flag long parameter name, value will be set to ``False``
+ (see example below).
+
+ :required: optional
+ :type: `str`
+
+ Example, given following code:
+
+ .. literalinclude:: tutorial/parameters_inverse.py
+
+ calls to task `with_flag` show flag on or off:
+
+ .. code-block:: console
+
+ $ doit with_flag
+ . with_flag
+ Flag On
+ $ doit with_flag --flagoff
+ . with_flag
+ Flag Off
+
+
title
-------
View
3  doc/dictionary.txt
@@ -249,3 +249,6 @@ x'
xxx
xyz
zsh
+str
+mytask
+flagoff
View
3  doc/extending.rst
@@ -71,6 +71,9 @@ set some class variables and implement the `execute` method.
:members: execute
+``cmd_options`` uses the same format as
+:ref:`task parameters <parameters-attributes>`.
+
Example: scaffolding
----------------------
View
3  doc/tutorial/parameters.py
@@ -19,7 +19,8 @@ def task_cmd_params():
'params':[{'name':'flag',
'short':'f',
'long': 'flag',
- 'default': ''}],
+ 'default': '',
+ 'help': 'helpful message about this flag'}],
'verbosity': 2
}
View
15 doc/tutorial/parameters_inverse.py
@@ -0,0 +1,15 @@
+def task_with_flag():
+ def _task(flag):
+ print "Flag {0}".format("On" if flag else "Off")
+
+ return {
+ 'params': [{
+ 'name': 'flag',
+ 'long': 'flagon',
+ 'short': 'f',
+ 'type': bool,
+ 'default': True,
+ 'inverse': 'flagoff'}],
+ 'actions': [(_task, )],
+ 'verbosity': 2
+ }
View
4 doit/cmd_help.py
@@ -70,7 +70,9 @@
- default [required] default value for parameter
- short [optional] (string - 1 letter) short option string
- long [optional] (string) long option string
- - type [optional] the option will be converted to this type
+ - type [optional] (callable) the option will be converted to this type
+ - help [optional] (string) description displayed by help command
+ - inverse [optional] (string) for a bool parameter set value to False
verbosity:
- type: int

No commit comments for this range

Something went wrong with that request. Please try again.