diff --git a/doc/Commands.md b/doc/Commands.md index d8dce889..0cd0f643 100644 --- a/doc/Commands.md +++ b/doc/Commands.md @@ -3,11 +3,13 @@ * [Command interpreter](#command-interpreter) + * [Command invocation](#command-invocation) + * [Addressing output to users](#addressing-output-to-users) + * [Inline invocation](#inline-invocation) + * [Chaining](#chaining) * [Piping](#piping) * [Substitution](#substitution) - * [Chaining](#chaining) * [Variables](#variables) - * [Inline invocation](#inline-invocation) * [Background processing](#background-processing) * [Types of commands](#types-of-commands) * [Built-in commands](#built-in-commands) @@ -114,9 +116,118 @@ ## Command interpreter PBot has a powerful command interpreter with useful functionality. +### Command invocation +There are a number of ways to invoke commands with PBot. + +The syntax of PBot's commands largely follow Unix/POSIX conventions. + +A single command's syntax is: + + [arguments] + +`` is one token containing no whitespace, and is required as denoted by the angle brackets. + +`[arguments]` is a list of tokens which can be quoted to contain whitespace, and is optional as denoted by the square brackets. + +We will refer to this as `` throughout this documentation. + +The most straight-forward way to invoke a command is: + + + +`` is the bot's trigger sequence, defined in the `general.trigger` registry setting +(defined to be the exclamation mark by default). + +Example: + + !echo hi + hi + +You can also prefix or postfix address PBot by its nickname: + + + + +Examples: + + PBot: hello + Hi there, pragma- + + bye, PBot + Good-bye, pragma- + +### Addressing output to users +There are a number of ways to address command output to users. + +You can use the `tell` keyword: + + tell (about|the) + +Examples: + + !tell dave about echo Testing + dave: Testing + + !tell mike the time + It's Sun 31 May 2020 06:03:08 PM PDT in Los Angeles. + +You can use the `give` keyword: + + give + +Examples: + + !give dave echo Testing + dave: Testing + + !give mike time + It's Sun 31 May 2020 06:03:08 PM PDT in Los Angeles. + +You can use [#inline-invocation](inline invocation), as well -- see the next section. + +### 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. + +The syntax for inline invocation is: + + [nickname:] [text] { } [text] + +`[nickname:]` may optionally be prefixed to the message to address the command output to them. + +`[text]` is optional message text that is ignored. + +`` is the bot's command trigger; which defaults to the exclamation mark (!). + +`` is the command to invoke. + +Example: + + newuser13: Check the !{version} and the !{help} documentation. + newuser13: PBot version 2696 2020-01-04 + newuser13: To learn all about me, see https://github.com/pragma-/pbot/tree/master/doc + +### Chaining +You can execute multiple commands sequentially as one command. + +The syntax for chaining is: + + ;;; [...] + +Example: + + !echo Test! ;;; me smiles. ;;; version + Test! * PBot smiles. PBot version 2696 2020-01-04 + ### Piping You can pipe output from one command as input into another command, indefinitely. +The syntax for piping is: + + | { } [...] + +Example: + !echo hello world | {sed s/world/everybody/} | {uc} HELLO EVERYBODY @@ -124,17 +235,21 @@ You can pipe output from one command as input into another command, indefinitely You can insert the output from another command at any point within a command. This substitutes the command with its output at the point where the command was used. +The syntax for substitution is: + + } > + +Example: + !echo This is &{echo a demonstration} of command substitution This is a demonstration of command substitution -For example, suppose you want to make a Google Image Search command. The naive -way would be to simply do: +Suppose you want to make a Google Image Search command. The naive way would be to simply do: !factadd img /call echo https://google.com/search?tbm=isch&q=$args -Unfortuately this would not support queries containing spaces or certain symbols. But -never fear! We can use command substitution and the `uri_escape` function from the -`func` command. +Unfortuately this would not support queries containing spaces or certain symbols. To fix this, +We can use command substitution and the `uri_escape` function from the `func` command. Note that you must escape the command substitution to insert it literally into the factoid otherwise it will be expanded first. @@ -144,12 +259,6 @@ factoid otherwise it will be expanded first. !img spaces & stuff https://google.com/search?tbm=isch&q=spaces%20%26%20stuff -### Chaining -You can execute multiple commands sequentially as one command. - - !echo Test! ;;; me smiles. ;;; version - Test! * PBot smiles. PBot version 2696 2020-01-04 - ### Variables You can use factoids as variables and interpolate them within commands. @@ -164,14 +273,6 @@ combine their effects. !echo $greeting:uc HELLO, WORLD -### 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. - - newuser13: Check the !{version} and the !{help} documentation. - newuser13: PBot version 2696 2020-01-04 - newuser13: To learn all about me, see https://github.com/pragma-/pbot/tree/master/doc - ### 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 diff --git a/doc/README.md b/doc/README.md index 39722b94..539875c9 100644 --- a/doc/README.md +++ b/doc/README.md @@ -35,11 +35,13 @@ * [Commands](Commands.md#commands) * [Command interpreter](Commands.md#command-interpreter) + * [Command invocation](Commands.md#command-invocation) + * [Addressing output to users](Commands.md#addressing-output-to-users) + * [Inline invocation](Commands.md#inline-invocation) + * [Chaining](Commands.md#chaining) * [Piping](Commands.md#piping) * [Substitution](Commands.md#substitution) - * [Chaining](Commands.md#chaining) * [Variables](Commands.md#variables) - * [Inline invocation](Commands.md#inline-invocation) * [Background processing](Commands.md#background-processing) * [Types of commands](Commands.md#types-of-commands) * [Built-in commands](Commands.md#built-in-commands)