Updated documentation and examples

Added information related to the new pyscript command.

The old way of running Python scripts via "py run()" should be considered deprecated.  The new "pyscript" command
is superior in two significant ways:
1) It supports tab-completion of file system paths
2) It allows the user to pass command-line arguments to scripts

3 files changed, 27 insertions, 16 deletions

diff --git a/examples/arg_printer.py b/examples/arg_printer.py
index 42084d4e..848dcf99 100755
--- a/examples/arg_printer.py
+++ b/examples/arg_printer.py
@@ -1,6 +1,8 @@
 #!/usr/bin/env python
 # coding=utf-8
+import os
 import sys
-print("Running Python script {!r} which was called with {} arguments".format(sys.argv[0], len(sys.argv) - 1))
+print("Running Python script {!r} which was called with {} arguments".format(os.path.basename(sys.argv[0]),
+                                                                             len(sys.argv) - 1))
 for i, arg in enumerate(sys.argv[1:]):
     print("arg {}: {!r}".format(i+1, arg))
diff --git a/examples/python_scripting.py b/examples/python_scripting.py
index baa15f3f..6c64dd9f 100755
--- a/examples/python_scripting.py
+++ b/examples/python_scripting.py
@@ -9,8 +9,8 @@ learn to create scripts.
 
 However, there comes a time when technical end users want more capability and power.  In particular it is common that
 users will want to create a script with conditional control flow - where the next command run will depend on the results
-from the previous command.  This is where the ability to run Python scripts inside a cmd2 application via the py command
-and the "py run('myscript.py')" syntax comes into play.
+from the previous command.  This is where the ability to run Python scripts inside a cmd2 application via the pyscript
+command and the "pyscript <script> [arguments]" syntax comes into play.
 
 This application and the "script_conditional.py" script serve as an example for one way in which this can be done.
 """
diff --git a/examples/script_conditional.py b/examples/script_conditional.py
index f0ded920..c26bd5fe 100644
--- a/examples/script_conditional.py
+++ b/examples/script_conditional.py
@@ -4,27 +4,36 @@ This is a Python script intended to be used with the "python_scripting.py" cmd2
 
 To run it you should do the following:
     ./python_scripting.py
-    py run('script_conditional.py')
+    pyscript script_conditional.py directory_path
 
 Note: The "cmd" function is defined within the cmd2 embedded Python environment and in there "self" is your cmd2
 application instance.
 """
+import os
+import sys
 
-# Try to change to a non-existent directory
-cmd('cd foobar')
+
+if len(sys.argv) > 1:
+    directory = sys.argv[1]
+    print('Using specified directory: {!r}'.format(directory))
+else:
+    directory = 'foobar'
+    print('Using default directory: {!r}'.format(directory))
+
+# Keep track of where we stared
+original_dir = os.getcwd()
+
+# Try to change to the specified directory
+cmd('cd {}'.format(directory))
 
 # Conditionally do something based on the results of the last command
 if self._last_result:
-    print('Contents of foobar directory:')
-    cmd('dir')
+    print('\nContents of directory {!r}:'.format(directory))
+    cmd('dir -l')
 
     # Change back to where we were
-    cmd('cd ..')
+    print('Changing back to original directory: {!r}'.format(original_dir))
+    cmd('cd {}'.format(original_dir))
 else:
-    # Change to parent directory
-    cmd('cd ..')
-    print('Contents of parent directory:')
-    cmd('dir')
-
-    # Change back to where we were
-    cmd('cd examples')
+    # cd command failed, print a warning
+    print('Failed to change directory to {!r}'.format(directory))