mirror of
https://github.com/octoleo/telegram-bot-bash.git
synced 2024-12-27 20:44:53 +00:00
adjust documenation
This commit is contained in:
Kay Marquardt (Gnadelwartz)
parent
5779accfe8
commit
60b1a59a8e
15
README.html
15
README.html
@ -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
13
README.md
@ -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
13
README.txt
@ -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
248
doc/4_expert.md
@ -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
|
||||
|
||||
|
||||
@ -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
251
doc/8_custom.md
@ -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
|
||||
|
||||
Loading…
Reference in New Issue
Block a user