Akamaru/Mikubot-2
Archived
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Updated readme for grammar and easier reading without formatting.

Browse Source
This commit is contained in:
topkecleon 2016-04-02 19:15:38 -04:00
parent b41a05e3cd
commit 1eb434f198
1 changed files with 125 additions and 129 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

254
README.md
View File

@ -5,16 +5,16 @@ 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) |
| [administration.lua](#administrationlua) | | [administration.lua](#administrationlua) |
| [Liberbot-related plugins](#liberbot-related-plugins) | | [Liberbot-related plugins](#liberbot-related-plugins) |
| [List of plugins](#list-of-plugins) | | [List of plugins](#list-of-plugins) |
| [Style](#style) | | [Style](#style) |
| [Contributors](#contributors) | | [Contributors](#contributors) |
## Setup ## Setup
You _must_ have Lua (5.2+), lua-socket, lua-sec, and lua-cjson installed. To upload files, you must have curl installed. To use fortune.lua, you must have fortune installed. You _must_ have Lua (5.2+), lua-socket, lua-sec, and lua-cjson installed. To upload files, you must have curl installed. To use fortune.lua, you must have fortune installed.
@ -46,13 +46,13 @@ 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`.
@ -69,13 +69,13 @@ Several functions used in multiple plugins are defined in utilities.lua. Refer t
## Control plugins ## Control plugins
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. |
* * * * * *
@ -88,61 +88,57 @@ 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 | | /(un)ban | Bans the target from the group or vice-versa. | 2 | Y |
| /ban | Bans the target from the group. | 2 | Y | | /changerule | Changes an individual group rule. | 3 | Y |
| /unban | Unbans the target from the group. | 2 | Y | | /setrules | Sets the rules for a group. | 3 | Y |
| /changerule | Changes an individual group rule. | 3 | Y | | /setmotd | Sets the message of the day for a group. | 3 | Y |
| /setrules | Sets the rules for a group. | 3 | Y | | /setlink | Sets the link for a group. | 3 | Y |
| /setmotd | Sets a group's "Message of the Day". | 3 | Y | | /alist | Returns a list of administrators. | 3 | Y |
| /setlink | Sets a group's link. | 3 | Y | | /flags | Returns a list of flags and their states, or toggles one. | 3 | Y |
| /flag | Returns a list of available flags and their settings, or toggles a flag. | 3 | Y | | /antiflood | Configures antiflood (flag 5) settings. | 3 | Y |
| /antiflood | Configures antiflood (flag 5) settings. | 3 | Y | | /(de)mod | Promotes a user to a moderator or vice-versa. | 3 | Y |
| /mod | Promotes a user to a moderator. | 3 | Y | | /(de)gov | Promotes a user to the governor or vice-versa. | 4 | Y |
| /demod | Demotes a moderator to a user. | 3 | Y | | /(un)hammer | Bans a user globally and blacklists him or vice-versa. | 4 | N |
| /gov | Promotes a user to a governor. | 4 | Y | | /(de)admin | Promotes a user to an administrator or vice-versa. | 5 | N |
| /degov | Demotes a governor to a user. | 4 | Y | | /gadd | Adds a group to the administrative system. | 5 | N |
| /hammer | Bans a user globally, and blacklists him. | 4 | N | | /grem | Removes a group from the administrative system. | 5 | Y |
| /unhammer | Removes a user's global ban, and unblacklists him. | 4 | N | | /glist | Returns a list of all administrated groups and their governors. | 5 | N |
| /admin | Promotes a user to an administrator. | 5 | N | | /broadcast | Broadcasts a message to all administrated groups. | 5 | N |
| /deadmin | Demotes an administrator to a user. | 5 | N |
| /gadd | Adds a group to the administrative system. | 5 | N |
| /grem | Removes a group from the administrative system | 5 | Y |
| /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.
### 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. |
#### antiflood #### antiflood
antiflood (flag 5) provides a system of automatic flood protection by removing users who post too much. It is entirely configurable by a group's governor, an administrator, or the bot owner. For each message to a particular group, a user is awarded a certain number of "points". The number of points is different for each message type. When the user reaches 100 points, he is removed. Points are reset each minute. In this way, if a user posts twenty messages within one minute, he is removed. antiflood (flag 5) provides a system of automatic flood protection by removing users who post too much. It is entirely configurable by a group's governor, an administrator, or the bot owner. For each message to a particular group, a user is awarded a certain number of "points". The number of points is different for each message type. When the user reaches 100 points, he is removed. Points are reset each minute. In this way, if a user posts twenty messages within one minute, he is removed.
@ -151,15 +147,15 @@ antiflood (flag 5) provides a system of automatic flood protection by removing u
| Type | Points | | Type | Points |
|:-----|:------:| |:-----|:------:|
| text | 5 | | text | 5 |
| contact | 5 | | contact | 5 |
| audio | 5 | | audio | 5 |
| voice | 5 | | voice | 5 |
| photo | 10 | | photo | 10 |
| document | 10 | | document | 10 |
| location | 10 | | location | 10 |
| video | 10 | | video | 10 |
| sticker | 20 | | sticker | 20 |
* * * * * *
@ -192,45 +188,45 @@ 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. |
* * * * * *
@ -248,20 +244,20 @@ 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) |
| [Ender](http://github.com/luksireiku) | | [Ender](http://github.com/luksireiku) |
| [Iman Daneshi](http://github.com/Imandaneshi) | | [Iman Daneshi](http://github.com/Imandaneshi) |
| [HeitorPB](http://github.com/heitorPB) | | [HeitorPB](http://github.com/heitorPB) |
| [Akronix](http://github.com/Akronix) | | [Akronix](http://github.com/Akronix) |
| [Ville](http://github.com/cwxda) | | [Ville](http://github.com/cwxda) |
| [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) |