* Bug 14355 fixed: powershell() was poorly documented 86/19986/4
Samuel GOUGEON [Mon, 30 Apr 2018 23:24:28 +0000 (01:24 +0200)]
  http://bugzilla.scilab.org/14355

  PDF page: http://bugzilla.scilab.org/attachment.cgi?id=4724

Change-Id: Ia432b5e271a50c46ae9f6378f39bc8a0c8483ba3

scilab/CHANGES.md
scilab/modules/windows_tools/help/en_US/powershell.xml
scilab/modules/windows_tools/tests/unit_tests/powershell.dia.ref [deleted file]
scilab/modules/windows_tools/tests/unit_tests/powershell.tst

index e65140e..8dd167e 100644 (file)
@@ -260,7 +260,7 @@ Help pages:
 * rewritten: `consolebox`, `double`, `isoview`, `pixel_drawing_mode`, `householder`, `or`, `|,||`,
  `and`, `&,&&`, `format`, `type`, `typeof`, `brackets`, `setlanguage`, `sleep`, `isinf`, `unique`,
  `bitor`, `bitxor`, `bitand`, `macr2tree`, `geomean`, `clf`, `getPreferencesValue`, `gcd`, `lcm`, `isglobal`,
- `whereis`, `mode`, `%onprompt`, `toeplitz`, `param3d`, `param3d1`, `argn`, `gettext`, `poly`,
+ `whereis`, `mode`, `%onprompt`, `toeplitz`, `param3d`, `param3d1`, `argn`, `powershell`, `gettext`, `poly`,
  `mtlb_int8`, `mtlb_int16`, `mtlb_int32`, `mtlb_int64`, `mtlb_uint8`, `mtlb_uint16`, `mtlb_uint32`, `mtlb_uint64`, `intersect`,
  `load`, `save`, `host`, `locate`, `null`
 * reorganized:
@@ -465,6 +465,7 @@ Known issues
 * [#14282](http://bugzilla.scilab.org/show_bug.cgi?id=14282): `listvarinfile(fn)` and `load(fn)` yielded some memory leak.
 * [#14296](http://bugzilla.scilab.org/show_bug.cgi?id=14296): Xcos labels moving after creating blocks using scripts crashed Scilab.
 * [#14318](http://bugzilla.scilab.org/show_bug.cgi?id=14318): There was a memory leak when writing a HDF5 file.
+* [#14355](http://bugzilla.scilab.org/show_bug.cgi?id=14355): `powershell` was poorly documented.
 * [#14460](http://bugzilla.scilab.org/show_bug.cgi?id=14460): sparse boolean indices were not supported.
 * [#14489](http://bugzilla.scilab.org/show_bug.cgi?id=14489): clicking the scinotes icon did not bring its window in the foreground.
 * [#14506](http://bugzilla.scilab.org/show_bug.cgi?id=14506): An `atomsInstallList` error message had a wrong number of input arguments.
index 9ddadaa..5fafd16 100644 (file)
@@ -2,6 +2,7 @@
 <!--
  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
  * Copyright (C) DIGITEO - Allan CORNET
+ * Copyright (C) 2018 - Samuel GOUGEON
  *
  * Copyright (C) 2012 - 2016 - Scilab Enterprises
  *
  * along with this program.
  *
  -->
-<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:lang="en" xml:id="powershell">
+<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
+        xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML"
+        xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org"
+        xml:lang="en" xml:id="powershell">
     <refnamediv>
         <refname>powershell</refname>
-        <refpurpose>shell (powershell) command execution (Windows
-            only)
+        <refpurpose>executes a command with the Windows powershell interpreter (Windows only)
         </refpurpose>
     </refnamediv>
     <refsynopsisdiv>
         <title>Syntax</title>
-        <synopsis>output=powershell(command-name)
-            [output,bOK]=powershell(command-name)
+        <synopsis>
+            output = powershell(command)
+            [output,bOK] = powershell(command)
         </synopsis>
     </refsynopsisdiv>
     <refsection>
+        <title>Arguments</title>
+        <variablelist>
+            <varlistentry>
+                <term>command</term>
+                <listitem>
+                    <para>
+                        Single text containing instructions sent to the MS Windows powershell.exe
+                        command interpreter.
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>output</term>
+                <listitem>
+                    <para>
+                        Column of text: output (and error message) yielded and normally displayed by
+                        Powershell on its screen.
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>bOK</term>
+                <listitem>
+                    <para>
+                        Single boolean: <literal>%T</literal> if <varname>command</varname> has
+                        been executed without error, <literal>%F</literal> otherwise.
+                    </para>
+                </listitem>
+            </varlistentry>
+        </variablelist>
+    </refsection>
+    <refsection>
         <title>Description</title>
-        <para>Sends a string command-name to Windows for execution by the powershell.
-            Standard output and standard errors of the shell command are written in
-            the calling shell. bOK returns if command has been executed.
+        <para>
+            <literal>powershell()</literal> opens a new session of the MS Windows
+            <emphasis>powershell.exe</emphasis> command interpreter, sends <varname>command</varname>
+            to it, lets it processing <varname>command</varname> instructions, receives as text the
+            <varname>output</varname> and possible error message yielded by the processing,
+            and closes the interpreter session.
+        </para>
+        <para>
+            The starting current working directory and environment variables of the powershell.exe
+            session are set <link linkend="host_description">as described for host()</link>.
         </para>
+        <para>
+            If an instruction in <varname>command</varname> generates an error, the error message
+            is caught and returned in <varname>output</varname>. Nothing is directly displayed
+            neither in the Scilab console nor in the <link linkend="consolebox">consolebox</link>.
+            <warning>
+                The effects of valid instructions processed before the erroneous one remain actual
+                (for instance, deleted files). However, their valid output is canceled and not
+                returned in <varname>output</varname>.
+            </warning>
+        </para>
+        <note>
+            Any path included in the <varname>command</varname> must be single-quoted.
+        </note>
     </refsection>
     <refsection>
         <title>Examples</title>
+        <para/>
+        <para>Current directory:</para>
+        <programlisting role="example"><![CDATA[
+r = powershell("pwd");
+r(4)
+
+// Directory content
+path = TMPDIR + "\rĂ©pertoire test";
+mkdir(path);
+mputl("Test of listing", path+"\test.txt");
+[r,ok] = powershell("ls ''"+path+"''"); ok   // single quotes ' needed
+rmdir(path, "s");
+     ]]></programlisting>
+        <para/>
+        <para>
+            Handling of environment variables, date:
+        </para>
         <programlisting role="example"><![CDATA[
-[s,w] = powershell('ls');
+setenv TEST ABCD;
+powershell("$env:TEST")
+
+// Current date:
+[r,ok] = powershell("get-Date -format ""yyyy-MM-dd HH:mm"""); ok  // => error
+[r,ok] = powershell("get-Date -format ''yyyy-MM-dd HH:mm''")
  ]]></programlisting>
+    <screen><![CDATA[
+--> setenv TEST ABCD;
+--> powershell("$env:TEST")
+ ans  =
+ ABCD
+
+
+--> // Current date:
+--> [r,ok] = powershell("get-Date -format ""yyyy-MM-dd HH:mm"""); ok
+ ok  =
+  F
+
+--> [r,ok] = powershell("get-Date -format ''yyyy-MM-dd HH:mm''")
+ ok  =
+  T
+ r  =
+ 2018-04-30 07:12
+]]></screen>
+        <para/>
+        <para>
+            Multiple instructions separated with ";":
+        </para>
+        <programlisting role="example"><![CDATA[
+powershell("echo $env:USERNAME'' uses powershell in Scilab'' ; Get-Date")
+ ]]></programlisting>
+    <screen><![CDATA[
+--> powershell("echo $env:USERNAME'' uses powershell in Scilab'' ; Get-Date")
+ ans  =
+!Samuel uses powershell in Scilab  !
+!                                  !
+!lundi 30 avril 2018 07:21:02      !
+!                                  !
+]]></screen>
     </refsection>
     <refsection role="see also">
         <title>See also</title>
         <simplelist type="inline">
             <member>
-                <link linkend="unix">unix</link>
+                <link linkend="host">host</link>
             </member>
             <member>
                 <link linkend="dos">dos</link>
             </member>
+            <member>
+                <link linkend="unix_g">unix_g</link>
+            </member>
         </simplelist>
     </refsection>
 </refentry>
diff --git a/scilab/modules/windows_tools/tests/unit_tests/powershell.dia.ref b/scilab/modules/windows_tools/tests/unit_tests/powershell.dia.ref
deleted file mode 100644 (file)
index a0ee706..0000000
+++ /dev/null
@@ -1,11 +0,0 @@
-// =============================================================================
-// Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
-// Copyright (C) 2009 - INRIA - Allan CORNET
-//
-//  This file is distributed under the same license as the Scilab package.
-// =============================================================================
-if getos() == 'Windows' then
-  cd('SCI/bin');
-  r = powershell('ls');
-  if r == [] then bugmes();quit;end
-end
index 710828b..c68f087 100644 (file)
@@ -1,11 +1,31 @@
 // =============================================================================
 // Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
 // Copyright (C) 2009 - INRIA - Allan CORNET
+// Copyright (C) 2018 - Samuel GOUGEON
 //
 //  This file is distributed under the same license as the Scilab package.
 // =============================================================================
+
+// Unit tests for powershell()
+
+// <-- CLI SHELL MODE -->
+// <-- NO CHECK REF -->
+
 if getos() == 'Windows' then
   cd('SCI/bin');
   r = powershell('ls');
-  if r == [] then pause,end
-end
\ No newline at end of file
+  assert_checktrue(r~=[]);
+
+  // Path with space & UTF-8 chars in command
+  path = TMPDIR+"\mon rĂ©pertoire";
+  mkdir(path);
+  mputl("Test bub 14355", path+"\test.txt");
+
+  r = powershell("ls ''"+path+"''");
+  assert_checktrue(r~=[]);
+  assert_checktrue(grep(r,"/^Mode/","r")~=[]);
+  rmdir(path,"s");
+
+  // Date quoted format
+  powershell("get-Date -format ''yyyy-MM-dd HH:mm''")
+end