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