doc/src/write_command.rst

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