Merge pull request #431 from IotaSpencer/devel

Document utils.IRCParser() (closes #420)

docs/technical/using-ircparser.md

@@ -0,0 +1,128 @@
+# Using utils.IRCParser()
+
+**As of 22/02/2017 PyLink allows plugin creators to either parse command arguments themselves
+or use a sub-classed instance of [argparse.ArgumentParser()](https://docs.python.org/3/library/argparse.html)
+to parse their arguments.**
+
+First off, you will already have access to IRCParser due to importing `utils`.
+
+Otherwise, this is how to include it..
+
+```python
+from pylinkirc import utils
+```
+
+When you add a command that you want to use `utils.IRCParser()` on,
+the following is a guide on how to add arguments.
+
+**Note**: Most if not all the examples are from Python's argparse documentation, linked above.
+
+#### Flag Arguments / 'Switch' Arguments
+```python
+
+SomeParser = utils.IRCParser()
+SomeParser.addargument('-a', '--argumentname')
+
+```
+
+#### Named Arguments / Positional Arguments
+
+```python
+SomeParser.add_argument('argname')
+```
+
+##### Action
+
+Actions define what to do when given an argument, whether it is used by itself or with some sort of value.
+
+`argparse` defines the following Actions.
+
+* `store` - just stores the value given. This is the default when an action isn't provided.
+    ```python
+    >>> parser = argparse.ArgumentParser()
+    >>> parser.add_argument('--foo')
+    >>> parser.parse_args('--foo 1'.split())
+    Namespace(foo='1')
+    ```
+
+* `store_true`/`store_false` - used when you just want to check if an argument was used.
+
+    ```python
+    >>> parser = argparse.ArgumentParser()
+    >>> parser.add_argument('--foo', action='store_true')
+    >>> parser.add_argument('--bar', action='store_false')
+    >>> parser.add_argument('--baz', action='store_false')
+    
+    >>> parser.parse_args('--foo --bar'.split())
+    Namespace(foo=True, bar=False, baz=True)
+    ```
+
+* `append`
+
+    ```python
+    >>> parser = argparse.ArgumentParser()
+    >>> parser.add_argument('--foo', action='append')
+    >>> parser.parse_args('--foo 1 --foo 2'.split())
+    Namespace(foo=['1', '2'])
+    ```
+
+* `count` - counts how many times an argument was used (flag/switch arguments only)
+    ```python
+    >>> parser = argparse.ArgumentParser()
+    >>> parser.add_argument('--verbose', '-v', action='count')
+    >>> parser.parse_args(['-vvv'])
+    Namespace(verbose=3)
+    ```
+
+Others exist, but are not particularly useful for the level of this guide.
+
+You can also specify an arbitrary `Action` by sub-classing Action. If you want
+to do this, you must `import argparse` in your plugin.
+
+More info on that is available [here](https://docs.python.org/3/library/argparse.html#action).
+
+##### Type Constraints
+
+If you want an argument to be of a certain type, you can include a `type=TYPE` keyword, done like so.
+
+```python
+SomeParser.add_argument('argname', type=int)
+
+```
+
+As such this will return an error if the input can not be converted to an `int`.
+
+Types usable are `str` and `int`,
+there may be more that are allowed in this keyword argument,
+but `str` and `int` are the only ones we have throughly used.
+
+**Note**: TYPE can be technically any callable. More about that [here](https://docs.python.org/3/library/argparse.html#type)!
+
+
+
+##### Choices
+If you want to limit what the user can enter for an argument,
+like if they have to choose something from a pre-existing list.
+
+This can be used by adding `choices=['A', 'AAAA', 'CNAME']` into the
+`SomeParser.add_argument()` call along with the option entries (-a/--argname).
+
+```python
+SomeParser.add_argument('argname', choices=['A', 'AAAA', 'CNAME'])
+
+```
+
+##### Needed Args (aka. nargs)
+
+The keyword argument `nargs` or Needed Args associates a different number of arguments to an action.
+
+* `N` - this is an integer, N arguments will be gathered into a list. nargs=1 produces a list of one item, while the default (not using nargs) produces just the argument itself.
+
+* `'?'` - One argument will be used, if `default` is defined in the call, then default will be used if there is no given argument.
+
+* `'*'` - All arguments are gathered into a list, while its *possible* to have multiple arguments with '*' it just doesn't make sense.
+
+* `'+'` - Like '*' but raises an error if there wasn't at least one argument given.
+
+* `utils.IRCParser.REMAINDER` - remaining arguments are gathered into a list, this is usually used when you need to get a phrase stored, such as the 'quote' text of a quote, a service bot part reason, and others.
+

docs/technical/writing-plugins.md

@@ -38,10 +38,13 @@ Each command function takes 3 arguments: `irc, source, args`.
 - **source**: The numeric of the sender. This will usually be a UID (for users) or a SID (for server).
 - **args**: A `list` of space-separated command arguments (excluding the command name) that the command was called with. For example, `/msg PyLink hello world 1234` would give an `args` list of `['world', '1234']`
 
-(Unfortunately, this means that for now, any fancy argument parsing has to be done manually.)
+With the inclusion of argparse. PyLink is able to parse arguments two ways. You can either use argparse and be really fancy with your argument parsing, or you can do your own parsing just by using the regular `args` list.
+More information on using `utils.IRCParser()` can be found in 
+[using IRCParser](using-ircparser.md)
 
 Command handlers do not return anything and can raise exceptions, which are caught by the core and automatically return an error message.
 
+
 ## Sending data to IRC
 
 Plugins receive data from the underlying protocol module, and communicate back using outgoing [command functions](pmodule-spec.md) implemented by the protocol module. They should *never* send raw data directly back to IRC, because that wouldn't be portable across different IRCds.