doc/build/html/_sources/write_command.txt

   1
   2 .. include:: ../rst_prolog.rst
   3
   4
   5 Add a user custom command
   6 ***************************
   7
   8 Introduction
   9 ============
  10
  11 .. note:: This documentation is for Python_ developers.
  12
  13
  14 The salomeTools product provides a simple way to develop commands.
  15 The first thing to do is to add a file with *.py* extension in the ``commands`` directory of salomeTools.
  16
  17 Here are the basic requirements that must be followed in this file in order to add a command.
  18
  19 Basic requirements
  20 ==================
  21
  22 By adding a file *mycommand.py* in the ``commands`` directory, salomeTools will define a new command named ``mycommand``.
  23
  24 In *mycommand.py*, there must be the following method: ::
  25
  26     def run(args, runner, logger):
  27         # your algorithm ...
  28         pass
  29
  30 In fact, at this point, the command will already be functional.
  31 But there are some useful services provided by salomeTools :
  32
  33 * You can give some options to your command:
  34
  35 .. code-block:: python
  36
  37     import src
  38
  39     # Define all possible option for mycommand command :  'sat mycommand <options>'
  40     parser = src.options.Options()
  41     parser.add_option('m', 'myoption', \
  42                       'boolean', 'myoption', \
  43                       'My option changes the behavior of my command.')
  44
  45     def run(args, runner, logger):
  46         # Parse the options
  47         (options, args) = parser.parse_args(args)
  48         # algorithm
  49
  50
  51 * You can add a *description* method that will display a message when the user will call the help:
  52
  53
  54 .. code-block:: python
  55    :emphasize-lines: 9,10
  56
  57     import src
  58
  59     # Define all possible option for mycommand command : 'sat mycommand <options>'
  60     parser = src.options.Options()
  61     parser.add_option('m', 'myoption', \
  62                       'boolean', 'myoption', \
  63                       'My option changes the behavior of my command.')
  64
  65     def description():
  66         return _("The help of mycommand.")
  67
  68     def run(args, runner, logger):
  69         # Parse the options
  70         (options, args) = parser.parse_args(args)
  71         # algorithm
  72
  73 HowTo access salomeTools config and other commands
  74 ========================================================
  75
  76 The *runner* variable is an python instance of *Sat* class.
  77 It gives access to *runner.cfg* which is the data model defined from all
  78 *configuration pyconf files* of salomeTools
  79 For example, *runner.cfg.APPLICATION.workdir*
  80 contains the root directory of the current application.
  81
  82 The *runner* variable gives also access to other commands of salomeTools:
  83
  84 .. code-block:: python
  85
  86     # as CLI_ 'sat prepare ...'
  87     runner.prepare(runner.cfg.VARS.application)
  88
  89 HowTo logger
  90 ==============
  91
  92 The logger variable is an instance of the Logger class.
  93 It gives access to the write method.
  94
  95 When this method is called, the message passed as parameter
  96 will be displayed in the terminal and written in an xml log file.
  97
  98 .. code-block:: python
  99
 100     logger.write("My message", 3) # 3 as default
 101
 102 The second argument defines the level of verbosity
 103 that is wanted for this message.
 104 It has to be between 1 and 5 (the most verbose level).
 105
 106 HELLO example
 107 ==============
 108
 109 Here is a *hello* command, file *commands/hello.py*:
 110
 111 .. code-block:: python
 112
 113     import src
 114
 115     """
 116     hello.py
 117     Define all possible options for hello command:
 118     sat hello <options>
 119     """
 120
 121     parser = src.options.Options()
 122     parser.add_option('f', 'french', 'boolean', 'french', "french set hello message in french.")
 123
 124     def description():
 125         return _("The help of hello.")
 126
 127     def run(args, runner, logger):
 128         # Parse the options
 129         (options, args) = parser.parse_args(args)
 130         # algorithm
 131         if not options.french:
 132             logger.write('HELLO! WORLD!\n')
 133         else:
 134             logger.write('Bonjour tout le monde!\n')
 135
 136 A first call of hello:
 137
 138 .. code-block:: bash
 139
 140     # Get the help of hello:
 141     ./sat --help hello
 142
 143     # To get bonjour
 144     ./sat hello --french
 145     Bonjour tout le monde!
 146
 147     # To get hello
 148     ./sat hello
 149     HELLO! WORLD!
 150
 151     # To get the log
 152     ./sat log
 153
 154
 155
 156
 157