From 881b2ba17b30a485cf60079911aaa641aecce630 Mon Sep 17 00:00:00 2001 From: Pragmatic Software Date: Thu, 9 Jan 2020 16:59:09 -0800 Subject: [PATCH] README.md: add more stuff --- README.md | 143 +++++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 120 insertions(+), 23 deletions(-) diff --git a/README.md b/README.md index 9f273aee..b2eaf63e 100644 --- a/README.md +++ b/README.md @@ -3,21 +3,27 @@ PBot PBot is a versatile IRC Bot written in Perl -* [Installation / Quick Start](#installation--quick-start) -* [Documentation](#documentation) -* [Features](#features) - * [Commands](#commands) - * [Plugins](#plugins) - * [Factoids](#factoids) - * [Code Factoids](#code-factoids) - * [Modules](#modules) - * [Useful IRC command improvements](#useful-irc-command-improvements) - * [Channel management](#channel-management) - * [Admin management](#admin-management) - * [Easy configuration](#easy-configuration) - * [Advanced interpreter](#advanced-interpreter) -* [Support](#support) -* [License](#license) + * [Installation / Quick Start](#installation--quick-start) + * [Documentation](#documentation) + * [Features](#features) + * [Commands](#commands) + * [Plugins](#plugins) + * [Factoids](#factoids) + * [Code Factoids](#code-factoids) + * [Modules](#modules) + * [Virtual machine](#virtual-machine) + * [Useful IRC command improvements](#useful-irc-command-improvements) + * [Channel management](#channel-management) + * [Admin management](#admin-management) + * [Easy configuration](#easy-configuration) + * [Advanced interpreter](#advanced-interpreter) + * [piping](#piping) + * [command substitution](#command-substitution) + * [command splitting](#command-splitting) + * [$variable interpolation](#variable-interpolation) + * [inline commands](#inline-commands) + * [Support](#support) + * [License](#license) Installation / Quick Start @@ -73,6 +79,7 @@ At its most simple, factoids merely output the text the creator sets. !factadd hello /say Hello, $nick! hello added to global channel. + PBot, hello Hello, pragma-! @@ -94,7 +101,7 @@ For more information, see the [Factoids documentation](doc/Factoids.md). ### Code Factoids -Code factoids are a special type of factoid that begin with the `/code` command. +Code Factoids are a special type of factoid that begin with the `/code` command. /code @@ -104,6 +111,19 @@ That's right! Anybody can create a factoid that can execute arbitrary code in How is this safe? Because the code is executed within a virtual machine that has been configured to fall-back to a previously saved state whenever it times out. +For example, the venerable `rot13` function: + + !factadd rot13 /code sh echo "$@" | tr a-zA-Z n-za-mN-ZA-M + rot13 added to global channel. + + !rot13 Pretty neat, huh? + Cerggl arng, uhu? + +You can pipe output from other commands to Code Factoids. + + !echo test | {rot13} + grfg + For more information, see the [Code Factoid documentation](doc/Factoids.md#code). ### Modules @@ -148,6 +168,33 @@ Module | Description For more information, see the [Modules documentation](doc/Modules.md). +### Virtual machine + +PBot can integrate with a virtual machine to safely execute arbitrary user-submitted +commands or code. + +PBot supports [several shells and languages](doc/Factoids.md#supported-languages) out of the box! + + !sh echo Remember rot13? | tr a-zA-Z n-za-mN-ZA-M + Erzrzore ebg13? + +PBot has extensive support for the C programming language. For instance, the C programming language +plugin is integrated with the GNU Debugger. It will print useful debugging information. + + !cc char *p = 0; *p++; + runtime error: store to null pointer of type 'char' + Program received signal SIGSEGV, Segmentation fault at + statement: *p = 1; + +It can display value of the most recent statement if there is no program output. + + !cc sizeof (int) + no output: sizeof(int) = 4 + +For more information about the C programming language plugin, see [the `cc` command in the Modules documentation.](doc/Modules.md#cc) + +For more information about the virtual machine, see the [Virtual Machine documentation.](doc/VirtualMachine.md) + ### Useful IRC command improvements * `mode` command can take wildcards, e.g. `mode +ov foo* bar*` to op nicks beginning with `foo` and voice nicks beginning with `bar` @@ -193,13 +240,63 @@ These settings can easily be configured via several methods: PBot has an advanced command interpreter with useful functionality. -* piping -* command substitution -* command separation -* inline commands -* $variable interpolation -* aliases -* and more! +#### piping + +You can pipe output from one command as input into another command, indefinitely. + + !echo hello world | {sed s/world/everybody/} | {uc} + HELLO EVERYBODY + +#### command substitution + +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. + + !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: + + !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. + +Note that you must escape the command substitution to insert it literally into the +factoid otherwise it will be expanded first. + + !factadd img /call echo https://google.com/search?tbm=isch&q=\&{func uri_escape $args} + + !img spaces & stuff + https://google.com/search?tbm=isch&q=spaces%20%26%20stuff + +#### command splitting + +You can execute multiple commands sequentially as one command. + + !echo Test! ;;; me smiles. ;;; version + Test! * PBot smiles. PBot version 2696 2020-01-04 + +#### $variable interpolation + +You can use factoids as variables and interpolate them within commands. + + !factadd greeting "Hello, world" + + !echo greeting is $greeting + greeting is Hello, world + +#### inline commands + +You can invoke up to three commands in-lined within a message. If the message +is address 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 + Support -------