this program is licensed under the **Affero GNU Public License v3**, you can read the copy that comes along with this program or read it at [gnu.org's website](http://www.gnu.org/licenses/agpl-3.0.html)
## dependencies
the following is all that's needed
* bash 4+
* GNU coreutils (sed, grep, tail, head, etc.)
* curl
* a telegram API token
Bash 4+ is obligatory for this library to work as features introduced at this point are heavily used.
## installation
drop it wherever you like, although I recommend either of these options
* copying the files to /usr/lib/bashbot-lib/
* add it as a submodule in your project (git submodules are very annoying to deal with)
* simply keep it in a subfolder in your project
## usage
source the library, and optionally the viewer, in your bash shellscript
```
. /usr/lib/bashbot-lib/bashbot-lib.sh
. /usr/lib/bashbot-lib/viewer.sh
```
you will also need the following
* a variable named api_url with the following content (mind the trailing forward slash): `api_url="https:/api.telegram.org/bot${YOUR_TOKEN_HERE}/"`
* the following files to read and write from: `updates.txt``sentmsgs.txt``delmsgs.txt`
* these files must be placed in the same directory you run your bot from or in the directory defined in the following bullet poiint
* (optional) a variable named bot_tmpdir with the following content (mind the trailing forward slash): `bot_tmpdir="/some/directory/"`
* if you define this directory, it will hold the files from the previous bullet point
* (optional) a bash associative array for use with the getmsg_content function: `declare -A curmsg`
* (optional) I recommend adding the following at the beggining of your implementation to centralize error logs: `exec 2>"${bot_tmpdir}error.log"`
once you've got that set up, all that's left is using the functions provided to make your bot
### getting updates
use the `getupd` function to request an update (singular) from telegram's servers, the output will be printed to `updates.txt`
if there is no updates for you, the connection will stall for 60 seconds waiting for one and return empty if there was none, this is done to minimize unnecesary network traffic; the code actually requests that the connection stay open for 300 seconds but telegram only does so for 60 anyways
with every update, getupd calculates the new offset required to request new updates after the last one so no repeated responses clutter `updates.txt`
`getupd` requires no additional arguments passed to it
### reading message contents
use the `getmsg_content` function to parse the contents of a message and save them to a bash associative array
the `getmsg_content` receives two arguments
* the **name** (not a reference to) of a bash associative array
* the filename of a file with telegram JSON responses formatted by this library's functions
**IMPORANT**: you must pass only the name of the associative array and not a reference to it
this is so because bash associative arrays can only be passed to functions as named references
the message is read from the last line of the file passed as second argument
the file will be either updates.txt or sentmsgs.txt most probably, although it will work with any file where the contents are telegram JSON responses formatted with this library's functions, so you can use it whoever you like in your implementation
the bash associative array will hold the following contents
if you sourced the viewer, you can view these contents with `view_content "curmsg"` where `curmsg` is the name of the bash associative array populated by `getmsg_content`
* (optional) an inline keyboard made with `mkinline_kbd`
**IMPORTANT**: you must [URL % encode](https://www.w3schools.com/tags/ref_urlencode.ASP) some special characters in the contents of the message or telegram won't accept them
```
# wrong way
sendmsg "${curmsg[chat_id]}" "message %% with ۖ special
