octoleo
/
telegram-bot-bash
mirror of https://github.com/octoleo/telegram-bot-bash.git
1
1
Fork 0
Code Issues Projects Releases Wiki Activity

use vim spellcheck for MD

This commit is contained in:
Kay Marquardt (Gnadelwartz) 2020-06-23 16:11:45 +02:00
parent afa8d874e3
commit 694ee6185d
9 changed files with 98 additions and 99 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

28
README.html
View File

@ -91,9 +91,9 @@ Written by Drew (@topkecleon), Daniil Gentili (@danogentili), and Kay M (@gnadel
<p>Released to the public domain wherever applicable. Elsewhere, consider it released under the <a href="http://www.wtfpl.net/txt/copying/">WTFPLv2</a>.</p>
<h2>Prerequisites</h2>
<p>Uses <a href="http://github.com/dominictarr/JSON.sh">JSON.sh</a>, but no more TMUX.</p>
<p>Even bashbot is written in bash, it depends on commands typically availible in a Unix/Linux Environment. More concret on the common commands provided by recent versions of <a href="https://en.wikipedia.org/wiki/List_of_GNU_Core_Utilities_commands">coreutils</a>, <a href="https://en.wikipedia.org/wiki/BusyBox#Commands">busybox</a> or <a href="https://landley.net/toybox/help.html">toybox</a>, see <a href="doc/7_develop.md#common-commands">Developer Notes</a></p>
<p>Even bashbot is written in bash, it depends on commands typically available in a Unix/Linux Environment. More concret on the common commands provided by recent versions of <a href="https://en.wikipedia.org/wiki/List_of_GNU_Core_Utilities_commands">coreutils</a>, <a href="https://en.wikipedia.org/wiki/BusyBox#Commands">busybox</a> or <a href="https://landley.net/toybox/help.html">toybox</a>, see <a href="doc/7_develop.md#common-commands">Developer Notes</a></p>
<p><em>Note for MacOS and BSD Users:</em> As bashbot heavily uses modern bash and (gnu) grep/sed features, bashbot will not run without installing additional software, see <a href="doc/0_install.md">Install Bashbot</a></p>
<p>Bashbot <a href="https://github.com/topkecleon/telegram-bot-bash">Documentation</a> and <a href="https://github.com/topkecleon/telegram-bot-bash/releases">Downloads</a> are availible on www.github.com</p>
<p>Bashbot <a href="https://github.com/topkecleon/telegram-bot-bash">Documentation</a> and <a href="https://github.com/topkecleon/telegram-bot-bash/releases">Downloads</a> are available on www.github.com</p>
<h2>Documentation</h2>
<ul>
<li><a href="https://core.telegram.org/bots">Introdution to Telegram Bots</a></li>
@ -108,7 +108,7 @@ Written by Drew (@topkecleon), Daniil Gentili (@danogentili), and Kay M (@gnadel
<li><a href="doc/2_usage.md">Getting Started</a>
<ul>
<li>Managing your Bot</li>
<li>Recieve data</li>
<li>Receive data</li>
<li>Send messages</li>
<li>Send files, locations, keyboards</li>
</ul></li>
@ -124,7 +124,7 @@ Written by Drew (@topkecleon), Daniil Gentili (@danogentili), and Kay M (@gnadel
<ul>
<li>Handling UTF-8 character sets</li>
<li>Run as other user or system service</li>
<li>Scedule bashbot from Cron</li>
<li>Schedule bashbot from Cron</li>
<li>Use from CLI and Scripts</li>
<li>Customize Bashbot Environment</li>
</ul></li>
@ -132,7 +132,7 @@ Written by Drew (@topkecleon), Daniil Gentili (@danogentili), and Kay M (@gnadel
<ul>
<li>Customize mycommands.sh</li>
<li>Overwrite/disable commands</li>
<li>Seperate logic from commands</li>
<li>Separate logic from commands</li>
<li>Test your Bot with shellcheck</li>
</ul></li>
<li><a href="doc/6_reference.md">Function Reference</a>
@ -143,17 +143,17 @@ Written by Drew (@topkecleon), Daniil Gentili (@danogentili), and Kay M (@gnadel
<li>jsshDB Bashbot key-value storage</li>
<li>Background and Interactive Jobs</li>
</ul></li>
<li><a href="doc/7_develop.md">Deveoper Notes</a>
<li><a href="doc/7_develop.md">Devloper Notes</a>
<ul>
<li>Debug bashbot</li>
<li>Modules, addons, events</li>
<li>Setup your environment</li>
<li>Bashbot testsuite</li>
<li>Bashbot test suite</li>
</ul></li>
<li><a href="examples/README.md">Examples Dir</a></li>
</ul>
<h3>Your really first bashbot in a nutshell</h3>
<p>To install and run bashbot you need acess to a linux/unix command line. If you don't know how to get accces to a linux/unix/bsd like command line you should stop reading here :-(</p>
<p>To install and run bashbot you need access to a linux/unix command line. If you don't know how to get access to a linux/unix/bsd like command line you should stop reading here :-(</p>
<p>In addition you need a <a href="https://telegram.org">Telegram client</a> and a mobile phone to <a href="https://telegramguide.com/create-a-telegram-account/">register an account</a>. If you don't want to register for Telegram you should stop reading here ;-)</p>
<p>After you're registered to Telegram send a message to <a href="https://telegram.me/botfather">@botfather</a>, <a href="doc/1_firstbot.md">create a new Telegram Bot token</a> and write it down. You need the token to install the bot.</p>
<p>Now open a linux/unix/bsd terminal and check if bash is installed: <code>which bash &amp;&amp; echo "bash installed!"</code>. If you get an error message bash is not installed.</p>
@ -176,7 +176,7 @@ It features background tasks and interactive chats, and can serve as an interfac
</code></pre>
<p>For more Information on how to install, customize and use your new bot, read the <a href="#Documentation">Documentation</a></p>
<h3>Log files</h3>
<p>Since version 0.96 bashbot log commands recieved/send and connection errors. If you start bashbot in debug mode bash stdout, stderr and all send/received telegram message are logged also.</p>
<p>Since version 0.96 bashbot log commands received/send and connection errors. If you start bashbot in debug mode bash stdout, stderr and all send/received telegram message are logged also.</p>
<p>To enable debug mode start bashbot with debug as third argument: <code>bashbot start debug</code></p>
<pre><code>├── logs
│   ├── BASHBOT.log # log what your bot is doing ...
@ -225,7 +225,7 @@ It features background tasks and interactive chats, and can serve as an interfac
<h3>Why Bash and not the much better xyz?</h3>
<p>Well, thats a damn good question ... may be because I'm an Unix/Linux admin from stone age. Nevertheless there are more reasons from my side:</p>
<ul>
<li>bashbot will run everywhere where bash is availible, from ebedded linux to mainframe</li>
<li>bashbot will run everywhere where bash is available, from ebedded linux to mainframe</li>
<li>easy to integrate with other shell script, e.g. for sending system message / health status</li>
<li>no need to install or learn a new programming language, library or framework</li>
<li>no database, not event driven, not OO ...</li>
@ -246,17 +246,17 @@ It features background tasks and interactive chats, and can serve as an interfac
<a class="sourceLine" id="cb5-8" title="8"><span class="co"># send me output of a system command</span></a>
<a class="sourceLine" id="cb5-9" title="9"><span class="ex">send_message</span> <span class="st">&quot;</span><span class="op">$(&lt;</span><span class="st">&quot;</span><span class="va">$BOTADMIN</span><span class="st">&quot;</span><span class="op">)</span><span class="st">&quot;</span> <span class="st">&quot;</span><span class="va">$(</span><span class="fu">df</span> -h<span class="va">)</span><span class="st">&quot;</span></a></code></pre></div>
<p>For more information see <a href="doc/8_custom.md">Expert Use</a></p>
<h3>Why do I get "EXPECTED value GOT EOF" on start?</h3>
<p>May be your IP is blocked by telegram. You can test this by running curl or wget manually:</p>
<h3>Blocked by telegram?</h3>
<p>This may happen if to many wrong requests are sent to api.telegram.org, e.g. using a wrong token or not existing API calls. If you have a fixed IP you can ask telegram service to unblock your ip or change your IP. If you are running a tor proxy on your server you may uncomment the <code>BASHBOT_CURL_ARGS</code> line in 'mycommands.sh'</p>
<p>You can test if younare blockeds by running curl or wget manually:</p>
<div class="sourceCode" id="cb6"><pre class="sourceCode bash"><code class="sourceCode bash"><a class="sourceLine" id="cb6-1" title="1"><span class="ex">curl</span> -m 10 https://api.telegram.org/bot</a>
<a class="sourceLine" id="cb6-2" title="2"><span class="co">#curl: (28) Connection timed out after 10001 milliseconds</span></a>
<a class="sourceLine" id="cb6-3" title="3"></a>
<a class="sourceLine" id="cb6-4" title="4"><span class="fu">wget</span> -t 1 -T 10 https://api.telegram.org/bot</a>
<a class="sourceLine" id="cb6-5" title="5"><span class="co">#Connecting to api.telegram.org (api.telegram.org)|46.38.243.234|:443... failed: Connection timed out.</span></a></code></pre></div>
<p>This may happen if to many wrong requests are sent to api.telegram.org, e.g. using a wrong token or not existing API calls. If you have a fixed IP you can ask telegram service to unblock your ip or change your IP. If you are running a socks or tor proxy on your server look for the <code>BASHBOT_CURL_ARGS</code> lines in 'mycommands.sh' as example.</p>
<p>@Gnadelwartz</p>
<h2>That's it!</h2>
<p>If you feel that there's something missing or if you found a bug, feel free to submit a pull request!</p>
<h4>$$VERSION$$ v0.98-dev-47-gba614b7</h4>
<h4>$$VERSION$$ v0.98-dev-69-gafa8d87</h4>
</body>
</html>

30
README.md
View File

@ -11,13 +11,13 @@ Elsewhere, consider it released under the [WTFPLv2](http://www.wtfpl.net/txt/cop
## Prerequisites
Uses [JSON.sh](http://github.com/dominictarr/JSON.sh), but no more TMUX.
Even bashbot is written in bash, it depends on commands typically availible in a Unix/Linux Environment.
Even bashbot is written in bash, it depends on commands typically available in a Unix/Linux Environment.
More concret on the common commands provided by recent versions of [coreutils](https://en.wikipedia.org/wiki/List_of_GNU_Core_Utilities_commands), [busybox](https://en.wikipedia.org/wiki/BusyBox#Commands) or [toybox](https://landley.net/toybox/help.html), see [Developer Notes](doc/7_develop.md#common-commands)
*Note for MacOS and BSD Users:* As bashbot heavily uses modern bash and (gnu) grep/sed features, bashbot will not run without installing additional software, see [Install Bashbot](doc/0_install.md)
Bashbot [Documentation](https://github.com/topkecleon/telegram-bot-bash) and [Downloads](https://github.com/topkecleon/telegram-bot-bash/releases) are availible on www.github.com
Bashbot [Documentation](https://github.com/topkecleon/telegram-bot-bash) and [Downloads](https://github.com/topkecleon/telegram-bot-bash/releases) are available on www.github.com
## Documentation
* [Introdution to Telegram Bots](https://core.telegram.org/bots)
@ -29,7 +29,7 @@ Bashbot [Documentation](https://github.com/topkecleon/telegram-bot-bash) and [Do
* [Get Bottoken from Botfather](doc/1_firstbot.md)
* [Getting Started](doc/2_usage.md)
* Managing your Bot
* Recieve data
* Receive data
* Send messages
* Send files, locations, keyboards
* [Advanced Features](doc/3_advanced.md)
@ -41,13 +41,13 @@ Bashbot [Documentation](https://github.com/topkecleon/telegram-bot-bash) and [Do
* [Expert Use](doc/4_expert.md)
* Handling UTF-8 character sets
* Run as other user or system service
* Scedule bashbot from Cron
* Schedule bashbot from Cron
* Use from CLI and Scripts
* Customize Bashbot Environment
* [Best Practices](doc/5_practice.md)
* Customize mycommands.sh
* Overwrite/disable commands
* Seperate logic from commands
* Separate logic from commands
* Test your Bot with shellcheck
* [Function Reference](doc/6_reference.md)
* Sending Messages, Files, Keyboards
@ -55,16 +55,16 @@ Bashbot [Documentation](https://github.com/topkecleon/telegram-bot-bash) and [Do
* Inline Queries
* jsshDB Bashbot key-value storage
* Background and Interactive Jobs
* [Deveoper Notes](doc/7_develop.md)
* [Devloper Notes](doc/7_develop.md)
* Debug bashbot
* Modules, addons, events
* Setup your environment
* Bashbot testsuite
* Bashbot test suite
* [Examples Dir](examples/README.md)
### Your really first bashbot in a nutshell
To install and run bashbot you need acess to a linux/unix command line. If you don't know how to get accces to a linux/unix/bsd like command line you should stop reading here :-(
To install and run bashbot you need access to a linux/unix command line. If you don't know how to get access to a linux/unix/bsd like command line you should stop reading here :-(
In addition you need a [Telegram client](https://telegram.org) and a mobile phone to [register an account](https://telegramguide.com/create-a-telegram-account/).
If you don't want to register for Telegram you should stop reading here ;-)
@ -104,7 +104,7 @@ For more Information on how to install, customize and use your new bot, read the
### Log files
Since version 0.96 bashbot log commands recieved/send and connection errors. If you start bashbot in debug mode
Since version 0.96 bashbot log commands received/send and connection errors. If you start bashbot in debug mode
bash stdout, stderr and all send/received telegram message are logged also.
To enable debug mode start bashbot with debug as third argument: `bashbot start debug`
@ -190,7 +190,7 @@ Bashbot is not more (in)secure as any other Bot written in any other language, w
### Why Bash and not the much better xyz?
Well, thats a damn good question ... may be because I'm an Unix/Linux admin from stone age. Nevertheless there are more reasons from my side:
- bashbot will run everywhere where bash is availible, from ebedded linux to mainframe
- bashbot will run everywhere where bash is available, from ebedded linux to mainframe
- easy to integrate with other shell script, e.g. for sending system message / health status
- no need to install or learn a new programming language, library or framework
- no database, not event driven, not OO ...
@ -221,8 +221,10 @@ send_message "$(<"$BOTADMIN")" "$(df -h)"
For more information see [Expert Use](doc/8_custom.md)
### Why do I get "EXPECTED value GOT EOF" on start?
May be your IP is blocked by telegram. You can test this by running curl or wget manually:
### Blocked by telegram?
This may happen if to many wrong requests are sent to api.telegram.org, e.g. using a wrong token or not existing API calls. If you have a fixed IP you can ask telegram service to unblock your ip or change your IP. If you are running a tor proxy on your server you may uncomment the ```BASHBOT_CURL_ARGS``` line in 'mycommands.sh'
You can test if younare blockeds by running curl or wget manually:
```bash
curl -m 10 https://api.telegram.org/bot
#curl: (28) Connection timed out after 10001 milliseconds
@ -230,8 +232,6 @@ curl -m 10 https://api.telegram.org/bot
wget -t 1 -T 10 https://api.telegram.org/bot
#Connecting to api.telegram.org (api.telegram.org)|46.38.243.234|:443... failed: Connection timed out.
```
This may happen if to many wrong requests are sent to api.telegram.org, e.g. using a wrong token or not existing API calls. If you have a fixed IP you can ask telegram service to unblock your ip or change your IP. If you are running a socks or tor proxy on your server look for the ```BASHBOT_CURL_ARGS``` lines in 'mycommands.sh' as example.
@Gnadelwartz
@ -239,4 +239,4 @@ This may happen if to many wrong requests are sent to api.telegram.org, e.g. usi
If you feel that there's something missing or if you found a bug, feel free to submit a pull request!
#### $$VERSION$$ v0.98-dev-47-gba614b7
#### $$VERSION$$ v0.98-dev-69-gafa8d87

41
README.txt
View File

@ -15,7 +15,7 @@ Elsewhere, consider it released under the
## Prerequisites
Uses [JSON.sh](http://github.com/dominictarr/JSON.sh), but no more TMUX.
Even bashbot is written in bash, it depends on commands typically availible in
Even bashbot is written in bash, it depends on commands typically available in
a Unix/Linux Environment.
More concret on the common commands provided by recent versions of
[coreutils](https://en.wikipedia.org/wiki/List_of_GNU_Core_Utilities_commands),
@ -30,7 +30,7 @@ see [Install Bashbot](doc/0_install.md)
Bashbot [Documentation](https://github.com/topkecleon/telegram-bot-bash) and
[Downloads](https://github.com/topkecleon/telegram-bot-bash/releases) are
availible on www.github.com
available on www.github.com
## Documentation
* [Introdution to Telegram Bots](https://core.telegram.org/bots)
@ -42,7 +42,7 @@ availible on www.github.com
* [Get Bottoken from Botfather](doc/1_firstbot.md)
* [Getting Started](doc/2_usage.md)
* Managing your Bot
* Recieve data
* Receive data
* Send messages
* Send files, locations, keyboards
* [Advanced Features](doc/3_advanced.md)
@ -54,13 +54,13 @@ availible on www.github.com
* [Expert Use](doc/4_expert.md)
* Handling UTF-8 character sets
* Run as other user or system service
* Scedule bashbot from Cron
* Schedule bashbot from Cron
* Use from CLI and Scripts
* Customize Bashbot Environment
* [Best Practices](doc/5_practice.md)
* Customize mycommands.sh
* Overwrite/disable commands
* Seperate logic from commands
* Separate logic from commands
* Test your Bot with shellcheck
* [Function Reference](doc/6_reference.md)
* Sending Messages, Files, Keyboards
@ -68,17 +68,17 @@ availible on www.github.com
* Inline Queries
* jsshDB Bashbot key-value storage
* Background and Interactive Jobs
* [Deveoper Notes](doc/7_develop.md)
* [Devloper Notes](doc/7_develop.md)
* Debug bashbot
* Modules, addons, events
* Setup your environment
* Bashbot testsuite
* Bashbot test suite
* [Examples Dir](examples/README.md)
### Your really first bashbot in a nutshell
To install and run bashbot you need acess to a linux/unix command line. If you
don't know how to get accces to a linux/unix/bsd like command line you should
To install and run bashbot you need access to a linux/unix command line. If you
don't know how to get access to a linux/unix/bsd like command line you should
stop reading here :-(
In addition you need a [Telegram client](https://telegram.org) and a mobile
@ -133,7 +133,7 @@ the [Documentation](#Documentation)
### Log files
Since version 0.96 bashbot log commands recieved/send and connection errors. If
Since version 0.96 bashbot log commands received/send and connection errors. If
you start bashbot in debug mode
bash stdout, stderr and all send/received telegram message are logged also.
@ -262,7 +262,7 @@ execution bug, pls update if you use an older version!
Well, thats a damn good question ... may be because I'm an Unix/Linux admin
from stone age. Nevertheless there are more reasons from my side:
- bashbot will run everywhere where bash is availible, from ebedded linux to
- bashbot will run everywhere where bash is available, from ebedded linux to
mainframe
- easy to integrate with other shell script, e.g. for sending system message /
health status
@ -303,9 +303,14 @@ send_message "$(<"$BOTADMIN")" "$(df -h)"
For more information see [Expert Use](doc/8_custom.md)
### Why do I get "EXPECTED value GOT EOF" on start?
May be your IP is blocked by telegram. You can test this by running curl or
wget manually:
### Blocked by telegram?
This may happen if to many wrong requests are sent to api.telegram.org, e.g.
using a wrong token or not existing API calls. If you have a fixed IP you can
ask telegram service to unblock your ip or change your IP. If you are running a
tor proxy on your server you may uncomment the ```BASHBOT_CURL_ARGS``` line in
'mycommands.sh'
You can test if younare blockeds by running curl or wget manually:
```bash
curl -m 10 https://api.telegram.org/bot
#curl: (28) Connection timed out after 10001 milliseconds
@ -314,12 +319,6 @@ wget -t 1 -T 10 https://api.telegram.org/bot
#Connecting to api.telegram.org (api.telegram.org)|46.38.243.234|:443...
failed: Connection timed out.
```
This may happen if to many wrong requests are sent to api.telegram.org, e.g.
using a wrong token or not existing API calls. If you have a fixed IP you can
ask telegram service to unblock your ip or change your IP. If you are running a
socks or tor proxy on your server look for the ```BASHBOT_CURL_ARGS``` lines
in 'mycommands.sh' as example.
@Gnadelwartz
@ -328,4 +327,4 @@ in 'mycommands.sh' as example.
If you feel that there's something missing or if you found a bug, feel free to
submit a pull request!
#### $$VERSION$$ v0.98-dev-47-gba614b7
#### $$VERSION$$ v0.98-dev-69-gafa8d87

8
doc/2_usage.md
View File

@ -1,5 +1,5 @@
#### [Home](../README.md)
## Gettting Started
## Getting Started
The Bots standard commands are in the commands dispatcher ```commands.sh```, Do not edit this file! Add your commands and functions to ```mycommands.sh```. In 'mycommands.sh.dist' you find examples how to add own commands and overwrite existing ones. See [Best practices](5_practice.md) for more information.
@ -95,7 +95,7 @@ To send a broadcast to all of users that ever used the bot run the following com
----
## Recieve data
## Receive data
Evertime a Message is received, you can read incoming data using the following variables:
### Regular Messages
@ -163,7 +163,7 @@ The following variables are set if the message contains optional parts:
Service Messages are regular messages not itended for end users, instead they signal special events to the
client, e.g. new users.
If a service message is recieved bashbot sets MESSAGE to the service message type as a command,
If a service message is received bashbot sets MESSAGE to the service message type as a command,
e.g. if a new user joins a chat MESSAGE is set to "/new_chat_user".
* ```$SERVICE```: This array contains info abbout recived service messages.
@ -281,5 +281,5 @@ send_action "${CHAT[ID]}" "action"
#### [Prev Create Bot](1_firstbot.md)
#### [Next Advanced Usage](3_advanced.md)
#### $$VERSION$$ v0.98-dev-47-gba614b7
#### $$VERSION$$ v0.98-dev-69-gafa8d87

6
doc/3_advanced.md
View File

@ -41,7 +41,7 @@ In addition you can check individual capabilities of users as you must define in
987654321:start:98979695
# * are only allowed on the right hand side and not for user!
# the following exaples are NOT valid!
# the following examples are NOT valid!
*:*:*
*:start:*
*:*:98979695
@ -226,7 +226,7 @@ massive aoumnt of messages. By default bashbot detects if a message is not sent
e.g. resend on throttling. In addtion every send error is logged in logs/ERROR.log
#### Trasmission results
#### Transmission results
On every message send to telegram (transmission) the results are provided in bash variables, like its done when a new message
is received.
@ -289,5 +289,5 @@ Note: If you disable automatic retry, se above, you disable also connection prob
#### [Prev Getting started](2_usage.md)
#### [Next Expert Use](4_expert.md)
#### $$VERSION$$ v0.96-0-g3871ca9
#### $$VERSION$$ v0.98-dev-69-gafa8d87

12
doc/4_expert.md
View File

@ -50,7 +50,7 @@ Most complete support for decoding of multibyte characters can only be provided
### Run as other user or system service
Bashbot is desingned to run manually by the user who installed it. Nevertheless it's possible to run it by an other user-ID, as a system service or sceduled from cron. This is onyl recommended for experiend linux users.
Bashbot is desingned to run manually by the user who installed it. Nevertheless it's possible to run it by an other user-ID, as a system service or scheduled from cron. This is onyl recommended for experiend linux users.
Setup the environment for the user you want to run bashbot and enter desired username, e.g. nobody :
```bash
@ -95,7 +95,7 @@ To change back the environment to your user-ID run ```sudo ./bashbot.sh init```
To use bashbot as a system servive include a working ```bashbot.rc``` in your init system (systemd, /etc/init.d).
### Scedule bashbot from Cron
### Schedule bashbot from Cron
An example crontab is provided in ```examples/bashbot.cron```.
- If you are running bashbot with your user-ID, copy the examples lines to your crontab and remove username ```nobody```.
@ -147,7 +147,7 @@ BOTTOKEN # default: content of ${TOKENFILE}
URL # telegram api URL - default: https://api.telegram.org/bot${BOTTOKEN}"
```
#### Interacctive use
#### Interactive use
For testing your setup or sending messages yoursel you can use bashbot functions from bash command line:
```bash
# are we running bash?
@ -206,7 +206,7 @@ This section describe how you can customize bashbot to your needs by setting env
#### Change file locations
In standard setup bashbot is self containing, this means you can place 'telegram-bot-bash' any location
and run it from there. All files - programm, config, data etc - will reside in 'telegram-bot-bash'.
and run it from there. All files - program, config, data etc - will reside in 'telegram-bot-bash'.
If you want to have other locations for config, data etc, define and export the following environment variables.
**Note: all specified directories and files must exist or running 'bashbot.sh' will fail.**
@ -338,7 +338,7 @@ for every poll until the maximum of BASHBOT_SLEEP ms.
```
#### Testet configs as of v0.90 release
#### Tested configs as of v0.90 release
**Note: Environment variables are not stored, you must setup them before every call to bashbot.sh, e.g. from a script.**
##### simple Unix like config, for one bot. bashbot is installed in '/usr/local/telegram-bot-bash'
@ -382,5 +382,5 @@ for every poll until the maximum of BASHBOT_SLEEP ms.
#### [Prev Advanced Use](3_advanced.md)
#### [Next Best Practice](5_practice.md)
#### $$VERSION$$ v0.96-0-g3871ca9
#### $$VERSION$$ v0.98-dev-69-gafa8d87

10
doc/5_practice.md
View File

@ -7,7 +7,7 @@ If you are new to Bot development read [Bots: An introduction for developers](ht
In addition you should know about [BotFather, the one bot to rule them all](https://core.telegram.org/bots#3-how-do-i-create-a-bot). It will help you create new bots and change settings for existing ones. [Commands known by Botfather](https://core.telegram.org/bots#generating-an-authorization-token)
If you dont't have a github account, it may time to [sepup a free account now](https://github.com/pricing)
If you don't have a github account, it may time to [setup a free account now](https://github.com/pricing)
### Add commands to mycommands.sh only
To ease updates never change ```bashbot.sh```, instead your commands and functions must go to ```mycommands.sh``` . Insert your Bot commands in the ```case ... esac``` block of the 'mycommands()' function:
@ -67,12 +67,12 @@ In case you want to add some processing to the global bashbot command add ```ret
```
### Seperate logic from commands
### Separate logic from commands
If a command need more than 2-3 lines of code, you should use a function to seperate logic from command. Place your functions in ```mycommands.sh``` and call the from your command. Example:
If a command need more than 2-3 lines of code, you should use a function to separate logic from command. Place your functions in ```mycommands.sh``` and call the from your command. Example:
```bash
# file: mycommands.sh
# your additional bahsbot commands
# your additional bashbot commands
mycommands() {
@ -152,5 +152,5 @@ The second warning is about an unused variable, this is true because in our exam
#### [Prev Best Practice](5_practice.md)
#### [Next Functions Reference](6_reference.md)
#### $$VERSION$$ v0.96-0-g3871ca9
#### $$VERSION$$ v0.98-dev-69-gafa8d87

56
doc/6_reference.md
View File

@ -126,7 +126,7 @@ send_file "${CHAT[ID]}" "https://www.domain,com/something.gif" "Something"
----
##### send_keyboard
Note: since version 0.6 send_keyboard was changed to use native "JSON Array" notation as used from Telegram. Example Keybord Array definitions:
Note: since version 0.6 send_keyboard was changed to use native "JSON Array" notation as used from Telegram. Example Keyboard Array definitions:
- yes no in two rows:
- OLD format: 'yes' 'no' (two strings)
@ -134,7 +134,7 @@ Note: since version 0.6 send_keyboard was changed to use native "JSON Array" not
- new layouts made easy with NEW format:
- Yes No in one row: '[ "yes" , "no" ]'
- Yes No plus Maybe in 2.row: '[ "yes" , "no" ] , [ "maybe" ]'
- numpad style keyboard: '[ "1" , "2" , "3" ] , [ "4" , "5" , "6" ] , [ "7" , "8" , "9" ] , [ "0" ]'
- number pad style keyboard: '[ "1" , "2" , "3" ] , [ "4" , "5" , "6" ] , [ "7" , "8" , "9" ] , [ "0" ]'
*usage:* send_keyboard "chat-id" "message" "keyboard"
@ -175,7 +175,7 @@ This allows to place multiple inline buttons in a row. The inline buttons must s
```[ {"text":"text1", "url":"url1"}, ... {"text":"textN", "url":"urlN"} ]```
Each button consists of a pair of text and URL values, sourrounded by '{ }', multiple buttons are seperated by '**,**' and everthing is wrapped in '[ ]'.
Each button consists of a pair of text and URL values, sourrounded by '{ }', multiple buttons are separated by '**,**' and everthing is wrapped in '[ ]'.
*usage:* send_inline_keyboard "chat-id" "message" "[ {"text":"text", "url":"url"} ...]"
@ -204,7 +204,7 @@ If your Bot is a chat admin he can kick and ban a user.
*alias:* _kick_user "${USER[ID]}"
##### unban_chat_member
If your Bot is a chat admine can unban a kicked user.
If your Bot is a chat admin can unban a kicked user.
*usage:* unban_chat_member "${CHAT[ID]}" "${USER[ID]}"
@ -295,7 +295,7 @@ It send back only one response to an inline query.
##### answer_inline_multi
anser_inline_multi allows you to send back a list of responses. responses must be seperated by ','.
anwser_inline_multi allows you to send back a list of responses. Responses must be separated by ','.
*usage:* answer_inline_multi "${iQUERY[ID]}" "res, res, ... res"
@ -351,7 +351,7 @@ see [InlineQueryResult for more information](https://core.telegram.org/bots/api#
### Background and Interactive jobs
Background functions and interactive jobs extends the bot functionality to not only react to user input. You can start scripts for interative
Background functions and interactive jobs extends the bot functionality to not only react to user input. You can start scripts for interactive
chats and send messages based on time or other external events.
##### start_proc
@ -402,7 +402,7 @@ fi
----
##### start_back
Starts a script as a background job and attaches a jobname to it. All output from a background job is sent to the associated chat.
Starts a script as a background job and attaches a job name to it. All output from a background job is sent to the associated chat.
In contrast to interactive chats, background jobs do not receive user input and can run forever. In addition you can suspend and restart running jobs, e.g. after reboot.
@ -453,7 +453,7 @@ fi
##### send_interactive
Form version 0.80 on forward_message is used to forward messages to interactive job. It replaces the old 'inproc' commands used for TMUX.
Usually message is automatically forwarded in 'commands.sh', but you can forward messages wihle processing also or send your own messages.
Usually a message is automatically forwarded in 'commands.sh', but you can forward messages while processing also or send your own messages.
*usage:* send_interactive "${CHAT[ID]}" "message"
@ -463,17 +463,17 @@ Usually message is automatically forwarded in 'commands.sh', but you can forwar
### jsshDB
Since output generated by JSON.sh is so handy to use in bash, we use the format for a simple keys/value file store.
The file extions is '.jssh' and for security reasons location of jssh files is restricted to BASHBOT_ETC and BASHBOT_DATA..
The file extentions is '.jssh' and for security reasons location of jssh files is restricted to BASHBOT_ETC and BASHBOT_DATA..
#### fast and slow operations
jsshDB files are simple text files and if you append a new Key/value pairs to the end of the file it overwrites
an existing key/value pair. We use this behaivor for "fast" file operations.
an existing key/value pair. We use this behavior for "fast" file operations.
"fast funtions" add a new key/value pair to the end of the file without deleting an existing one, this is fast but over (long)
time the file grows infinitly.
"fast functions" add a new key/value pair to the end of the file without deleting an existing one, this is fast but over (long)
time the file grows infinity.
"slow funtions" in contrast modify the key/value pairs in place and write the whole file back,
"slow functions" in contrast modify the key/value pairs in place and write the whole file back,
this is slower but clean up the file. All previously added key/value pairs are replaced
and only the last one is written back to the file.
@ -499,7 +499,7 @@ A jssh fileDB consists of two files which must reside inside BASHBOT_ETC or BAS
Path names containing `..` or not located in BASHBOT_ETC or BASHBOT_DATA are refused by jsshDB functions with an error.
Since version 0.94 jsshDB functions support file locking with flock. write/update operations are serialised with flock to wait until
Since version 0.94 jsshDB functions support file locking with flock. Write/update operations are serialised with flock to wait until
previous operations are finished, see "man flock" for information. To avoid deadlocks we use a timeout of 10s for write and 5s for read operations.
Every jssh_*DB function exist as jssj_*DB_async also.
@ -592,7 +592,7 @@ cat "${DATADIR:-}/myvalues.jssh"
```
##### jssh_printDB
Print content of an ARRAY to STDOUT. ARRAY name must be delared with "declare -A ARRAY" before calling printDB..
Print content of an ARRAY to STDOUT. ARRAY name must be declared with "declare -A ARRAY" before calling printDB..
*usage:* jssh_printDB "ARRAY"
@ -614,7 +614,7 @@ jssh_printDB READVALUES
```
##### jssh_updateDB
Update/Add content of an ARRAY into a jsshDB file. ARRAY name must be delared with "declare -A ARRAY" before calling updateDB.
Update/Add content of an ARRAY into a jsshDB file. ARRAY name must be declared with "declare -A ARRAY" before calling updateDB.
"DB" file MUST exist or nothing is written.
Note: Existing content not in ARRAY is kept in file.
@ -649,14 +649,14 @@ cat "$DBfile"
```
##### jssh_readDB
Read content of a file in JSON.sh format into given ARRAY. ARRAY name must be delared with "declare -A ARRAY" upfront,
Read content of a file in JSON.sh format into given ARRAY. ARRAY name must be declared with "declare -A ARRAY" upfront,
*usage:* jssh_readDB "ARRAY" "filename"
*usage:* jssh_readDB_async "ARRAY" "filename"
Note: readDB uses concurrent / shared locking from flock so multiple proceses can read from file, as long no process is writing.
Maximum timeour for reading is 1s to not block readers.
Note: readDB uses concurrent / shared locking from flock so multiple processes can read from file, as long no process is writing.
Maximum timeout for reading is 1s to not block readers.
*example:*
```bash
@ -720,7 +720,7 @@ jssh_insertKeyDB "newkey" "an other value" "${DATADIR:-.}/myvalues"
```
##### jssh_deleteKeyDB
Deleted a key=value pair froma jsshDB file, key name is only allowed to contain '-a-zA-Z0-9,._'
Deleted a key=value pair from a jsshDB file, key name is only allowed to contain '-a-zA-Z0-9,._'
*usage:* jssh_deleteKeyDB "key" "filename"
@ -754,7 +754,7 @@ https://linuxconfig.org/how-to-use-arrays-in-bash-script
----
### Aliases - shortcuts for often used funtions
### Aliases - shortcuts for often used functions
Aliases are handy shortcuts for using in 'mycommands.sh', they avoid error prone typing of "${CHAT[ID]}" "${USER[ID]}" as much as possible.
Do not use them in bashbot.sh, modules and addons.
@ -855,7 +855,7 @@ Do not use them in bashbot.sh, modules and addons.
##### download
Download the fiven URL ans returns the final filename in TMPDIR. If the given filename exists,the filename is prefixed with a
random number. filename is not allowed to contain '/' or '..'.
random number. Filename is not allowed to contain '/' or '..'.
*usage:* download URL filename
@ -986,7 +986,7 @@ Reads JSON fro STDIN and Outputs found Value to STDOUT
##### Json2Array
Read JSON.sh style data from STDIN and asssign to given ARRAY
Read JSON.sh style data from STDIN and assign to given ARRAY
ARRAY name must be declared with "declare -A ARRAY" before calling
*usage:* Json2Array "ARRAY"
@ -1005,13 +1005,13 @@ Output ARRAY as JSON.sh style data to STDOUT
----
##### process_client
Every Message sent to your Bot is processd by this function. It parse the send JSON and assign the found Values to bash variables.
Every Message sent to your Bot is processed by this function. It parse the send JSON and assign the found Values to bash variables.
##### process_updates
If new updates are availible, this functions gets the JSON from Telegram and dispatch it.
If new updates are available, this functions gets the JSON from Telegram and dispatch it.
##### process_inline
Every Inline Message sent to your Bot is processd by this function. It parse the send JSON and assign the found Values to bash variables.
Every Inline Message sent to your Bot is processed by this function. It parse the send JSON and assign the found Values to bash variables.
##### start_timer
Start the the every minute timer ...
@ -1028,12 +1028,12 @@ Dispatcher for BASHBOT_EVENT_MESSAGE and related
----
##### getBotName
The name of your bot is availible as bash variable "$ME", there is no need to call this function if Bot is running.
The name of your bot is available as bash variable "$ME", there is no need to call this function if Bot is running.
*usage:* ME="$(getBotName)"
#### [Prev Best Practice](5_practice.md)
#### [Next Notes for Developers](7_develop.md)
#### $$VERSION$$ v0.96-0-g3871ca9
#### $$VERSION$$ v0.98-dev-69-gafa8d87

6
doc/7_develop.md
View File

@ -283,7 +283,7 @@ For a shell script running as a service it's important to be paranoid about quot
To run shellcheck for a single script run ```shellcheck -x script.sh```, to check all schripts run ```dev/hooks/pre-commit.sh```.
### bashbot tests
### bashbot test suite
Starting with version 0.70 bashbot has a test suite. To start testsuite run ```dev/all-tests.sh```. all-tests.sh will return 'SUCCESS' only if all tests pass.
#### enabling / disabling tests
@ -302,7 +302,7 @@ A temporary test environment is created when 'ALL-tests.sh' starts and deleted a
The file ```ALL-tests.inc.sh``` must be included from all tests and provide the test environment as shell variables:
```bash
# Test Evironment
# Test Environment
TESTME="$(basename "$0")"
DIRME="$(pwd)"
TESTDIR="$1"
@ -347,5 +347,5 @@ fi
#### [Prev Function Reference](6_reference.md)
#### $$VERSION$$ v0.96-0-g3871ca9
#### $$VERSION$$ v0.98-dev-69-gafa8d87