Updated readme for grammar and easier reading without formatting.
This commit is contained in:
parent
b41a05e3cd
commit
1eb434f198
124
README.md
124
README.md
@ -6,7 +6,7 @@ The plugin-wielding, multipurpose Telegram bot.
|
|||||||
otouto is an independently-developed Telegram API bot written in Lua. Originally conceived as a CLI script in February of 2015, otouto has since been open-sourced and migrated to the API, and is being developed to this day.
|
otouto is an independently-developed Telegram API bot written in Lua. Originally conceived as a CLI script in February of 2015, otouto has since been open-sourced and migrated to the API, and is being developed to this day.
|
||||||
|
|
||||||
| The Manual |
|
| The Manual |
|
||||||
|:-----------|
|
|:------------------------------------------------------|
|
||||||
| [Setup](#setup) |
|
| [Setup](#setup) |
|
||||||
| [Plugins](#plugins) |
|
| [Plugins](#plugins) |
|
||||||
| [Control plugins](#control-plugins) |
|
| [Control plugins](#control-plugins) |
|
||||||
@ -47,12 +47,12 @@ Most plugins are intended for public use, but a few are for other purposes, like
|
|||||||
A plugin can have five components, and two of them are required:
|
A plugin can have five components, and two of them are required:
|
||||||
|
|
||||||
| Component | Description | Required? |
|
| Component | Description | Required? |
|
||||||
|:----------|:------------|:----------|
|
|:----------|:---------------------------------------------|:----------|
|
||||||
| action | The main function. It accepts the `msg` table as an argument. | Y |
|
| action | Main function. Expects `msg` table as an argument. | Y |
|
||||||
| triggers | A table of commands to be used for the plugin. Use Lua patterns. | Y |
|
| triggers | Table of triggers for the plugin. Uses Lua patterns. | Y |
|
||||||
| cron | An optional function to be called approximately every minute. | N |
|
| cron | Optional function to be called every minute. | N |
|
||||||
| command | The basic command and syntax. This is listed in the help text. | N |
|
| command | Basic command and syntax. Listed in the help text. | N |
|
||||||
| doc | Usage and other info for the plugin. This is returned with "/help command" | N |
|
| doc | Usage for the plugin. Returned by "/help $command". | N |
|
||||||
|
|
||||||
The `on_msg_receive()` function adds a few variables to the `msg` table for your convenience. These are self-explanatory: `msg.from.id_str`, `msg.to.id_str`, `msg.chat.id_str`, `msg.text_lower`, `msg.from.name`.
|
The `on_msg_receive()` function adds a few variables to the `msg` table for your convenience. These are self-explanatory: `msg.from.id_str`, `msg.to.id_str`, `msg.chat.id_str`, `msg.text_lower`, `msg.from.name`.
|
||||||
|
|
||||||
@ -70,12 +70,12 @@ Several functions used in multiple plugins are defined in utilities.lua. Refer t
|
|||||||
Some plugins are designed to be used by the bot's owner. Here are some examples, how they're used, and what they do.
|
Some plugins are designed to be used by the bot's owner. Here are some examples, how they're used, and what they do.
|
||||||
|
|
||||||
| Plugin | Command | Function |
|
| Plugin | Command | Function |
|
||||||
|:-------|:--------|:---------|
|
|:--------------|:-----------|:------------------------------------------------|
|
||||||
| control.lua | /reload | Reloads all plugins and configuration. |
|
| control.lua | /reload | Reloads all plugins and configuration. |
|
||||||
| control.lua | /halt | Saves the database and shuts down the bot properly. |
|
| control.lua | /halt | Shuts down the bot after saving the database. |
|
||||||
| blacklist.lua | /blacklist | Allows the admin to list people the bot will ignore. |
|
| blacklist.lua | /blacklist | Blocks people from using the bot. |
|
||||||
| shell.lua | /run | Executes shell commands on the host operating system. |
|
| shell.lua | /run | Executes shell commands on the host system. |
|
||||||
| luarun.lua | /lua | Executes Lua commands in the bot's environement. |
|
| luarun.lua | /lua | Executes Lua commands in the bot's environment. |
|
||||||
|
|
||||||
* * *
|
* * *
|
||||||
|
|
||||||
@ -89,34 +89,30 @@ Once the installation is finished, enable `administration.lua` in your config fi
|
|||||||
While tg is running, you may start/reload otouto with administration.lua enabled, and have access to a wide variety of administrative commands and automata. The administration "database" is stored in `administration.json`. To start using otouto to administrate a group (note that you must be the owner (or an administrator)), send `/gadd` to that group. For a list of commands, use `/ahelp`. Below I'll describe various functions now available to you.
|
While tg is running, you may start/reload otouto with administration.lua enabled, and have access to a wide variety of administrative commands and automata. The administration "database" is stored in `administration.json`. To start using otouto to administrate a group (note that you must be the owner (or an administrator)), send `/gadd` to that group. For a list of commands, use `/ahelp`. Below I'll describe various functions now available to you.
|
||||||
|
|
||||||
| Command | Function | Privilege | Internal? |
|
| Command | Function | Privilege | Internal? |
|
||||||
|:--------|:---------|:----------|:----------|
|
|:------------|:------------------------------------------------|:----------|:----------|
|
||||||
| /groups | Returns a list of administrated groups (except those flagged "unlisted". | 1 | N |
|
| /groups | Returns a list of administrated groups (except the unlisted). | 1 | N |
|
||||||
| /ahelp | Returns a list of administrative commands and their required privileges. | 1 | Y |
|
| /ahelp | Returns a list of accessible administrative commands. | 1 | Y |
|
||||||
| /ops | Returns a list of moderators, governors, and administrators. | 1 | Y |
|
| /ops | Returns a list of the moderators and governor of a group. | 1 | Y |
|
||||||
| /desc | Returns the link, rules, MOTD, and enabled flags of a group. | 1 | Y |
|
| /desc | Returns detailed information for a group. | 1 | Y |
|
||||||
| /rules | Returns the rules of a group. | 1 | Y |
|
| /rules | Returns the rules of a group. | 1 | Y |
|
||||||
| /motd | Returns a group's "Message of the Day". | 1 | Y |
|
| /motd | Returns the message of the day of a group. | 1 | Y |
|
||||||
| /link | Returns the link for a group. | 1 | Y |
|
| /link | Returns the link for a group. | 1 | Y |
|
||||||
| /leave | Removes the user from the group. | 1 | Y |
|
|
||||||
| /kick | Removes the target from the group. | 2 | Y |
|
| /kick | Removes the target from the group. | 2 | Y |
|
||||||
| /ban | Bans the target from the group. | 2 | Y |
|
| /(un)ban | Bans the target from the group or vice-versa. | 2 | Y |
|
||||||
| /unban | Unbans the target from the group. | 2 | Y |
|
|
||||||
| /changerule | Changes an individual group rule. | 3 | Y |
|
| /changerule | Changes an individual group rule. | 3 | Y |
|
||||||
| /setrules | Sets the rules for a group. | 3 | Y |
|
| /setrules | Sets the rules for a group. | 3 | Y |
|
||||||
| /setmotd | Sets a group's "Message of the Day". | 3 | Y |
|
| /setmotd | Sets the message of the day for a group. | 3 | Y |
|
||||||
| /setlink | Sets a group's link. | 3 | Y |
|
| /setlink | Sets the link for a group. | 3 | Y |
|
||||||
| /flag | Returns a list of available flags and their settings, or toggles a flag. | 3 | Y |
|
| /alist | Returns a list of administrators. | 3 | Y |
|
||||||
|
| /flags | Returns a list of flags and their states, or toggles one. | 3 | Y |
|
||||||
| /antiflood | Configures antiflood (flag 5) settings. | 3 | Y |
|
| /antiflood | Configures antiflood (flag 5) settings. | 3 | Y |
|
||||||
| /mod | Promotes a user to a moderator. | 3 | Y |
|
| /(de)mod | Promotes a user to a moderator or vice-versa. | 3 | Y |
|
||||||
| /demod | Demotes a moderator to a user. | 3 | Y |
|
| /(de)gov | Promotes a user to the governor or vice-versa. | 4 | Y |
|
||||||
| /gov | Promotes a user to a governor. | 4 | Y |
|
| /(un)hammer | Bans a user globally and blacklists him or vice-versa. | 4 | N |
|
||||||
| /degov | Demotes a governor to a user. | 4 | Y |
|
| /(de)admin | Promotes a user to an administrator or vice-versa. | 5 | N |
|
||||||
| /hammer | Bans a user globally, and blacklists him. | 4 | N |
|
|
||||||
| /unhammer | Removes a user's global ban, and unblacklists him. | 4 | N |
|
|
||||||
| /admin | Promotes a user to an administrator. | 5 | N |
|
|
||||||
| /deadmin | Demotes an administrator to a user. | 5 | N |
|
|
||||||
| /gadd | Adds a group to the administrative system. | 5 | N |
|
| /gadd | Adds a group to the administrative system. | 5 | N |
|
||||||
| /grem | Removes a group from the administrative system | 5 | Y |
|
| /grem | Removes a group from the administrative system. | 5 | Y |
|
||||||
|
| /glist | Returns a list of all administrated groups and their governors. | 5 | N |
|
||||||
| /broadcast | Broadcasts a message to all administrated groups. | 5 | N |
|
| /broadcast | Broadcasts a message to all administrated groups. | 5 | N |
|
||||||
|
|
||||||
Internal commands can only be run within an administrated group.
|
Internal commands can only be run within an administrated group.
|
||||||
@ -124,23 +120,23 @@ Internal commands can only be run within an administrated group.
|
|||||||
### Description of Privileges
|
### Description of Privileges
|
||||||
|
|
||||||
| # | Title | Description | Scope |
|
| # | Title | Description | Scope |
|
||||||
|:-:|:------|:------------|:------|
|
|:-:|:--------------|:------------------------------------------------------------------|:-------|
|
||||||
| 0 | Banned | Cannot enter the group(s). | Either |
|
| 0 | Banned | Cannot enter the group(s). | Either |
|
||||||
| 1 | User | Default rank. | Local |
|
| 1 | User | Default rank. | Local |
|
||||||
| 2 | Moderator | Can kick/ban/unban users from a group. | Local |
|
| 2 | Moderator | Can kick/ban/unban users. | Local |
|
||||||
| 3 | Governor | Can set rules/motd/link. Can promote/demote moderators. Can modify flags. | Local |
|
| 3 | Governor | Can set rules/motd/link, promote/demote moderators, modify flags. | Local |
|
||||||
| 4 | Administrator | Can globally ban/unban users. Can promote/demote governors. | Global |
|
| 4 | Administrator | Can globally ban/unban users, promote/demote governors. | Global |
|
||||||
| 5 | Owner | Can add/remove groups. Can broadcast. Can promote/demote administrators. | Global |
|
| 5 | Owner | Can add/remove groups, broadcast, promote/demote administrators. | Global |
|
||||||
|
|
||||||
Obviously, each greater rank inherits the privileges of the lower, positive ranks.
|
Obviously, each greater rank inherits the privileges of the lower, positive ranks.
|
||||||
|
|
||||||
### Flags
|
### Flags
|
||||||
|
|
||||||
| # | Name | Description |
|
| # | Name | Description |
|
||||||
|:-:|:-----|:------------|
|
|:-:|:------------|:---------------------------------------------------------------------------------|
|
||||||
| 1 | unlisted | Removes a group from the /groups listing. |
|
| 1 | unlisted | Removes a group from the /groups listing. |
|
||||||
| 2 | antisquig | Automatically removes users for posting Arabic script or RTL characters. |
|
| 2 | antisquig | Automatically removes users for posting Arabic script or RTL characters. |
|
||||||
| 3 | antisquig Strict | Automatically removes users whose names contain Arabic script or RTL characters. |
|
| 3 | antisquig++ | Automatically removes users whose names contain Arabic script or RTL characters. |
|
||||||
| 4 | antibot | Prevents bots from being added by non-moderators. |
|
| 4 | antibot | Prevents bots from being added by non-moderators. |
|
||||||
| 5 | antiflood | Prevents flooding by rate-limiting messages per user. |
|
| 5 | antiflood | Prevents flooding by rate-limiting messages per user. |
|
||||||
|
|
||||||
@ -193,43 +189,43 @@ Once this is set up, put your bot in the admin group and run `/modadd` and `/mod
|
|||||||
## List of plugins
|
## List of plugins
|
||||||
|
|
||||||
| Plugin | Command | Function | Aliases |
|
| Plugin | Command | Function | Aliases |
|
||||||
|:-------|:--------|:---------|:--------|
|
|:--------------------|:------------------------------|:--------------------------------------------------------|:--------|
|
||||||
| help.lua | /help [command] | Returns a list of commands or command-specific help. | /h |
|
| help.lua | /help [command] | Returns a list of commands or command-specific help. | /h |
|
||||||
| about.lua | /about | Returns the about text as configured in config.lua. |
|
| about.lua | /about | Returns the about text as configured in config.lua. |
|
||||||
| ping.lua | /ping | The simplest plugin ever! |
|
| ping.lua | /ping | The simplest plugin ever! |
|
||||||
| echo.lua | /echo <text> | Repeats a string of text. |
|
| echo.lua | /echo ‹text› | Repeats a string of text. |
|
||||||
| gSearch.lua | /google <query> | Returns Google web results. | /g, /gnsfw |
|
| gSearch.lua | /google ‹query› | Returns Google web results. | /g |
|
||||||
| gImages.lua | /images <query> | Returns a Google image result. | /i, /insfw |
|
| gImages.lua | /images ‹query› | Returns a Google image result. | /i |
|
||||||
| gMaps.lua | /location <query> | Returns location data from Google Maps. | /loc |
|
| gMaps.lua | /location ‹query› | Returns location data from Google Maps. | /loc |
|
||||||
| youtube.lua | /youtube <query> | Returns the top video result from YouTube. | /yt |
|
| youtube.lua | /youtube ‹query› | Returns the top video result from YouTube. | /yt |
|
||||||
| wikipedia.lua | /wikipedia <query> | Returns the summary of a Wikipedia article. | /wiki |
|
| wikipedia.lua | /wikipedia ‹query› | Returns the summary of a Wikipedia article. | /w |
|
||||||
| lastfm.lua | /np [username] | Returns the song you are currently listening to. |
|
| lastfm.lua | /np [username] | Returns the song you are currently listening to. |
|
||||||
| lastfm.lua | /fmset [username] | Sets your username for /np. /fmset -- will delete it. |
|
| lastfm.lua | /fmset [username] | Sets your username for /np. /fmset -- will delete it. |
|
||||||
| hackernews.lua | /hackernews | Returns the latest posts from Hacker News. | /hn |
|
| hackernews.lua | /hackernews | Returns the latest posts from Hacker News. | /hn |
|
||||||
| imdb.lua | /imdb <query> | Returns film information from IMDb. |
|
| imdb.lua | /imdb ‹query› | Returns film information from IMDb. |
|
||||||
| hearthstone.lua | /hearthstone <query> | Returns data for Hearthstone cards matching the query. | /hs |
|
| hearthstone.lua | /hearthstone ‹query› | Returns data for Hearthstone cards matching the query. | /hs |
|
||||||
| calc.lua | /calc <expression> | Returns solutions to math expressions and conversions between common units. |
|
| calc.lua | /calc ‹expression› | Returns conversions and solutions to math expressions. |
|
||||||
| bible.lua | /bible <reference> | Returns a Bible verse. | /b |
|
| bible.lua | /bible ‹reference› | Returns a Bible verse. | /b |
|
||||||
| urbandictionary.lua | /urbandictionary <query> | Returns the top definition from Urban Dictionary. | /ud, /urban |
|
| urbandictionary.lua | /urban ‹query› | Returns the top definition from Urban Dictionary. | /ud |
|
||||||
| time.lua | /time <query> | Returns the time, date, and a timezone for a location. |
|
| time.lua | /time ‹query› | Returns the time, date, and a timezone for a location. |
|
||||||
| weather.lua | /weather <query> | Returns current weather conditions for a given location. |
|
| weather.lua | /weather ‹query› | Returns current weather conditions for a given location. |
|
||||||
| nick.lua | /nick <nickname> | Set your nickname. /nick - will delete it. |
|
| nick.lua | /nick ‹nickname› | Set your nickname. /nick - will delete it. |
|
||||||
| whoami.lua | /whoami | Returns user and chat info for you or the replied-to user. | /who |
|
| whoami.lua | /whoami | Returns user and chat info for you or the replied-to user. | /who |
|
||||||
| eightball.lua | /8ball | Returns an answer from a magic 8-ball. |
|
| eightball.lua | /8ball | Returns an answer from a magic 8-ball. |
|
||||||
| dice.lua | /roll <nDr> | Returns RNG dice rolls. Uses D&D notation. |
|
| dice.lua | /roll ‹nDr› | Returns RNG dice rolls. Uses D&D notation. |
|
||||||
| reddit.lua | /reddit [r/subreddit ¦ query] | Returns the top results from a given subreddit, query, or r/all. | /r |
|
| reddit.lua | /reddit [r/subreddit ¦ query] | Returns the top results from a subreddit, query, or r/all. | /r |
|
||||||
| xkcd.lua | /xkcd [query] | Returns an xkcd strip and its alt text. |
|
| xkcd.lua | /xkcd [query] | Returns an xkcd strip and its alt text. |
|
||||||
| slap.lua | /slap <target> | Gives someone a slap (or worse). |
|
| slap.lua | /slap ‹target› | Gives someone a slap (or worse). |
|
||||||
| commit.lua | /commit | Returns a commit message from whatthecommit.com. |
|
| commit.lua | /commit | Returns a commit message from whatthecommit.com. |
|
||||||
| fortune.lua | /fortune | Returns a UNIX fortune. |
|
| fortune.lua | /fortune | Returns a UNIX fortune. |
|
||||||
| pun.lua | /pun | Returns a pun. |
|
| pun.lua | /pun | Returns a pun. |
|
||||||
| pokedex.lua | /pokedex <query> | Returns a Pokedex entry. | /dex |
|
| pokedex.lua | /pokedex ‹query› | Returns a Pokedex entry. | /dex |
|
||||||
| currency.lua | /cash [amount] <currency> to <currency> | Converts one currency to another. |
|
| currency.lua | /cash [amount] ‹cur› to ‹cur› | Converts one currency to another. |
|
||||||
| cats.lua | /cat | Returns a cat picture. |
|
| cats.lua | /cat | Returns a cat picture. |
|
||||||
| reactions.lua | /reactions | Returns a list of reaction emoticons which can be used through the bot. |
|
| reactions.lua | /reactions | Returns a list of emoticons which can be posted by the bot. |
|
||||||
| apod.lua | /apod [date] | Returns the NASA Astronomy Picture of the Day. |
|
| apod.lua | /apod [date] | Returns the NASA Astronomy Picture of the Day. |
|
||||||
| dilbert.lua | /dilbert [date] | Returns a Dilbert strip. |
|
| dilbert.lua | /dilbert [date] | Returns a Dilbert strip. |
|
||||||
| patterns.lua | /s/<from>/<to>/ | Fixed that for you. :^) |
|
| patterns.lua | /s/‹from›/‹to›/ | Search-and-replace using Lua patterns. |
|
||||||
| me.lua | /me | Returns user-specific data stored by the bot. |
|
| me.lua | /me | Returns user-specific data stored by the bot. |
|
||||||
|
|
||||||
* * *
|
* * *
|
||||||
@ -249,7 +245,7 @@ There are a a few ways to contribute if you are not a programmer. For one, your
|
|||||||
Contributions are appreciated in any form. Monetary contributions will go toward server costs. Both programmers and donators will be eternally honored (at their discretion) on this page.
|
Contributions are appreciated in any form. Monetary contributions will go toward server costs. Both programmers and donators will be eternally honored (at their discretion) on this page.
|
||||||
|
|
||||||
| Contributors |
|
| Contributors |
|
||||||
|:-----------|
|
|:----------------------------------------------|
|
||||||
| [Juan Potato](http://github.com/JuanPotato) |
|
| [Juan Potato](http://github.com/JuanPotato) |
|
||||||
| [Tiago Danin](http://github.com/TiagoDanin) |
|
| [Tiago Danin](http://github.com/TiagoDanin) |
|
||||||
| [bb010g](http://github.com/bb010g) |
|
| [bb010g](http://github.com/bb010g) |
|
||||||
@ -261,7 +257,7 @@ Contributions are appreciated in any form. Monetary contributions will go toward
|
|||||||
| [dogtopus](http://github.com/dogtopus) |
|
| [dogtopus](http://github.com/dogtopus) |
|
||||||
|
|
||||||
| Donators |
|
| Donators |
|
||||||
|:---------|
|
|:----------------------------------------------|
|
||||||
| [n8](http://telegram.me/n8_c00) |
|
| [n8](http://telegram.me/n8_c00) |
|
||||||
| [Alex](http://telegram.me/sandu) |
|
| [Alex](http://telegram.me/sandu) |
|
||||||
| [Brayden Banks](http://telegram.me/bb010g) |
|
| [Brayden Banks](http://telegram.me/bb010g) |
|
||||||
|
Reference in New Issue
Block a user