diff --git a/docs/advanced/local_bots.md b/docs/advanced/local_bots.md index 2628a85..52d6840 100644 --- a/docs/advanced/local_bots.md +++ b/docs/advanced/local_bots.md @@ -14,11 +14,27 @@ feel free to use our bot's in your room! ## Overview -[RSS Bot](#rss_bot) | [Reminder](#reminder) | [sed Bot](#sed_bot) | [Poll Bot](#poll_bot) | [Karma Bot](#karma_bot) | [Github Bot](#github_bot) | [Weather Bot](#weather_bot) | [Translator](#translator) | [version checker](#version_checker) | -[urbandictionary Bot](#urbandictionary_bot) | [Wolfram Alpha Bot](#wolfram_alpha_bot) | [Factorial Bot](#factorial_bot) | [Dice Bot](#dice_bot) | [XKCD](#xkcd) | [CommitStrip](#commitstrip) | [Cat Disruptor](#cat_disruptor) | [echobot [envs]](#echobot_envs) +[RSS Bot](#rss_bot) | +[Reminder](#reminder) | +[sed Bot](#sed_bot) | +[Poll Bot](#poll_bot) | +[Karma Bot](#karma_bot) | +[Github Bot](#github_bot) | +[Weather Bot](#weather_bot) | +[Translator](#translator) | +[version checker](#version_checker) | +[urbandictionary Bot](#urbandictionary_bot) | +[Wolfram Alpha Bot](#wolfram_alpha_bot) | +[Factorial Bot](#factorial_bot) | +[Dice Bot](#dice_bot) | +[XKCD](#xkcd) | +[CommitStrip](#commitstrip) | +[Cat Disruptor](#cat_disruptor) | +[echobot [envs]](#echobot_envs) -there is also [@maubot:envs.net](https://matrix.to/#/@maubot:envs.net) which includes all bots. -you can try all the bots in [#test:envs.net](https://matrix.to/#/#test:envs.net). +!!! info + there is also [@maubot:envs.net](https://matrix.to/#/@maubot:envs.net) which includes all bots. + you can try all the bots in [`#test:envs.net`](https://matrix.to/#/#test:envs.net). *** @@ -26,76 +42,315 @@ you can try all the bots in [#test:envs.net](https://matrix.to/#/#test:envs.net) **name:** [`@rss:envs.net`](https://matrix.to/#/@rss:envs.net) -a bot that posts RSS feed updates to Matrix. +A Bot that posts RSS feed updates to Matrix. **Usage:** `!rss [...]` -- subscribe - Subscribe this room to a feed. -- unsubscribe - Unsubscribe this room from a feed. -- template - Change the notification template for a subscription in this room -- notice [true/false] - Set whether or not the bot should send updates as m.notice -- subscriptions - List the subscriptions in the current room. +- `subscribe ` - Subscribe this room to a feed. +- `unsubscribe ` - Unsubscribe this room from a feed. +- `template ` - Change the notification template for a subscription in this room +- `notice [true/false]` - Set whether or not the bot should send updates as m.notice +- `subscriptions` - List the subscriptions in the current room. ## Reminder +A Bot to remind you about things. + **name:** [`@reminder:envs.net`](https://matrix.to/#/@reminder:envs.net) +**Usage:** `!remind [message]` _OR_ `!remind [...]` + +**Subcommands:** reschedule, help, list, locales, locale, timezone + +`` can be a time delta (e.g. `2 days 1.5 hours` or `friday at 15:00`) or an absolute date (e.g. `2020-03-27 15:00`). + +To set the timezone for date parsing and output for your messages, use `!remind tz `. +It's recommended to use a [TZ database name](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones), +but anything supported by Pytz will work. + +Similarly, you can set the locale for date parsing with `!remind locale `. If you +provide multiple locales, each one will be tried for parsing your input until one matches. Unlike +the timezone, the locale only affects input, not output. You can view available locales using +`!remind locales`. You can also contribute new locales by making a pull request +(see [locales.py](https://github.com/maubot/reminder/blob/master/reminder/locales.py), content warning: long regexes). + +To list your upcoming reminders, use `!remind list` + ## sed Bot +A Bot to do sed-like replacements. + **name:** [`@sed:envs.net`](https://matrix.to/#/@sed:envs.net) +Example: + +> this is a wrong txt. + +**Usage:** `s/txt/text/g` + +**sed output:** +> this is a wrong text. + ## Poll Bot +A Bot that creates a poll in a room and allows users to vote. + **name:** [`@poll:envs.net`](https://matrix.to/#/@poll:envs.net) +**Usage:** `!poll [...]` + +- `new ` - Creates a new poll with "Question" "choice" "choice" "choice" ... +- `results` - Prints out the current results of the poll +- `close` - Ends the poll + +Example: + +`!poll new "Question" "Choice1" "Choice2" "Choice3"` - Creates a new poll with given (at least 1) choices + +The user can now also create polls with line-breaks: +``` +!poll new What is my question? +Choice1 +Choice2 +Choice3 +``` + +`!poll results` - Displays the results from the poll + +`!poll close` - Ends the poll + +Users vote by adding the matching emoji to the poll (i.e. if the first choice has a :thumbsup: then in order to pick that choice the user has to react with :thumbsup:) + ## Karma Bot +A Bot that tracks the karma of users. + **name:** [`@karma:envs.net`](https://matrix.to/#/@karma:envs.net) +**Usage:** `!karma [...]` + +- `up ` - Upvote an event +- `down ` - Downvote a message +- `stats` - View global karma statistics +- `view [user ID]` - View your or another users karma +- `export` - Export the data of your karma +- `breakdown` - View your karma breakdown +- `top` - View the highest rated users +- `bottom` - View the lowest rated users +- `best` - View the highest rated messages +- `worst` - View the lowest rated messages + ## Github Bot +A GitHub client and webhook receiver for maubot. + **name:** [`@github:envs.net`](https://matrix.to/#/@github:envs.net) +**Usage:** `!github [...]` + +- `login [flags]` - Log into GitHub. +- `ping` - Check your login status. +- `raw ` - Make a raw GraphQL query. +- `create [owner/repo] ` - Create an issue. Title on first line, body on other lines +- `webhook <subcommand> [...]` - Manage webhooks. + +<br /> +1. **Use `!github login` to log in.** + + After inviting your bot / client to a matrix channel, use the `!gh` or + `!github` command to use the github instance. + + Using `gh login` first is mandatory and needed once **per instance**. + + The bot will reply with a link leading to your personal Github's allowed + OAuth apps page, where you shall grant the necessary rights to the bot + OAuth app. + + By default, the bot will request access to all public repos and to add + webhooks. You can control the permissions it wants with some flags: + + - `--no-repo` makes it not ask for repo access at all. + Only `!github webhook add` will work, other commands like `!github create` + will not. + - `--no-hook` makes it not ask for webhook access. + `!github webhook add` will not work. + - `--private` makes it ask for private repo access. Necessary if you want to + use the bot to manage private repos. + +<br /> +2. **Use `!github webhook add <owner>/<repo>` to add webhooks.** + + This will let you see in the current channel all the commits, comments, + issues, stars, forks, pull requests, and so on, for that given repository. + + You must have admin rights on the repositories you want to track, as adding + webhooks to a repository requires manager access rights to a project. + + Once you create a webhook and track a repository, it will be tracked + **only in the room from which you are in**. + ## Weather Bot +A Bot that gets the weather from [wttr.in](http://wttr.in) and returns the text to the chat + **name:** [`@weather:envs.net`](https://matrix.to/#/@weather:envs.net) +**Usage:** + +- `!weather` - Reply with the weather based on the default config value (Germany, Berlin) +- `!weather <location>` - Reply with the location for the specified `<location>` where +`<location>` can be an airport code, or a city + ## Translator +A Bot to translate words using Google Translate (DeepL is planned too) + **name:** [`@translate:envs.net`](https://matrix.to/#/@translate:envs.net) +**Usage:** `!translate <language> [text]` + +After inviting the bot to your room, simply use the `!translate` command: + +`!translate en ru Hello world.` + +which results in + +>Translator: +> > rubo77 +> > !translate en ru Hello world. + +> Привет, мир. + +You can also use the alias `tr`: + +`!tr en ru Hello world.` + +The first parameter (source language) can be set to `auto` or omitted entirely +to let Google Translate detect the source language. Additionally, you can reply +to a message with `!tr <from> <to>` (no text) to translate the message you +replied to. + +**supported languages:** + +- de: (german) +- en: (english) +- zh: (chinese) +- ... + +Full list of supported languages: [https://cloud.google.com/translate/docs/languages](https://cloud.google.com/translate/docs/languages) + ## version checker +A Bot to check the version of servers in rooms. + **name:** [`@version:envs.net`](https://matrix.to/#/@version:envs.net) +**Usage:** + +- `!servers` - Test all servers in room and report aggregated tests. +- `!servers retest <name>` - Re-test a server and update the previous results. +- `!servers match <software> [operator] <version>` - Show all servers with the + given software and version. Operator can be `>`, `<`, `>=`, `<=`, `!=`, `=` + or empty. +- `!server test <name>` - Test one server, independently of any previous whole-room tests. +- `!server`, `!version` and `!versions` are aliases for `!servers`, `recheck` + is an alias for `tetest`. + ## urbandictionary Bot +A Bot to fetch definitions from [Urban Dictionary](https://www.urbandictionary.com/). Returns a specified or random entry. + **name:** [`@urban:envs.net`](https://matrix.to/#/@urban:envs.net) +**Usage:** `!ud [term] [index]` + +Examples +``` +!ud +!ud foo +!ud foo 2 +``` + ## Wolfram Alpha Bot +a Bot to search on [Wolfram Alpha](https://www.wolframalpha.com/). + **name:** [`@wolframalpha:envs.net`](https://matrix.to/#/@wolframalpha:envs.net) +**Usage:** `!wolfram some search term` + ## Factorial Bot +A Bot that calculates expected and unexpected factorials in messages. + **name:** [`@factorial:envs.net`](https://matrix.to/#/@factorial:envs.net) +**Usage:** + +Simply type a number followed by one or more exclamation marks. Note that multiple exclamation marks means a double factorial, not a factorial applied twice. + +Example: + +`1! 2! 3!` + +> 1! = 1 +> 2! = 2 +> 3! = 6 + +`over 9000!` + +>9000! ≈ 8.09958 × 10<sup>31681</sup> + + ## Dice Bot +A Bot that rolls dice. Has built-in calculator. + **name:** [`@dice:envs.net`](https://matrix.to/#/@dice:envs.net) +**Usage:** + +The base command is `!roll`. To roll dice, pass `XdY` as an argument, where `X` +is the number of dice (optional) and `Y` is the number of sides in each dice. +Most Python math and bitwise operators and basic `math` module functions are +also supported, which means you can roll different kinds of dice and combine +the results however you like. + ## XKCD +A Bot to fetch xkcd comics and to get notifications about new comics. + **name:** [`@xkcd:envs.net`](https://matrix.to/#/@xkcd:envs.net) +**Usage:** `!xkcd [number]` _OR_ `!xkcd <subcommand> [...]` + +**Subcommands:** `reindex`, `lucky`, `search`, `subscribe`, `unsubscribe` + ## CommitStrip +A Bot to fetch [CommitStrips](https://www.commitstrip.com/en/) and to get notifications about new comics. + **name:** [`@commitstrip:envs.net`](https://matrix.to/#/@commitstrip:envs.net) +**Usage:** `!commitstrip` _OR_ `!commitstrip <subcommand> [...]` + +**Subcommands:** `search`, `subscribe`, `unsubscribe` + ## Cat Disruptor +A Bot plugin that disrupts monologues cat pictures and react to some messages. + **name:** [`@cat:envs.net`](https://matrix.to/#/@cat:envs.net) +You can use it 3 times per day with `🐈️` _(\:cat2:)_. + ## echobot [envs] +A simple Bot that echoes pings and other stuff. + **name:** [`@echo:envs.net`](https://matrix.to/#/@echo:envs.net) + +**Usage:** + +- `!ping` - Reply with "Pong!" and the time it took for the message to reach the bot. +- `!echo <message>` - Reply with the given message