doc: document selectors

README.md

@@ -14,6 +14,7 @@ PBot is a versatile IRC Bot written in Perl
     * [Substitution](#substitution)
     * [Chaining](#chaining)
     * [Variables](#variables)
+    * [Selectors](#selectors)
     * [Inline invocation](#inline-invocation)
     * [Background processing](#background-processing)
   * [Extensible](#extensible)
@@ -145,6 +146,12 @@ combine their effects.
     <pragma-> !echo $greeting:uc
        <PBot> HELLO, WORLD
 
+#### Selectors
+You can select a random item from a selection list and interpolate the value within commands.
+
+    <pragma-> !echo This is a %(neat|cool|awesome) bot.
+       <PBot> This is a cool bot.
+
 #### Inline invocation
 You can invoke up to three commands inlined within a message.  If the message
 is addressed to a nick, the output will also be addressed to them.

doc/Commands.md

@@ -10,6 +10,7 @@
   * [Piping](#piping)
   * [Substitution](#substitution)
   * [Variables](#variables)
+  * [Selectors](#selectors)
   * [Background processing](#background-processing)
 * [Types of commands](#types-of-commands)
   * [Built-in commands](#built-in-commands)
@@ -295,6 +296,25 @@ combine their effects.
     <pragma-> !echo $greeting:uc
        <PBot> HELLO, WORLD
 
+### Selectors
+You can select a random item from a selection list and interpolate the value within commands.
+
+The syntax for selectors is:
+
+    %(<list of selections>)[:modifiers]
+
+`<list of selections>` is a list of items separated by a vertical bar.
+
+`[:modifiers]` is an optional list of modifiers, each prefixed with a colon. See [expansion-modifiers](Factoids.md#expansion-modifiers).
+
+Examples:
+
+    <pragma-> !echo This is a %(neat|cool|awesome) bot.
+       <PBot> This is a cool bot.
+
+    <pragma-> !echo IRC is %(fun|weird|confusing|amazing):pick_unique(2):enumerate
+       <PBot> IRC is weird and fun
+
 ### Background processing
 Any command can be flagged to be executed as a background process. For example, suppose you
 make a Plugin that has a command that may potentially take a long time to complete, which could

doc/README.md

@@ -42,6 +42,7 @@
     * [Piping](Commands.md#piping)
     * [Substitution](Commands.md#substitution)
     * [Variables](Commands.md#variables)
+    * [Selectors](Commands.md#selectors)
     * [Background processing](Commands.md#background-processing)
   * [Types of commands](Commands.md#types-of-commands)
     * [Built-in commands](Commands.md#built-in-commands)