From bd1c6660079398a406d2160dd6869ea2bb9b25d0 Mon Sep 17 00:00:00 2001
From: Todd Leonhardt <todd.leonhardt@gmail.com>
Date: Sun, 3 Nov 2019 18:03:48 -0500
Subject: Improved documentation for Argument Parsing and Tab-Completion

Also:
- Added a couple examples
---
 examples/arg_decorators.py | 59 ++++++++++++++++++++++++++++++++++++++++++++++
 examples/basic.py          | 43 +++++++++++++++++++++++++++++++++
 2 files changed, 102 insertions(+)
 create mode 100755 examples/arg_decorators.py
 create mode 100755 examples/basic.py

(limited to 'examples')

diff --git a/examples/arg_decorators.py b/examples/arg_decorators.py
new file mode 100755
index 00000000..a085341d
--- /dev/null
+++ b/examples/arg_decorators.py
@@ -0,0 +1,59 @@
+#!/usr/bin/env python3
+# coding=utf-8
+"""An example demonstrating how use one of cmd2's argument parsing decorators"""
+import argparse
+import os
+
+import cmd2
+
+
+class ArgparsingApp(cmd2.Cmd):
+    def __init__(self):
+        super().__init__(use_ipython=True)
+        self.intro = 'cmd2 has awesome decorators to make it easy to use Argparse to parse command arguments'
+
+    # do_fsize parser
+    fsize_parser = cmd2.Cmd2ArgumentParser(description='Obtain the size of a file')
+    fsize_parser.add_argument('-c', '--comma', action='store_true',
+                              help='add comma for thousands separator')
+    fsize_parser.add_argument('-u', '--unit', choices=['MB', 'KB'], help='unit to display size in')
+    fsize_parser.add_argument('file_path', help='path of file',
+                              completer_method=cmd2.Cmd.path_complete)
+
+    @cmd2.with_argparser(fsize_parser)
+    def do_fsize(self, args: argparse.Namespace) -> None:
+        """Obtain the size of a file"""
+        expanded_path = os.path.expanduser(args.file_path)
+
+        try:
+            size = os.path.getsize(expanded_path)
+        except OSError as ex:
+            self.perror("Error retrieving size: {}".format(ex))
+            return
+
+        if args.unit == 'KB':
+            size /= 1024
+        elif args.unit == 'MB':
+            size /= 1024 * 1024
+        else:
+            args.unit = 'bytes'
+        size = round(size, 2)
+
+        if args.comma:
+            size = '{:,}'.format(size)
+        self.poutput('{} {}'.format(size, args.unit))
+
+    # do_pow parser
+    pow_parser = argparse.ArgumentParser()
+    pow_parser.add_argument('base', type=int)
+    pow_parser.add_argument('exponent', type=int, choices=range(-5, 6))
+
+    @cmd2.with_argparser(pow_parser)
+    def do_pow(self, args: argparse.Namespace) -> None:
+        """Raise an integer to a small integer exponent, either positive or negative"""
+        self.poutput('{} ** {} == {}'.format(args.base, args.exponent, args.base ** args.exponent))
+
+
+if __name__ == '__main__':
+    app = ArgparsingApp()
+    app.cmdloop()
diff --git a/examples/basic.py b/examples/basic.py
new file mode 100755
index 00000000..75672a6b
--- /dev/null
+++ b/examples/basic.py
@@ -0,0 +1,43 @@
+#!/usr/bin/env python3
+# coding=utf-8
+"""A simple example demonstrating the following:
+    1) How to add a command
+    2) How to add help for that command
+    3) Persistent history
+    4) How to run an initialization script at startup
+    5) How to add custom command aliases using the alias command
+    6) Shell-like capabilities
+"""
+import cmd2
+from cmd2 import style
+
+
+class BasicApp(cmd2.Cmd):
+    CUSTOM_CATEGORY = 'My Custom Commands'
+
+    def __init__(self):
+        super().__init__(multiline_commands=['echo'], persistent_history_file='cmd2_history.dat',
+                         startup_script='scripts/startup.txt', use_ipython=True)
+
+        self.intro = style('Welcome to PyOhio 2019 and cmd2!', fg='red', bg='white', bold=True) + ' 😀'
+
+        # Allow access to your application in py and ipy via self
+        self.locals_in_py = True
+
+        # Set the default category name
+        self.default_category = 'cmd2 Built-in Commands'
+
+    @cmd2.with_category(CUSTOM_CATEGORY)
+    def do_intro(self, _):
+        """Display the intro banner"""
+        self.poutput(self.intro)
+
+    @cmd2.with_category(CUSTOM_CATEGORY)
+    def do_echo(self, arg):
+        """Example of a multiline command"""
+        self.poutput(arg)
+
+
+if __name__ == '__main__':
+    app = BasicApp()
+    app.cmdloop()
-- 
cgit v1.2.1