scilab/modules/m2sci/help/en_US/mfile2sci.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!--
   3  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
   4  * Copyright (C) ???? - INRIA - Serge STEER
   5  * Copyright (C) 2002-2004 - INRIA - Vincent COUVERT
   6  * Copyright (C) 2018 - Samuel GOUGEON
   7  *
   8  * Copyright (C) 2012 - 2016 - Scilab Enterprises
   9  *
  10  * This file is hereby licensed under the terms of the GNU GPL v2.0,
  11  * pursuant to article 5.3.4 of the CeCILL v.2.1.
  12  * This file was originally licensed under the terms of the CeCILL v2.1,
  13  * and continues to be available under such terms.
  14  * For more information, see the COPYING file which you should have received
  15  * along with this program.
  16     *
  17     -->
  18 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
  19         xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML"
  20         xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org"
  21         xml:lang="en" xml:id="mfile2sci">
  22     <refnamediv>
  23         <refname>mfile2sci</refname>
  24         <refpurpose>Matlab M-file to Scilab conversion function</refpurpose>
  25     </refnamediv>
  26     <refsynopsisdiv>
  27         <title>Syntax</title>
  28         <synopsis>
  29             mfile2sci()  // interactive GUI
  30             mfile2sci(M_file_path)
  31             mfile2sci(M_file_path, result_path )
  32             mfile2sci(M_file_path, result_path, Recmode)
  33             mfile2sci(M_file_path, result_path, Recmode, only_double)
  34             mfile2sci(M_file_path, result_path, Recmode, only_double, verbose_mode)
  35             mfile2sci(M_file_path, result_path, Recmode, only_double, verbose_mode, prettyprintoutput)
  36         </synopsis>
  37     </refsynopsisdiv>
  38     <refsection>
  39         <title>Arguments</title>
  40         <variablelist>
  41             <varlistentry>
  42                 <term>M_file_path</term>
  43                 <listitem>
  44                     <para>a character string which gives the path of Matlab M-file to convert</para>
  45                 </listitem>
  46             </varlistentry>
  47             <varlistentry>
  48                 <term>result_path</term>
  49                 <listitem>
  50                     <para>
  51                         a character string which gives the directory where the result has to be
  52                         written. Default value is current directory.
  53                     </para>
  54                 </listitem>
  55             </varlistentry>
  56             <varlistentry>
  57                 <term>Recmode</term>
  58                 <listitem>
  59                     <para>
  60                         Boolean flag, used by <literal>translatepaths()</literal> function for
  61                         recursive conversion. Must be %F to convert a single mfile. Default value: %F
  62                     </para>
  63                 </listitem>
  64             </varlistentry>
  65             <varlistentry>
  66                 <term>only_double</term>
  67                 <listitem>
  68                     <para>
  69                         Boolean: If %T, mfile2sci() considers that numerical functions and operators
  70                         (like "+") are used only with numerical data. This excludes for instance
  71                         instructions like <literal>"ab" + "cd"</literal> (that then will be
  72                         kept as is instead of being converted into
  73                         <literal>asciimat("ab") + asciimat("cd")</literal>).
  74                     </para>
  75                     <para>
  76                         Default value: %F: All possible conversions are done.
  77                     </para>
  78                 </listitem>
  79             </varlistentry>
  80             <varlistentry>
  81                 <term>verbose_mode</term>
  82                 <listitem>
  83                     <para> display information mode</para>
  84                     <table border="0">
  85                         <tr valign="top">
  86                             <th>0 : </th>
  87                             <td>no information displayed</td>
  88                         </tr>
  89                         <tr valign="top">
  90                             <th>1 : </th>
  91                             <td>
  92                                 information is written as comments in resulting SCI-file.
  93                             </td>
  94                         </tr>
  95                         <tr valign="top">
  96                             <th>2 : </th>
  97                             <td>
  98                                 information is written as comments in resulting SCI-file
  99                                 and in logfile.
 100                             </td>
 101                         </tr>
 102                         <tr valign="top">
 103                             <th>[3] : </th>
 104                             <td>
 105                                 information is written as comments in resulting SCI-file,
 106                                 in logfile and displayed in Scilab window. (Default value)
 107                             </td>
 108                         </tr>
 109                     </table>
 110                 </listitem>
 111             </varlistentry>
 112             <varlistentry>
 113                 <term>prettyprintoutput</term>
 114                 <listitem>
 115                     <para>Boolean flag, if %T generated code is beautified. Default value: %F</para>
 116                 </listitem>
 117             </varlistentry>
 118         </variablelist>
 119     </refsection>
 120     <refsection>
 121         <title>Description</title>
 122         <para>
 123             M2SCI (and particularly mfile2sci) is Matlab M-file to Scilab function conversion tools.
 124             It tries whenever possible to replace call to Matlab functions by the equivalent
 125             Scilab primitives and functions.
 126         </para>
 127         <para>
 128             To convert a Matlab M-file just enter the Scilab instruction:
 129             <literal>mfile2sci(file)</literal>
 130         </para>
 131         <para>
 132             where file is a character string giving the path name of the M-file.
 133         </para>
 134         <para>
 135             <literal>mfile2sci(..)</literal> will then generate three files in the same directory:
 136         </para>
 137         <para>
 138             <table border="0">
 139                 <tr valign="top">
 140                     <td><emphasis role="bold">&lt;function-name>.sci</emphasis></td>
 141                     <td>The result of the translation of the M-file in Scilab language.</td>
 142                 </tr>
 143                 <tr valign="top">
 144                     <td><emphasis role="bold">&lt;function-name>.cat</emphasis></td>
 145                     <td>the Scilab help file associated to the function</td>
 146                 </tr>
 147                 <tr valign="top">
 148                     <td><emphasis role="bold">sci_&lt;function-name>.sci</emphasis></td>
 149                     <td>
 150                         The Scilab function required to convert the calls to this Matlab M-file
 151                         in other Matlab M-files. This function may be improved "by hand".
 152                         This function is only useful for conversion not for use of translated
 153                         functions.
 154                     </td>
 155                 </tr>
 156             </table>
 157         </para>
 158         <para>
 159             Some functions like eye, ones, size, sum,... behave differently according to the
 160             dimension of their arguments. When mfile2sci cannot infer dimensions it replaces
 161             these function call by a call to an emulation function named mtlb_&lt;function_name>.
 162             For efficiency, these functions may be replaced by the proper scilab equivalent
 163             instructions.
 164             To get information about replacement, enter:
 165             <literal>help mtlb_&lt;function_name></literal> in Scilab command window
 166         </para>
 167         <para>
 168             Some other functions like plot, has no straightforward equivalent in scilab.
 169             They are also replaced by an emulation function named
 170             <literal>mtlb_&lt;function_name></literal>.
 171         </para>
 172         <para>
 173             When translation may be incorrect or may be improved mfile2sci adds a
 174             comment which begins by "//!" (according to verbose_mode)
 175         </para>
 176         <note>
 177             <literal>mfile2sci()</literal> without input argument launches a GUI allowing to
 178             select a file/directory, and to configure and run the converter:
 179             <programlisting role="example"><![CDATA[
 180 mfile2sci()
 181             ]]></programlisting>
 182         </note>
 183     </refsection>
 184     <refsection>
 185         <title>Examples</title>
 186         <programlisting role="example"><![CDATA[
 187 // Create a simple M-file
 188 rot90m = ["function B = rot90(A,k)"
 189     "if ~isa(A, ''double'')"
 190     "    error(''rot90: Wrong type for input argument #1: Real or complex matrix expected.'');"
 191     "    return"
 192     "end"
 193     "[m,n] = size(A);"
 194     "if nargin == 1"
 195     "    k = 1;"
 196     "else"
 197     "    if ~isa(k, ''double'')"
 198     "        error(''rot90: Wrong type for input argument #2: A real expected.'');"
 199     "        return"
 200     "    end"
 201     "    k = rem(k,4);"
 202     "    if k < 0"
 203     "        k = k + 4;"
 204     "    end"
 205     "end"
 206     "if k == 1"
 207     "    A = A.'';"
 208     "    B = A(n:-1:1,:);"
 209     "elseif k == 2"
 210     "    B = A(m:-1:1,n:-1:1);"
 211     "elseif k == 3"
 212     "    B = A(m:-1:1,:);"
 213     "    B = B.'';"
 214     "else"
 215     "    B = A;"
 216     "end"];
 217 mputl(rot90m, TMPDIR + "/rot90.m")
 218
 219 // Convert it to scilab language
 220 mfile2sci(TMPDIR + "/rot90.m",TMPDIR)
 221
 222 // Show the new code
 223 editor(TMPDIR + "/rot90.sci")
 224
 225 // Compile it in scilab
 226 exec(TMPDIR+'/rot90.sci')
 227
 228 // Call & use it
 229 m = rand(4,2);
 230 rot90(m,1)
 231  ]]></programlisting>
 232     </refsection>
 233     <refsection role="see also">
 234         <title>See also</title>
 235         <simplelist type="inline">
 236             <member>
 237                 <link linkend="translatepaths">translatepaths</link>
 238             </member>
 239         </simplelist>
 240     </refsection>
 241     <refsection role="history">
 242         <title>History</title>
 243         <revhistory>
 244             <revision>
 245                 <revnumber>6.0.2</revnumber>
 246                 <revdescription>
 247                     The <varname>only_double</varname> option is now %F by default.
 248                 </revdescription>
 249             </revision>
 250         </revhistory>
 251     </refsection>
 252 </refentry>