doc/build/html/write_command.html

   1
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
   3   "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   4
   5
   6 <html xmlns="http://www.w3.org/1999/xhtml">
   7   <head>
   8     <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
   9
  10     <title>Add a user custom command &mdash; salomeTools 5.0.0dev documentation</title>
  11
  12     <link rel="stylesheet" href="_static/alabaster.css" type="text/css" />
  13     <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
  14     <link rel="stylesheet" href="/volatile/wambeke/SAT5/SAT5_S840_MATIX24/SAT/doc/src/custom.css" type="text/css" />
  15
  16     <script type="text/javascript">
  17       var DOCUMENTATION_OPTIONS = {
  18         URL_ROOT:    '',
  19         VERSION:     '5.0.0dev',
  20         COLLAPSE_INDEX: false,
  21         FILE_SUFFIX: '.html',
  22         HAS_SOURCE:  true
  23       };
  24     </script>
  25     <script type="text/javascript" src="_static/jquery.js"></script>
  26     <script type="text/javascript" src="_static/underscore.js"></script>
  27     <script type="text/javascript" src="_static/doctools.js"></script>
  28     <script type="text/javascript" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
  29     <link rel="top" title="salomeTools 5.0.0dev documentation" href="index.html" />
  30     <link rel="next" title="src" href="commands/apidoc/modules.html" />
  31     <link rel="prev" title="Command generate" href="commands/generate.html" />
  32
  33   <link rel="stylesheet" href="_static/custom.css" type="text/css" />
  34
  35
  36   <meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" />
  37
  38   </head>
  39   <body>
  40
  41
  42     <div class="document">
  43       <div class="documentwrapper">
  44         <div class="bodywrapper">
  45           <div class="body" role="main">
  46
  47   <div class="section" id="add-a-user-custom-command">
  48 <h1>Add a user custom command<a class="headerlink" href="#add-a-user-custom-command" title="Permalink to this headline">¶</a></h1>
  49 <div class="section" id="introduction">
  50 <h2>Introduction<a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
  51 <div class="admonition note">
  52 <p class="first admonition-title">Note</p>
  53 <p class="last">This documentation is for <a class="reference external" href="https://docs.python.org/2.7">Python</a> developers.</p>
  54 </div>
  55 <p>The salomeTools product provides a simple way to develop commands.
  56 The first thing to do is to add a file with <em>.py</em> extension in the <tt class="docutils literal"><span class="pre">commands</span></tt> directory of salomeTools.</p>
  57 <p>Here are the basic requirements that must be followed in this file in order to add a command.</p>
  58 </div>
  59 <div class="section" id="basic-requirements">
  60 <h2>Basic requirements<a class="headerlink" href="#basic-requirements" title="Permalink to this headline">¶</a></h2>
  61 <p>By adding a file <em>mycommand.py</em> in the <tt class="docutils literal"><span class="pre">commands</span></tt> directory, salomeTools will define a new command named <tt class="docutils literal"><span class="pre">mycommand</span></tt>.</p>
  62 <p>In <em>mycommand.py</em>, there must be the following method:</p>
  63 <div class="highlight-python"><div class="highlight"><pre><span class="k">def</span> <span class="nf">run</span><span class="p">(</span><span class="n">args</span><span class="p">,</span> <span class="n">runner</span><span class="p">,</span> <span class="n">logger</span><span class="p">):</span>
  64     <span class="c"># your algorithm ...</span>
  65     <span class="k">pass</span>
  66 </pre></div>
  67 </div>
  68 <p>In fact, at this point, the command will already be functional.
  69 But there are some useful services provided by salomeTools :</p>
  70 <ul class="simple">
  71 <li>You can give some options to your command:</li>
  72 </ul>
  73 <div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">src</span>
  74
  75 <span class="c"># Define all possible option for mycommand command :  &#39;sat mycommand &lt;options&gt;&#39;</span>
  76 <span class="n">parser</span> <span class="o">=</span> <span class="n">src</span><span class="o">.</span><span class="n">options</span><span class="o">.</span><span class="n">Options</span><span class="p">()</span>
  77 <span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s">&#39;m&#39;</span><span class="p">,</span> <span class="s">&#39;myoption&#39;</span><span class="p">,</span> \
  78                   <span class="s">&#39;boolean&#39;</span><span class="p">,</span> <span class="s">&#39;myoption&#39;</span><span class="p">,</span> \
  79                   <span class="s">&#39;My option changes the behavior of my command.&#39;</span><span class="p">)</span>
  80
  81 <span class="k">def</span> <span class="nf">run</span><span class="p">(</span><span class="n">args</span><span class="p">,</span> <span class="n">runner</span><span class="p">,</span> <span class="n">logger</span><span class="p">):</span>
  82     <span class="c"># Parse the options</span>
  83     <span class="p">(</span><span class="n">options</span><span class="p">,</span> <span class="n">args</span><span class="p">)</span> <span class="o">=</span> <span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">(</span><span class="n">args</span><span class="p">)</span>
  84     <span class="c"># algorithm</span>
  85 </pre></div>
  86 </div>
  87 <ul class="simple">
  88 <li>You can add a <em>description</em> method that will display a message when the user will call the help:</li>
  89 </ul>
  90 <div class="highlight-python"><div class="highlight"><pre> <span class="kn">import</span> <span class="nn">src</span>
  91
  92  <span class="c"># Define all possible option for mycommand command : &#39;sat mycommand &lt;options&gt;&#39;</span>
  93  <span class="n">parser</span> <span class="o">=</span> <span class="n">src</span><span class="o">.</span><span class="n">options</span><span class="o">.</span><span class="n">Options</span><span class="p">()</span>
  94  <span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s">&#39;m&#39;</span><span class="p">,</span> <span class="s">&#39;myoption&#39;</span><span class="p">,</span> \
  95                    <span class="s">&#39;boolean&#39;</span><span class="p">,</span> <span class="s">&#39;myoption&#39;</span><span class="p">,</span> \
  96                    <span class="s">&#39;My option changes the behavior of my command.&#39;</span><span class="p">)</span>
  97
  98 <span class="hll"> <span class="k">def</span> <span class="nf">description</span><span class="p">():</span>
  99 </span><span class="hll">     <span class="k">return</span> <span class="n">_</span><span class="p">(</span><span class="s">&quot;The help of mycommand.&quot;</span><span class="p">)</span>
 100 </span>
 101  <span class="k">def</span> <span class="nf">run</span><span class="p">(</span><span class="n">args</span><span class="p">,</span> <span class="n">runner</span><span class="p">,</span> <span class="n">logger</span><span class="p">):</span>
 102      <span class="c"># Parse the options</span>
 103      <span class="p">(</span><span class="n">options</span><span class="p">,</span> <span class="n">args</span><span class="p">)</span> <span class="o">=</span> <span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">(</span><span class="n">args</span><span class="p">)</span>
 104      <span class="c"># algorithm</span>
 105 </pre></div>
 106 </div>
 107 </div>
 108 <div class="section" id="howto-access-salometools-config-and-other-commands">
 109 <h2>HowTo access salomeTools config and other commands<a class="headerlink" href="#howto-access-salometools-config-and-other-commands" title="Permalink to this headline">¶</a></h2>
 110 <p>The <em>runner</em> variable is an python instance of <em>Sat</em> class.
 111 It gives access to <em>runner.cfg</em> which is the data model defined from all
 112 <em>configuration pyconf files</em> of salomeTools
 113 For example, <em>runner.cfg.APPLICATION.workdir</em>
 114 contains the root directory of the current application.</p>
 115 <p>The <em>runner</em> variable gives also access to other commands of salomeTools:</p>
 116 <div class="highlight-python"><div class="highlight"><pre><span class="c"># as CLI_ &#39;sat prepare ...&#39;</span>
 117 <span class="n">runner</span><span class="o">.</span><span class="n">prepare</span><span class="p">(</span><span class="n">runner</span><span class="o">.</span><span class="n">cfg</span><span class="o">.</span><span class="n">VARS</span><span class="o">.</span><span class="n">application</span><span class="p">)</span>
 118 </pre></div>
 119 </div>
 120 </div>
 121 <div class="section" id="howto-logger">
 122 <h2>HowTo logger<a class="headerlink" href="#howto-logger" title="Permalink to this headline">¶</a></h2>
 123 <p>The logger variable is an instance of the Logger class.
 124 It gives access to the write method.</p>
 125 <p>When this method is called, the message passed as parameter
 126 will be displayed in the terminal and written in an xml log file.</p>
 127 <div class="highlight-python"><div class="highlight"><pre><span class="n">logger</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="s">&quot;My message&quot;</span><span class="p">,</span> <span class="mi">3</span><span class="p">)</span> <span class="c"># 3 as default</span>
 128 </pre></div>
 129 </div>
 130 <p>The second argument defines the level of verbosity
 131 that is wanted for this message.
 132 It has to be between 1 and 5 (the most verbose level).</p>
 133 </div>
 134 <div class="section" id="hello-example">
 135 <h2>HELLO example<a class="headerlink" href="#hello-example" title="Permalink to this headline">¶</a></h2>
 136 <p>Here is a <em>hello</em> command, file <em>commands/hello.py</em>:</p>
 137 <div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">src</span>
 138
 139 <span class="sd">&quot;&quot;&quot;</span>
 140 <span class="sd">hello.py</span>
 141 <span class="sd">Define all possible options for hello command:</span>
 142 <span class="sd">sat hello &lt;options&gt;</span>
 143 <span class="sd">&quot;&quot;&quot;</span>
 144
 145 <span class="n">parser</span> <span class="o">=</span> <span class="n">src</span><span class="o">.</span><span class="n">options</span><span class="o">.</span><span class="n">Options</span><span class="p">()</span>
 146 <span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s">&#39;f&#39;</span><span class="p">,</span> <span class="s">&#39;french&#39;</span><span class="p">,</span> <span class="s">&#39;boolean&#39;</span><span class="p">,</span> <span class="s">&#39;french&#39;</span><span class="p">,</span> <span class="s">&quot;french set hello message in french.&quot;</span><span class="p">)</span>
 147
 148 <span class="k">def</span> <span class="nf">description</span><span class="p">():</span>
 149     <span class="k">return</span> <span class="n">_</span><span class="p">(</span><span class="s">&quot;The help of hello.&quot;</span><span class="p">)</span>
 150
 151 <span class="k">def</span> <span class="nf">run</span><span class="p">(</span><span class="n">args</span><span class="p">,</span> <span class="n">runner</span><span class="p">,</span> <span class="n">logger</span><span class="p">):</span>
 152     <span class="c"># Parse the options</span>
 153     <span class="p">(</span><span class="n">options</span><span class="p">,</span> <span class="n">args</span><span class="p">)</span> <span class="o">=</span> <span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">(</span><span class="n">args</span><span class="p">)</span>
 154     <span class="c"># algorithm</span>
 155     <span class="k">if</span> <span class="ow">not</span> <span class="n">options</span><span class="o">.</span><span class="n">french</span><span class="p">:</span>
 156         <span class="n">logger</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="s">&#39;HELLO! WORLD!</span><span class="se">\n</span><span class="s">&#39;</span><span class="p">)</span>
 157     <span class="k">else</span><span class="p">:</span>
 158         <span class="n">logger</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="s">&#39;Bonjour tout le monde!</span><span class="se">\n</span><span class="s">&#39;</span><span class="p">)</span>
 159 </pre></div>
 160 </div>
 161 <p>A first call of hello:</p>
 162 <div class="highlight-bash"><div class="highlight"><pre><span class="c"># Get the help of hello:</span>
 163 ./sat --help hello
 164
 165 <span class="c"># To get bonjour</span>
 166 ./sat hello --french
 167 Bonjour tout le monde!
 168
 169 <span class="c"># To get hello</span>
 170 ./sat hello
 171 HELLO! WORLD!
 172
 173 <span class="c"># To get the log</span>
 174 ./sat log
 175 </pre></div>
 176 </div>
 177 </div>
 178 </div>
 179
 180
 181           </div>
 182         </div>
 183       </div>
 184       <div class="sphinxsidebar">
 185         <div class="sphinxsidebarwrapper">
 186             <p class="logo"><a href="index.html">
 187               <img class="logo" src="_static/sat_v5.0.png" alt="Logo"/>
 188             </a></p>
 189   <h3><a href="index.html">Table Of Contents</a></h3>
 190   <ul>
 191 <li><a class="reference internal" href="#">Add a user custom command</a><ul>
 192 <li><a class="reference internal" href="#introduction">Introduction</a></li>
 193 <li><a class="reference internal" href="#basic-requirements">Basic requirements</a></li>
 194 <li><a class="reference internal" href="#howto-access-salometools-config-and-other-commands">HowTo access salomeTools config and other commands</a></li>
 195 <li><a class="reference internal" href="#howto-logger">HowTo logger</a></li>
 196 <li><a class="reference internal" href="#hello-example">HELLO example</a></li>
 197 </ul>
 198 </li>
 199 </ul>
 200 <div class="relations">
 201 <h3>Related Topics</h3>
 202 <ul>
 203   <li><a href="index.html">Documentation overview</a><ul>
 204       <li>Previous: <a href="commands/generate.html" title="previous chapter">Command generate</a></li>
 205       <li>Next: <a href="commands/apidoc/modules.html" title="next chapter">src</a></li>
 206   </ul></li>
 207 </ul>
 208 </div>
 209   <h3>This Page</h3>
 210   <ul class="this-page-menu">
 211     <li><a href="_sources/write_command.txt"
 212            rel="nofollow">Show Source</a></li>
 213   </ul>
 214 <div id="searchbox" style="display: none">
 215   <h3>Quick search</h3>
 216     <form class="search" action="search.html" method="get">
 217       <input type="text" name="q" />
 218       <input type="submit" value="Go" />
 219       <input type="hidden" name="check_keywords" value="yes" />
 220       <input type="hidden" name="area" value="default" />
 221     </form>
 222     <p class="searchtip" style="font-size: 90%">
 223     Enter search terms or a module, class or function name.
 224     </p>
 225 </div>
 226 <script type="text/javascript">$('#searchbox').show(0);</script>
 227         </div>
 228       </div>
 229       <div class="clearer"></div>
 230     </div>
 231     <div class="footer">
 232       &copy;2018, CEA.
 233
 234       |
 235       Powered by <a href="http://sphinx-doc.org/">Sphinx 1.1.3</a>
 236       &amp; <a href="https://github.com/bitprophet/alabaster">Alabaster </a>
 237
 238       |
 239       <a href="_sources/write_command.txt"
 240           rel="nofollow">Page source</a>
 241     </div>
 242
 243
 244
 245
 246   </body>
 247 </html>