using_wrap: Group converters and contexts in logical groups.

develop/using_wrap.rst

@@ -2,8 +2,7 @@
 Using commands.wrap to parse your command's arguments
 *****************************************************
 
-This document illustrates how to use the new 'wrap' function present in Supybot
+.. contents::
-0.80 to handle argument parsing and validation for your plugin's commands.
 
 Introduction
 ============
@@ -159,6 +158,14 @@ Below is a list of all the available converters to use with wrap. If the
 converter accepts any arguments, they are listed after it and if they are
 optional, the default value is shown.
 
+Numbers and time
+----------------
+
+expiry
+
+    Takes a number of seconds and adds it to the current time to create an
+    expiration timestamp.
+
 id, kind="integer"
 
     Returns something that looks like an integer ID number. Takes an optional
@@ -167,10 +174,12 @@ id, kind="integer"
     the argument be an integer, does no other integrity-checking, and provides
     a nice error message with the kind in it.
 
-ip
+index
 
-    Checks and makes sure the argument looks like a valid IP and then returns
+    Basically ("int", "index"), but with a twist. This will take a 1-based
-    it.
+    index and turn it into a 0-based index (which is more useful in code). It
+    doesn't transform 0, and it maintains negative indices as is (note that it
+    does allow them!).
 
 int, type="integer", p=None
 
@@ -179,32 +188,11 @@ int, type="integer", p=None
     to test the integer with. If p(i) fails (where i is the integer arg parsed
     out of the argument string), the arg will not be accepted.
 
-index
-
-    Basically ("int", "index"), but with a twist. This will take a 1-based
-    index and turn it into a 0-based index (which is more useful in code). It
-    doesn't transform 0, and it maintains negative indices as is (note that it
-    does allow them!).
-
-color
-
-    Accepts arguments that describe a text color code (e.g., "black", "light
-    blue") and returns the mIRC color code for that color. (Note that many
-    other IRC clients support the mIRC color code scheme, not just mIRC)
-
 now
 
     Simply returns the current timestamp as an arg, does not reference or
     modify the argument list.
 
-url
-
-    Checks for a valid URL.
-
-httpUrl
-
-    Checks for a valid HTTP URL.
-
 long, type="long"
 
     Basically the same as int minus the predicate, except that it converts the
@@ -229,45 +217,14 @@ nonNegativeInt
 
     Accepts only non-negative integers.
 
-letter
+Channel
+-------
 
-    Looks for a single letter. (Technically, it looks for any one-element
+channelDb
-    sequence).
 
-haveOp, action="do that"
+    Sets the channel appropriately in order to get to the databases for that
-
+    channel (handles whether or not a given channel uses channel-specific
-    Simply requires that the bot have ops in the channel that the command is
+    databases and whatnot).
-    called in. The action parameter completes the error message: "I need to be
-    opped to ...".
-
-expiry
-
-    Takes a number of seconds and adds it to the current time to create an
-    expiration timestamp.
-
-literal, literals, errmsg=None
-
-    Takes a required sequence or string (literals) and any argument that
-    uniquely matches the starting substring of one of the literals is
-    transformed into the full literal. For example, with ``("literal", ("bar",
-    "baz", "qux"))``, you'd get "bar" for "bar", "baz" for "baz", and "qux"
-    for any of "q", "qu", or "qux". "b" and "ba" would raise errors because
-    they don't uniquely identify one of the literals in the list. You can
-    override errmsg to provide a specific (full) error message, otherwise the
-    default argument error message is displayed.
-
-to
-
-    Returns the string "to" if the arg is any form of "to" (case-insensitive).
-
-nick
-
-    Checks that the arg is a valid nick on the current IRC server.
-
-seenNick
-
-    Checks that the arg is a nick that the bot has seen (NOTE: this is limited
-    by the size of the history buffer that the bot has).
 
 channel
 
@@ -286,84 +243,102 @@ onlyInChannel
     Requires that the command be called from within any channel that the bot
     is currently in.
 
-nickInChannel
-
-    Requires that the argument be a nick that is in the current channel, and
-    returns that nick.
-
-networkIrc, errorIfNoMatch=False
-
-    Returns the IRC object of the specified IRC network. If one isn't
-    specified, the IRC object of the IRC network the command was called on is
-    returned.
-
 callerInGivenChannel
 
     Takes the given argument as a channel and makes sure that the caller is in
     that channel.
 
-plugin, require=True
+public
 
-    Returns the plugin specified by the arg or None. If require is True, an
+    Requires that the command be sent in a channel instead of a private
-    error is raised if the plugin cannot be retrieved.
+    message.
 
-boolean
+private
 
-    Converts the text string to a boolean value. Acceptable true values are:
+    Requires that the command be sent in a private message instead of a
-    "1", "true", "on", "enable", or "enabled" (case-insensitive). Acceptable
+    channel.
-    false values are: "0", false", "off", "disable", or "disabled"
+
-    (case-insensitive).
+validChannel
+
+    Gets a channel argument once it makes sure it's a valid channel.
+
+Words
+-----
+
+color
+
+    Accepts arguments that describe a text color code (e.g., "black", "light
+    blue") and returns the mIRC color code for that color. (Note that many
+    other IRC clients support the mIRC color code scheme, not just mIRC)
+
+letter
+
+    Looks for a single letter. (Technically, it looks for any one-element
+    sequence).
+
+literal, literals, errmsg=None
+
+    Takes a required sequence or string (literals) and any argument that
+    uniquely matches the starting substring of one of the literals is
+    transformed into the full literal. For example, with ``("literal", ("bar",
+    "baz", "qux"))``, you'd get "bar" for "bar", "baz" for "baz", and "qux"
+    for any of "q", "qu", or "qux". "b" and "ba" would raise errors because
+    they don't uniquely identify one of the literals in the list. You can
+    override errmsg to provide a specific (full) error message, otherwise the
+    default argument error message is displayed.
 
 lowered
 
     Returns the argument lowered (NOTE: it is lowered according to IRC
     conventions, which does strange mapping with some punctuation characters).
 
-anything
+to
 
-    Returns anything as is.
+    Returns the string "to" if the arg is any form of "to" (case-insensitive).
 
-something, errorMsg=None, p=None
+Network
+-------
 
-    Takes anything but the empty string. errorMsg can be used to customize the
+ip
-    error message. p is any predicate function that can be used to test the
-    validity of the input.
 
-filename
+    Checks and makes sure the argument looks like a valid IP and then returns
+    it.
 
-    Used to get a filename argument.
+url
 
-commandName
+    Checks for a valid URL.
 
-    Returns the canonical command name version of the given string (ie, the
+httpUrl
-    string is lowercased and dashes and underscores are removed).
 
-text
+    Checks for a valid HTTP URL.
 
-    Takes the rest of the arguments as one big string. Note that this differs
+Users, nicks, and permissions
-    from the "anything" context in that it clobbers the arg string when it's
+-----------------------------
-    done.  Using any converters after this is most likely incorrect.
 
-glob
+haveOp, action="do that"
 
-    Gets a glob string. Basically, if there are no wildcards (``*``, ``?``) in
+    Simply requires that the bot have ops in the channel that the command is
-    the argument, returns ``*string*``, making a glob string that matches
+    called in. The action parameter completes the error message: "I need to be
-    anything containing the given argument.
+    opped to ...".
 
-somethingWithoutSpaces
+nick
 
-    Same as something, only with the exception of disallowing spaces of course.
+    Checks that the arg is a valid nick on the current IRC server.
+
+seenNick
+
+    Checks that the arg is a nick that the bot has seen (NOTE: this is limited
+    by the size of the history buffer that the bot has).
+
+nickInChannel
+
+    Requires that the argument be a nick that is in the current channel, and
+    returns that nick.
 
 capability
 
     Used to retrieve an argument that describes a capability.
 
-channelDb
-
-    Sets the channel appropriately in order to get to the databases for that
-    channel (handles whether or not a given channel uses channel-specific
-    databases and whatnot).
-
 hostmask
 
     Returns the hostmask of any provided nick or hostmask argument.
@@ -376,37 +351,10 @@ user
 
     Requires that the caller be a registered user.
 
-matches, regexp, errmsg
-
-    Searches the args with the given regexp and returns the matches. If no
-    match is found, errmsg is given.
-
-public
-
-    Requires that the command be sent in a channel instead of a private
-    message.
-
-private
-
-    Requires that the command be sent in a private message instead of a
-    channel.
-
 otherUser
 
     Returns the user specified by the username or hostmask in the argument.
 
-regexpMatcher
-
-    Gets a matching regexp argument (m// or //).
-
-validChannel
-
-    Gets a channel argument once it makes sure it's a valid channel.
-
-regexpReplacer
-
-    Gets a replacing regexp argument (s//).
-
 owner
 
     Requires that the command caller has the "owner" capability.
@@ -423,6 +371,78 @@ checkChannelCapability, capability
     Checks to make sure that the caller has the specified capability on the
     channel the command is called in.
 
+Matching
+--------
+
+anything
+
+    Returns anything as is.
+
+something, errorMsg=None, p=None
+
+    Takes anything but the empty string. errorMsg can be used to customize the
+    error message. p is any predicate function that can be used to test the
+    validity of the input.
+
+somethingWithoutSpaces
+
+    Same as something, only with the exception of disallowing spaces of course.
+
+matches, regexp, errmsg
+
+    Searches the args with the given regexp and returns the matches. If no
+    match is found, errmsg is given.
+
+regexpMatcher
+
+    Gets a matching regexp argument (m// or //).
+
+glob
+
+    Gets a glob string. Basically, if there are no wildcards (``*``, ``?``) in
+    the argument, returns ``*string*``, making a glob string that matches
+    anything containing the given argument.
+
+regexpReplacer
+
+    Gets a replacing regexp argument (s//).
+
+Other
+-----
+
+networkIrc, errorIfNoMatch=False
+
+    Returns the IRC object of the specified IRC network. If one isn't
+    specified, the IRC object of the IRC network the command was called on is
+    returned.
+
+plugin, require=True
+
+    Returns the plugin specified by the arg or None. If require is True, an
+    error is raised if the plugin cannot be retrieved.
+
+boolean
+
+    Converts the text string to a boolean value. Acceptable true values are:
+    "1", "true", "on", "enable", or "enabled" (case-insensitive). Acceptable
+    false values are: "0", false", "off", "disable", or "disabled"
+    (case-insensitive).
+
+filename
+
+    Used to get a filename argument.
+
+commandName
+
+    Returns the canonical command name version of the given string (ie, the
+    string is lowercased and dashes and underscores are removed).
+
+text
+
+    Takes the rest of the arguments as one big string. Note that this differs
+    from the "anything" context in that it clobbers the arg string when it's
+    done.  Using any converters after this is most likely incorrect.
+
 Contexts List
 =============
   What contexts are available for me to use?
@@ -431,14 +451,8 @@ The list of available contexts is below. Unless specified otherwise, it can be
 assumed that the type returned by the context itself matches the type of the
 converter it is applied to.
 
-any
+Options
-    Looks for any number of arguments matching the supplied converter. Will
+-------
-    return a sequence of converted arguments or None.
-
-many
-    Looks for multiple arguments matching the supplied converter. Expects at
-    least one to work, otherwise it will fail. Will return the sequence of
-    converted arguments.
 
 optional
     Look for an argument that satisfies the supplied converter, but if it's not
@@ -450,6 +464,30 @@ additional
     that it's the right type. If there aren't any arguments to check, then use
     the default value. Will return the converted argument as is or None.
 
+first
+    Tries each of the supplied converters in order and returns the result of
+    the first successfully applied converter.
+
+Multiplicity
+------------
+
+any
+    Looks for any number of arguments matching the supplied converter. Will
+    return a sequence of converted arguments or None.
+
+many
+    Looks for multiple arguments matching the supplied converter. Expects at
+    least one to work, otherwise it will fail. Will return the sequence of
+    converted arguments.
+
+commalist
+    Looks for a comma separated list of arguments that match the supplied
+    converter. Returns a list of the successfully converted arguments. If any
+    of the arguments fail, this whole context fails.
+
+Other
+-----
+
 rest
     Treat the rest of the arguments as one big string, and then convert. If the
     conversion is unsuccessful, restores the arguments.
@@ -461,19 +499,10 @@ getopts
     name in the dictionary. For no conversion, use None as the converter name
     in the dictionary.
 
-first
-    Tries each of the supplied converters in order and returns the result of
-    the first successfully applied converter.
-
 reverse
     Reverse the argument list, apply the converters, and then reverse the
     argument list back.
 
-commalist
-    Looks for a comma separated list of arguments that match the supplied
-    converter. Returns a list of the successfully converted arguments. If any
-    of the arguments fail, this whole context fails.
-
 
 Final Word
 ==========