Changes to make our project as welcoming as possible for new contributors.

Changes include:
1) Added CONTRIBUTING.md with detailed instructions for how to contribute, which should be especially useful to those new to open source in general or GitHub in particular
2) Added CODE_OF_CONDUCT.md which sets ground rules for participants’ behavior and helps to facilitate a friendly, welcoming environment
3) Renamed the "example" directory to "examples" in the hope that one day soon there may be more than a single example ;-)

4 files changed, 127 insertions, 0 deletions

diff --git a/examples/example.py b/examples/example.py
new file mode 100755
index 00000000..f39be5de
--- /dev/null
+++ b/examples/example.py
@@ -0,0 +1,53 @@
+#!/usr/bin/env python
+# coding=utf-8
+"""A sample application for cmd2.
+
+Thanks to cmd2's built-in transtript testing capability, it also serves as a test suite for example.py when used with
+ the exampleSession.txt transcript.
+
+Running `python example.py -t exampleSession.txt` will run all the commands in the transcript against example.py,
+verifying that the output produced matches the transcript.
+"""
+
+from cmd2 import Cmd, make_option, options
+
+
+class CmdLineApp(Cmd):
+    """ Example cmd2 application. """
+    multilineCommands = ['orate']
+    Cmd.shortcuts.update({'&': 'speak'})
+    maxrepeats = 3
+    Cmd.settable.append('maxrepeats')
+
+    # Setting this true makes it run a shell command if a cmd2/cmd command doesn't exist
+    # default_to_shell = True
+
+    def __init__(self):
+        # Set use_ipython to True to enable the "ipy" command which embeds and interactive IPython shell
+        Cmd.__init__(self, use_ipython=False)
+
+    @options([make_option('-p', '--piglatin', action="store_true", help="atinLay"),
+              make_option('-s', '--shout', action="store_true", help="N00B EMULATION MODE"),
+              make_option('-r', '--repeat', type="int", help="output [n] times")
+              ])
+    def do_speak(self, arg, opts=None):
+        """Repeats what you tell me to."""
+        arg = ''.join(arg)
+        if opts.piglatin:
+            arg = '%s%say' % (arg[1:], arg[0])
+        if opts.shout:
+            arg = arg.upper()
+        repetitions = opts.repeat or 1
+        for i in range(min(repetitions, self.maxrepeats)):
+            self.stdout.write(arg)
+            self.stdout.write('\n')
+            # self.stdout.write is better than "print", because Cmd can be
+            # initialized with a non-standard output destination
+
+    do_say = do_speak  # now "say" is a synonym for "speak"
+    do_orate = do_speak  # another synonym, but this one takes multi-line input
+
+
+if __name__ == '__main__':
+    c = CmdLineApp()
+    c.cmdloop()
diff --git a/examples/exampleSession.txt b/examples/exampleSession.txt
new file mode 100644
index 00000000..a4eef91f
--- /dev/null
+++ b/examples/exampleSession.txt
@@ -0,0 +1,69 @@
+(Cmd) help
+
+Documented commands (type help <topic>):
+========================================
+_relative_load  edit  help     list  orate  py    run   say  shell      show
+cmdenvironment  eof   history  load  pause  quit  save  set  shortcuts  speak
+
+(Cmd) help say
+Repeats what you tell me to.
+Usage: speak [options] arg
+
+Options:
+  -h, --help            show this help message and exit
+  -p, --piglatin        atinLay
+  -s, --shout           N00B EMULATION MODE
+  -r REPEAT, --repeat=REPEAT
+                        output [n] times
+
+(Cmd) say goodnight, Gracie
+goodnight, Gracie
+(Cmd) say -ps --repeat=5 goodnight, Gracie
+OODNIGHT, GRACIEGAY
+OODNIGHT, GRACIEGAY
+OODNIGHT, GRACIEGAY
+(Cmd) set maxrepeats 5
+maxrepeats - was: 3
+now: 5
+(Cmd) say -ps --repeat=5 goodnight, Gracie
+OODNIGHT, GRACIEGAY
+OODNIGHT, GRACIEGAY
+OODNIGHT, GRACIEGAY
+OODNIGHT, GRACIEGAY
+OODNIGHT, GRACIEGAY
+(Cmd) hi
+-------------------------[1]
+help
+-------------------------[2]
+help say
+-------------------------[3]
+say goodnight, Gracie
+-------------------------[4]
+say -ps --repeat=5 goodnight, Gracie
+-------------------------[5]
+set maxrepeats 5
+-------------------------[6]
+say -ps --repeat=5 goodnight, Gracie
+(Cmd) run 4
+say -ps --repeat=5 goodnight, Gracie
+
+OODNIGHT, GRACIEGAY
+OODNIGHT, GRACIEGAY
+OODNIGHT, GRACIEGAY
+OODNIGHT, GRACIEGAY
+OODNIGHT, GRACIEGAY
+(Cmd) orate Four score and
+> seven releases ago
+> our BDFL
+> blah blah blah
+Four score and
+seven releases ago
+our BDFL
+blah blah blah
+(Cmd) & look, a shortcut!
+look, a shortcut!
+(Cmd) set prompt "---> "
+prompt - was: (Cmd)
+now: --->
+---> say goodbye
+goodbye
diff --git a/examples/script.py b/examples/script.py
new file mode 100644
index 00000000..7d0c998a
--- /dev/null
+++ b/examples/script.py
@@ -0,0 +1,3 @@
+#!/usr/bin/env python
+print("This is a python script running ...")
+
diff --git a/examples/script.txt b/examples/script.txt
new file mode 100644
index 00000000..1e18262a
--- /dev/null
+++ b/examples/script.txt
@@ -0,0 +1,2 @@
+help
+help history