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

adjust documenation

This commit is contained in:
Kay Marquardt (Gnadelwartz) 2019-05-30 12:03:40 +02:00
parent 5779accfe8
commit 60b1a59a8e
6 changed files with 297 additions and 306 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

15
README.html
View File

@ -92,6 +92,8 @@ code > span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Inf
<li>Handling UTF-8 character sets</li>
<li>Run as other user or system service</li>
<li>Scedule bashbot from Cron</li>
<li>Use from CLI and Scripts</li>
<li>Customize Bashbot Environment</li>
</ul></li>
<li><a href="doc/5_practice.md">Best Practices</a>
<ul>
@ -108,17 +110,12 @@ code > span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Inf
</ul></li>
<li><a href="doc/7_develop.md">Deveoper Notess</a>
<ul>
<li>Debug bashbot</li>
<li>Modules, addons, events</li>
<li>Setup your environment</li>
<li>Test, Add, Push changes</li>
<li>Prepare a new version</li>
<li>Bashbot testsuite</li>
</ul></li>
<li><a href="doc/8_custom.md">Expert Use</a>
<ul>
<li>Use from CLI and Scripts</li>
<li>Customize Bashbot Environment</li>
</ul></li>
<li><a href="examples/README.md">Examples</a></li>
<li><a href="examples/README.md">Examples Dir</a></li>
</ul>
<h3 id="your-really-first-bashbot-in-a-nutshell">Your really first bashbot in a nutshell</h3>
<p>To install and run bashbot you need acess to a linux/unix/bsd 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>
@ -193,6 +190,6 @@ It features background tasks and interactive chats, and can serve as an interfac
<p><span class="citation">@Gnadelwartz</span></p>
<h2 id="thats-it">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 id="version-v0.90-dev2-0-gec85636"><br /><span class="math display"><em>V</em><em>E</em><em>R</em><em>S</em><em>I</em><em>O</em><em>N</em></span><br /> v0.90-dev2-0-gec85636</h4>
<h4 id="version-v0.90-dev2-19-g5779acc"><br /><span class="math display"><em>V</em><em>E</em><em>R</em><em>S</em><em>I</em><em>O</em><em>N</em></span><br /> v0.90-dev2-19-g5779acc</h4>
</body>
</html>

13
README.md
View File

@ -41,6 +41,8 @@ Bashbot [Documentation](https://github.com/topkecleon/telegram-bot-bash) and [Do
* Handling UTF-8 character sets
* Run as other user or system service
* Scedule bashbot from Cron
* Use from CLI and Scripts
* Customize Bashbot Environment
* [Best Practices](doc/5_practice.md)
* Customize commands.sh
* Seperate logic from commands
@ -51,14 +53,11 @@ Bashbot [Documentation](https://github.com/topkecleon/telegram-bot-bash) and [Do
* Inline Queries
* Background and Interactive Jobs
* [Deveoper Notess](doc/7_develop.md)
* Debug bashbot
* Modules, addons, events
* Setup your environment
* Test, Add, Push changes
* Prepare a new version
* Bashbot testsuite
* [Expert Use](doc/8_custom.md)
* Use from CLI and Scripts
* Customize Bashbot Environment
* [Examples](examples/README.md)
* [Examples Dir](examples/README.md)
### Your really first bashbot in a nutshell
To install and run bashbot you need acess to a linux/unix/bsd command line. If you don't know how to get accces to a linux/unix/bsd like command line you should stop reading here :-(
@ -182,4 +181,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.90-dev2-0-gec85636
#### $$VERSION$$ v0.90-dev2-19-g5779acc

13
README.txt
View File

@ -53,6 +53,8 @@ all](https://core.telegram.org/bots#3-how-do-i-create-a-bot)
* Handling UTF-8 character sets
* Run as other user or system service
* Scedule bashbot from Cron
* Use from CLI and Scripts
* Customize Bashbot Environment
* [Best Practices](doc/5_practice.md)
* Customize commands.sh
* Seperate logic from commands
@ -63,14 +65,11 @@ all](https://core.telegram.org/bots#3-how-do-i-create-a-bot)
* Inline Queries
* Background and Interactive Jobs
* [Deveoper Notess](doc/7_develop.md)
* Debug bashbot
* Modules, addons, events
* Setup your environment
* Test, Add, Push changes
* Prepare a new version
* Bashbot testsuite
* [Expert Use](doc/8_custom.md)
* Use from CLI and Scripts
* Customize Bashbot Environment
* [Examples](examples/README.md)
* [Examples Dir](examples/README.md)
### Your really first bashbot in a nutshell
To install and run bashbot you need acess to a linux/unix/bsd command line. If
@ -256,4 +255,4 @@ tor proxy on your server you may uncomment the ```BASHBOT_CURL_ARGS``` line in
If you feel that there's something missing or if you found a bug, feel free to
submit a pull request!
#### $$VERSION$$ v0.90-dev2-0-gec85636
#### $$VERSION$$ v0.90-dev2-19-g5779acc

248
doc/4_expert.md
View File

@ -101,8 +101,252 @@ 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```.
- if you run bashbot as an other user or a system service edit ```examples/bashbot.cron``` to fit your needs and replace username```nobody``` with the username you want to run bashbot. copy the modified file to ```/etc/cron.d/bashbot```
#### [Prev Expert Use](4_expert.md)
### Use bashbot from CLI and scripts
You can use bashbot to send *messages*, *locations*, *venues*, *pictures* etc. from command line and scripts
by sourcing it:
*usage:* . bashbot.sh source
Before sourcing 'bahsbot.sh' for interactive and script use, you should export and set BASHBOT_HOME to bashbots installation dir,
e.g. '/usr/local/telegram-bot-bash'. see [Bashbot Environemt](#Bashbot-environment)
**Note:** *If you don't set BASHBOT_HOME bashbot will use the actual directory as NEW home directory
which means it will create all needed files and ask for bot token and botadmin if you are not in the real bot home!*
*Examples:*
```bash
# if you are in the bashbot directory
. bashbot.sh source
# same, but more readable in scripts
source ./bashbot.sh source
# use bashbot config in BASHBOT_HOME from any directory
export BASHBOT_HOME=/usr/local/telegram-bot-bash
source ${BASHBOT_HOME}/bashbot.sh source
# use / create new config in current directory
unset BASHBOT_HOME
source /path/to/bashbot.sh source
```
#### Environment variable exported from bashbot
If you have sourced 'bashbot.sh' you have the following bashot internal variables availible:
```bash
COMMANDS # default: ./commands.sh"
MODULEDIR # default: ./modules"
TOKENFILE # default: ./token"
BOTADMIN # default: ./botadmin"
BOTACL # default: ./botacl"
TMPDIR # default: ./data-bot-bash"
COUNTFILE # default: ./count"
BOTTOKEN # default: content of ${TOKENFILE}
URL # telegram api URL - default: https://api.telegram.org/bot${BOTTOKEN}"
```
#### Interacctive use
For testing your setup or sending messages yoursel you can use bashbot functions from bash command line:
```bash
# are we running bash?
echo $SHELL
/bin/bash
# source bashbot.sh WITHOUT BASHBOT_HOME set
./bashbot.sh source
# output bashbot internal variables
echo $COMMANDS $MODULEDIR $TOKENFILE $BOTADMIN $BOTACL $TMPDIR $COUNTFILE
./commands.sh ./modules ./token ./botadmin ./botacl ./data-bot-bash ./count
# source bashbot.sh WITH BASHBOT_HOME set
export BASHBOT_HOME=/usr/local/telegram-bot-bash
source ./bashbot.sh source
# output bashbot internal variables
echo $COMMANDS $MODULEDIR $TOKENFILE $BOTADMIN $BOTACL $TMPDIR $COUNTFILE
/usr/local/telegram-bot-bash/commands.sh /usr/local/telegram-bot-bash/modules /usr/local/telegram-bot-bash/token
/usr/local/telegram-bot-bash/botadmin /usr/local/telegram-bot-bash/botacl /usr/local/telegram-bot-bash/data-bot-bash
/usr/local/telegram-bot-bash/count
```
After sourcing you can use bashbot functions to send Messages, Locations, Pictures etc. to any Telegram
User or Chat you are in. See [Send Messages](2_usage.md#sending-messages).
*Examples:* You can test this by sending messages to yourself:
```bash
# fist Hello World
send_normal_message "$(< $BOTADMIN)" "Hello World! This is my first message"
# now with some markdown and HTML
send_markdown_message "$(< $BOTADMIN)" '*Hello World!* _This is my first markdown message_'
send_html_message "$(< $BOTADMIN)" '<b>Hello World!</b> <em>This is my first HTML message</em>'
send_keyboard "$(< $BOTADMIN)" 'Do you like it?' '[ "Yep" , "No" ]'
```
Now something more useful ...
```bash
# sending output from system commands:
send_normal_message "$(< $BOTADMIN)" "$(date)"
send_normal_message "$(< $BOTADMIN)" "$(uptime)"
send_normal_message "$(< $BOTADMIN)" '`'$(free)'`'
# same but markdown style 'code' (monospaced)
send_markdown_message "$(< $BOTADMIN)" "\`$(free)\`"
```
### Bashbot environment
This section describe how you can customize bashbot to your needs by setting environment variables.
#### 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'.
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.**
##### BASHBOT_ETC
Location of the files ```commands.sh```, ```mycommands.sh```, ```token```, ```botadmin```, ```botacl``` ...
```bash
unset BASHBOT_ETC # keep in telegram-bot-bash (default)
export BASHBOT_ETC "" # keep in telegram-bot-bash
export BASHBOT_ETC "/etc/bashbot" # unix like config location
export BASHBOT_ETC "/etc/bashbot/bot1" # multibot configuration bot 1
export BASHBOT_ETC "/etc/bashbot/bot2" # multibot configuration bot 2
```
e.g. /etc/bashbot
##### BASHBOT_VAR
Location of runtime data ```data-bot-bash```, ```count```
```bash
unset BASHBOT_VAR # keep in telegram-bot-bash (default)
export BASHBOT_VAR "" # keep in telegram-bot-bash
export BASHBOT_VAR "/var/spool/bashbot" # unix like config location
export BASHBOT_VAR "/var/spool/bashbot/bot1" # multibot configuration bot 1
export BASHBOT_VAR "/var/spool/bashbot/bot2" # multibot configuration bot 2
```
##### BASHBOT_JSONSH
Full path to JSON.sh script, default: './JSON.sh/JSON.sh', must end with '/JSON.sh'.
```bash
unset BASHBOT_JSONSH # telegram-bot-bash/JSON.sh/JSON.sh (default)
export BASHBOT_JSONSH "" # telegram-bot-bash/JSON.sh/JSON.sh
export BASHBOT_JSONSH "/usr/local/bin/JSON.sh" # installed in /usr/local/bin
```
##### BASHBOT_HOME
Set bashbot home directory, where bashot will look for additional files.
If BASHBOT_ETC, BASHBOT_VAR or BASHBOT_JSONSH are set the have precedence over BASHBOT_HOME.
This is also usefull if you want to force bashbot to always use full pathnames instead of relative ones.
```bash
unset BASHBOT_HOME # autodetection (default)
export BASHBOT_HOME "" # autodetection
export BASHBOT_HOME "/usr/local/telegram-bot-bash" # unix like location
export BASHBOT_HOME "/usr/local/bin" # Note: you MUST set ETC, VAR and JSONSH to other locations to make this work!
```
----
#### Change config values
##### BASHBOT_URL
Uses given URL instead of offical telegram API URL, useful if you have your own telegram server or for testing.
```bash
unset BASHBOT_URL # use Telegram URL https://api.telegram.org/bot<token> (default)
export BASHBOT_URL "" # use use Telegram https://api.telegram.org/bot<token>
export BASHBOT_URL "https://my.url.com/bot" # use your URL https://my.url.com/bot<token>
```
##### BASHBOT_TOKEN
##### BASHBOT_WGET
Bashbot uses ```curl``` to communicate with telegram server. if ```curl``` is not availible ```wget``` is used.
If 'BASHBOT_WGET' is set to any value (not undefined or not empty) wget is used even is curl is availible.
```bash
unset BASHBOT_WGET # use curl (default)
export BASHBOT_WGET "" # use curl
export BASHBOT_WGET "yes" # use wget
export BASHBOT_WGET "no" # use wget!
```
##### BASHBOT_SLEEP
Instead of polling permanently or with a fixed delay, bashbot offers a simple adaptive polling.
If messages are recieved bashbot polls with no dealy. If no messages are availible bashbot add 100ms delay
for every poll until the maximum of BASHBOT_SLEEP ms.
```bash
unset BASHBOT_SLEEP # 5000ms (default)
export BASHBOT_SLEEP "" # 5000ms
export BASHBOT_SLEEP "1000" # 1s maximum sleep
export BASHBOT_SLEEP "10000" # 10s maximum sleep
export BASHBOT_SLEEP "1" # values < 1000 disables sleep (not recommended)
```
#### Testet 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'
```bash
# Note: all dirs and files must exist!
export BASHBOT_ETC "/etc/bashbot"
export BASHBOT_VAR "/var/spool/bashbot"
/usr/local/telegram-bot-bash/bashbot.sh start
```
##### Unix like config for one bot. bashbot.sh is installed in '/usr/bin'
```bash
# Note: all dirs and files must exist!
export BASHBOT_ETC "/etc/bashbot"
export BASHBOT_VAR "/var/spool/bashbot"
export BASHBOT_JSONSH "/var/spool/bashbot"
/usr/local/bin/bashbot.sh start
```
##### simple multibot config, everything is keept inside 'telegram-bot-bash' dir
```bash
# config for running Bot 1
# Note: all dirs and files must exist!
export BASHBOT_ETC "./mybot1"
export BASHBOT_VAR "./mybot1"
/usr/local/telegram-bot-bash/bashbot.sh start
```
```bash
# config for running Bot 2
# Note: all dirs and files must exist!
export BASHBOT_ETC "./mybot2"
export BASHBOT_VAR "./mybot2"
/usr/local/telegram-bot-bash/bashbot.sh start
```
#### [Prev Advanced Use](3_advanced.md)
#### [Next Best Practice](5_practice.md)
#### $$VERSION$$ v0.90-dev2-0-gec85636
#### $$VERSION$$ v0.90-dev2-19-g5779acc

63
doc/7_develop.md
View File

@ -1,4 +1,5 @@
#### [Home](../README.md)
## Notes for bashbot developers
This section is about help and best practices for new bashbot developers. The main focus on is creating new versions of bashbot, not on develop your individual bot. Nevertheless the rules and tools described here can also help you with your bot development.
@ -17,26 +18,26 @@ In addition you can change the change the level of verbosity by adding a third a
```
### Modules and Addons
Modules live in ```modules/*.sh``` are bashbot functions factored out in seperate files, gouped by functionality. Main reason for creating modules was
to make bashbot.sh smaller and contain only initalisation and a basic set of functions. In addition not every functionality is needed ba every bot, so you can
e.g. disable inline or background processing by renaming the respective module files to 'module.sh.off'.
**Modules** live in ```modules/*.sh``` and are bashbot functions factored out in seperate files, gouped by functionality. Main reason for creating modules was
to keep 'bashbot.sh' small, while extending functionality. In addition not every functionality is needed by a bot, so you can
disable modules by removing them, e.g. rename the respective module files to 'module.sh.off'.
Modules must onyl use functions provieded by 'bahsbot.sh' or the module itself, no depedencies to other modules or addons must exist.
If a module function is called from 'bashbot.sh' for whatever reason, you must test with '_is_function' or '_execute_if_function' if the
module is availible.
Modules must use onyl functions provided by 'bahsbot.sh' or the module itself, no depedencies to other modules or addons must exist.
If a module function is called from 'bashbot.sh', bashbot must work if the module is disabled, so it's madatory to use '_is_function'
or '_execute_if_function' if a module function is called.
Addons live in ```addons/*.sh.dist``` and are disabled by default. To activate an addon remove the dist from filename, e.g. ```cp addons/example.sh.dist addons/example.sh```. Addons have to register themself to BASHBOT_EVENTS at startup, e.g. to call a function everytime a message is recieved.
This is similar on how 'commands.sh' works, but imore flexible and a major difference: Addons are executed in the context of the main script,
while 'commands.sh' is executed as a seperate process.
**Addons** live in ```addons/*.sh.dist``` and are disabled by default. To activate an addon remove the '.dist' from filename, e.g. ```cp addons/example.sh.dist addons/example.sh```. Addons must register themself to BASHBOT_EVENTS at startup, e.g. to call a function everytime a message is recieved.
Registering to EVENTS is similar on how 'commands.sh' is ececuted, but more flexible and one major difference:
**Addons are executed in the context of the main script**, while 'commands.sh' is executed as a seperate process.
This is why addons are time critical and must return as fast as possible and spawn every action as a seperate process or function with '&'!
If you want to send out a message from aa addon use ```send_message "${CHAT[ID]}" "Message to send ..." &``` to not wait for completion, witch may take several seconds.
This is why event functions are time critical and must return as fast as possible. Spawn actions as a seperate process or function with '&', e.g.
send a message as respone from an addon: ```send_message "${CHAT[ID]}" "Message to send ..." &```.
### Bashbot Events
Addons can register functions to bashbot events at startup by providing their name and a and a fucnction name per event
If an event occours each registered event function is called.
#### Bashbot Events
Addons can register functions to bashbot events at startup by providing their name and a callback function.
If an event occours each registered function for the event is called.
Events run in the same context as the main bashbot event loop so variables set here are persistent as long bashbot is running.
Events run in the same context as the main bashbot loop, so variables set here are persistent as long bashbot is running.
Note: For the same reason event function MUST return imideatly! Time consuming tasks must be run in background or as a subshell, e.g. "long running &"
@ -52,12 +53,14 @@ Availible events:
* BASHBOT_EVENT_LOCATION a location or a venue is received
* BASHBOT_EVENT_FILE a file is received
*usage*: BASHBOT_EVENT_xxx["name]="function"
*usage*: BASHBOT_EVENT_xxx["uniqe-name"]="callback"
"unique-name" can be every alphanumeric string incl. '-' and '_'. Per convention it should be name of the addon followed by an internal identyfier.
*Example:* Register a function to echo to any Text send to the bot
```bash
# register callback:
BASHBOT_EVENT_TEXT["example"]="example_echo"
BASHBOT_EVENT_TEXT["example_1"]="example_echo"
# function called if a text is recieved
example_echo() {
@ -79,7 +82,7 @@ Registering to BASHBOT_EVENT_TIMER works a little different, you have to add a t
*Examples:*
```bash
# register callback:
BAHSBOT_EVENT_TIMER["example1","1"]="example_everymin"
BAHSBOT_EVENT_TIMER["example_every","1"]="example_everymin"
# function called every minute
example_everymin() {
@ -88,16 +91,16 @@ example_everymin() {
}
# register other callback:
BAHSBOT_EVENT_TIMER["example2","-10"]="example_in10min"
BAHSBOT_EVENT_TIMER["example_10min","-10"]="example_in10min"
BAHSBOT_EVENT_TIMER["example3","5"]="example_every5min"
BAHSBOT_EVENT_TIMER["example_every5","5"]="example_every5min"
```
----
### Create a stripped down Version of your Bot
#### Create a stripped down Version of your Bot
Currently bashbot is more a bot development environment than a bot, containing examples, developer scripts, modules, documentation and more.
You don't need all these files after you're finished with your cool new bot.
@ -120,7 +123,7 @@ Now have a look at the directory 'standalone', here you find the files 'bashbot.
5. give your (dev) fork a new version tag: ```git tag vx.xx```(optional)
6. setup github hooks by running ```dev/install-hooks.sh``` (optional)
### Test, Add, Push changes
#### Test, Add, Push changes
A typical bashbot develop loop looks as follow:
1. start developing - *change, copy, edit bashbot files ...*
@ -132,7 +135,7 @@ A typical bashbot develop loop looks as follow:
**If you setup your dev environment with hooks and use the scripts above, versioning, addding and testing is done automatically.**
### common commands
#### common commands
We state bashbot is a bash only bot, but this is not true. bashbot is a bash script using bash features PLUS external commands.
Usually bash is used in a unix/linux environment where many (GNU) commands are availible, but if commands are missing, bashbot may not work.
@ -175,7 +178,7 @@ INDEX="$(( ${INDEX} + 1 ))" -> (( INDEX++ ))
```
For more examples see [Pure bash bible](https://github.com/dylanaraps/pure-bash-bible)
### Prepare a new version
#### Prepare a new version
After some development it may time to create a new version for the users. a new version can be in sub version upgrade, e.g. for fixes and smaller additions or
a new release version for new features. To mark a new version use ```git tag NEWVERSION``` and run ```dev/version.sh``` to update all version strings.
@ -186,7 +189,7 @@ Usually I start with pre versions and when everything looks good I push out a re
If you release a new Version run ```dev/make-distribution.sh``` to create the zip and tar.gz archives in the dist directory and attach them to the github release. Do not forget to delete directory dist afterwards.
### Versioning
#### Versioning
Bashbot is tagged with version numbers. If you start a new development cycle you can tag your fork with a version higher than the current version.
E.g. if you fork 'v0.60' the next develop version should tagged as ```git tag "v0.61-dev"``` for fixes or ```git tag "v0.70-dev"``` for new features.
@ -197,22 +200,22 @@ To update the Version Number in files run ```dev/version.sh files```, it will up
To update version in all files run 'dev/version.sh' without parameter.
### Shellcheck
#### Shellcheck
For a shell script running as a service it's important to be paranoid about quoting, globbing and other common problems. So it's a must to run shellchek on all shell scripts before you commit a change. this is automated by a git hook activated in Setup step 6.
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 tests
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
#### enabling / disabling tests
All tests are placed in the directory ```test```. To disable a test remove the execute flag from the '*-test.sh' script, to (re)enable a test make the script executable again.
### creating new tests
#### creating new tests
To create a new test run ```test/ADD-test-new.sh``` and answer the questions, it will create the usually needed files and dirs:
Each test consists of a script script named after ```p-name-test.sh``` *(where p is test pass 'a-z' and name the name
@ -269,5 +272,5 @@ fi
#### [Prev Function Reference](6_reference.md)
#### [Next Expert Use](8_custom.md)
#### $$VERSION$$ v0.90-dev2-18-ga1a4829
#### $$VERSION$$ v0.90-dev2-19-g5779acc

251
doc/8_custom.md
View File

@ -1,251 +0,0 @@
#### [Home](../README.md)
## Expert use
### Use bashbot from CLI and scripts
You can use bashbot to send *messages*, *locations*, *venues*, *pictures* etc. from command line and scripts
by sourcing it:
*usage:* . bashbot.sh source
Before sourcing 'bahsbot.sh' for interactive and script use, you should export and set BASHBOT_HOME to bashbots installation dir,
e.g. '/usr/local/telegram-bot-bash'. see [Bashbot Environemt](#Bashbot-environment)
**Note:** *If you don't set BASHBOT_HOME bashbot will use the actual directory as NEW home directory
which means it will create all needed files and ask for bot token and botadmin if you are not in the real bot home!*
*Examples:*
```bash
# if you are in the bashbot directory
. bashbot.sh source
# same, but more readable in scripts
source ./bashbot.sh source
# use bashbot config in BASHBOT_HOME from any directory
export BASHBOT_HOME=/usr/local/telegram-bot-bash
source ${BASHBOT_HOME}/bashbot.sh source
# use / create new config in current directory
unset BASHBOT_HOME
source /path/to/bashbot.sh source
```
#### Environment variable exported from bashbot
If you have sourced 'bashbot.sh' you have the following bashot internal variables availible:
```bash
COMMANDS # default: ./commands.sh"
MODULEDIR # default: ./modules"
TOKENFILE # default: ./token"
BOTADMIN # default: ./botadmin"
BOTACL # default: ./botacl"
TMPDIR # default: ./data-bot-bash"
COUNTFILE # default: ./count"
BOTTOKEN # default: content of ${TOKENFILE}
URL # telegram api URL - default: https://api.telegram.org/bot${BOTTOKEN}"
```
#### Interacctive use
For testing your setup or sending messages yoursel you can use bashbot functions from bash command line:
```bash
# are we running bash?
echo $SHELL
/bin/bash
# source bashbot.sh WITHOUT BASHBOT_HOME set
./bashbot.sh source
# output bashbot internal variables
echo $COMMANDS $MODULEDIR $TOKENFILE $BOTADMIN $BOTACL $TMPDIR $COUNTFILE
./commands.sh ./modules ./token ./botadmin ./botacl ./data-bot-bash ./count
# source bashbot.sh WITH BASHBOT_HOME set
export BASHBOT_HOME=/usr/local/telegram-bot-bash
source ./bashbot.sh source
# output bashbot internal variables
echo $COMMANDS $MODULEDIR $TOKENFILE $BOTADMIN $BOTACL $TMPDIR $COUNTFILE
/usr/local/telegram-bot-bash/commands.sh /usr/local/telegram-bot-bash/modules /usr/local/telegram-bot-bash/token
/usr/local/telegram-bot-bash/botadmin /usr/local/telegram-bot-bash/botacl /usr/local/telegram-bot-bash/data-bot-bash
/usr/local/telegram-bot-bash/count
```
After sourcing you can use bashbot functions to send Messages, Locations, Pictures etc. to any Telegram
User or Chat you are in. See [Send Messages](2_usage.md#sending-messages).
*Examples:* You can test this by sending messages to yourself:
```bash
# fist Hello World
send_normal_message "$(< $BOTADMIN)" "Hello World! This is my first message"
# now with some markdown and HTML
send_markdown_message "$(< $BOTADMIN)" '*Hello World!* _This is my first markdown message_'
send_html_message "$(< $BOTADMIN)" '<b>Hello World!</b> <em>This is my first HTML message</em>'
send_keyboard "$(< $BOTADMIN)" 'Do you like it?' '[ "Yep" , "No" ]'
```
Now something more useful ...
```bash
# sending output from system commands:
send_normal_message "$(< $BOTADMIN)" "$(date)"
send_normal_message "$(< $BOTADMIN)" "$(uptime)"
send_normal_message "$(< $BOTADMIN)" '`'$(free)'`'
# same but markdown style 'code' (monospaced)
send_markdown_message "$(< $BOTADMIN)" "\`$(free)\`"
```
### Bashbot environment
This section describe how you can customize bashbot to your needs by setting environment variables.
#### 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'.
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.**
##### BASHBOT_ETC
Location of the files ```commands.sh```, ```mycommands.sh```, ```token```, ```botadmin```, ```botacl``` ...
```bash
unset BASHBOT_ETC # keep in telegram-bot-bash (default)
export BASHBOT_ETC "" # keep in telegram-bot-bash
export BASHBOT_ETC "/etc/bashbot" # unix like config location
export BASHBOT_ETC "/etc/bashbot/bot1" # multibot configuration bot 1
export BASHBOT_ETC "/etc/bashbot/bot2" # multibot configuration bot 2
```
e.g. /etc/bashbot
##### BASHBOT_VAR
Location of runtime data ```data-bot-bash```, ```count```
```bash
unset BASHBOT_VAR # keep in telegram-bot-bash (default)
export BASHBOT_VAR "" # keep in telegram-bot-bash
export BASHBOT_VAR "/var/spool/bashbot" # unix like config location
export BASHBOT_VAR "/var/spool/bashbot/bot1" # multibot configuration bot 1
export BASHBOT_VAR "/var/spool/bashbot/bot2" # multibot configuration bot 2
```
##### BASHBOT_JSONSH
Full path to JSON.sh script, default: './JSON.sh/JSON.sh', must end with '/JSON.sh'.
```bash
unset BASHBOT_JSONSH # telegram-bot-bash/JSON.sh/JSON.sh (default)
export BASHBOT_JSONSH "" # telegram-bot-bash/JSON.sh/JSON.sh
export BASHBOT_JSONSH "/usr/local/bin/JSON.sh" # installed in /usr/local/bin
```
##### BASHBOT_HOME
Set bashbot home directory, where bashot will look for additional files.
If BASHBOT_ETC, BASHBOT_VAR or BASHBOT_JSONSH are set the have precedence over BASHBOT_HOME.
This is also usefull if you want to force bashbot to always use full pathnames instead of relative ones.
```bash
unset BASHBOT_HOME # autodetection (default)
export BASHBOT_HOME "" # autodetection
export BASHBOT_HOME "/usr/local/telegram-bot-bash" # unix like location
export BASHBOT_HOME "/usr/local/bin" # Note: you MUST set ETC, VAR and JSONSH to other locations to make this work!
```
----
#### Change config values
##### BASHBOT_URL
Uses given URL instead of offical telegram API URL, useful if you have your own telegram server or for testing.
```bash
unset BASHBOT_URL # use Telegram URL https://api.telegram.org/bot<token> (default)
export BASHBOT_URL "" # use use Telegram https://api.telegram.org/bot<token>
export BASHBOT_URL "https://my.url.com/bot" # use your URL https://my.url.com/bot<token>
```
##### BASHBOT_TOKEN
##### BASHBOT_WGET
Bashbot uses ```curl``` to communicate with telegram server. if ```curl``` is not availible ```wget``` is used.
If 'BASHBOT_WGET' is set to any value (not undefined or not empty) wget is used even is curl is availible.
```bash
unset BASHBOT_WGET # use curl (default)
export BASHBOT_WGET "" # use curl
export BASHBOT_WGET "yes" # use wget
export BASHBOT_WGET "no" # use wget!
```
##### BASHBOT_SLEEP
Instead of polling permanently or with a fixed delay, bashbot offers a simple adaptive polling.
If messages are recieved bashbot polls with no dealy. If no messages are availible bashbot add 100ms delay
for every poll until the maximum of BASHBOT_SLEEP ms.
```bash
unset BASHBOT_SLEEP # 5000ms (default)
export BASHBOT_SLEEP "" # 5000ms
export BASHBOT_SLEEP "1000" # 1s maximum sleep
export BASHBOT_SLEEP "10000" # 10s maximum sleep
export BASHBOT_SLEEP "1" # values < 1000 disables sleep (not recommended)
```
#### Testet configs as of v.07 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'
```bash
# Note: all dirs and files must exist!
export BASHBOT_ETC "/etc/bashbot"
export BASHBOT_VAR "/var/spool/bashbot"
/usr/local/telegram-bot-bash/bashbot.sh start
```
##### Unix like config for one bot. bashbot.sh is installed in '/usr/bin'
```bash
# Note: all dirs and files must exist!
export BASHBOT_ETC "/etc/bashbot"
export BASHBOT_VAR "/var/spool/bashbot"
export BASHBOT_JSONSH "/var/spool/bashbot"
/usr/local/bin/bashbot.sh start
```
##### simple multibot config, everything is keept inside 'telegram-bot-bash' dir
```bash
# config for running Bot 1
# Note: all dirs and files must exist!
export BASHBOT_ETC "./mybot1"
export BASHBOT_VAR "./mybot1"
/usr/local/telegram-bot-bash/bashbot.sh start
```
```bash
# config for running Bot 2
# Note: all dirs and files must exist!
export BASHBOT_ETC "./mybot2"
export BASHBOT_VAR "./mybot2"
/usr/local/telegram-bot-bash/bashbot.sh start
```
#### [Prev Notes for Developers](7_develop.md)
#### $$VERSION$$ v0.90-dev2-0-gec85636