update expert use

This commit is contained in:
Kay Marquardt (Gnadelwartz) 2019-05-23 14:06:38 +02:00
parent e0bb9f85e1
commit b1fb35d421

View File

@ -3,19 +3,23 @@
## Expert use ## Expert use
### Use bashbot from CLI and scripts ### Use bashbot from CLI and scripts
You can use bashbot to send messages, locations, venues, pictures etc from command line and scripts. You can use bashbot to send *messages*, *locations*, *venues*, *pictures* etc. from command line and scripts
by sourcing it:
For interactive use and script use should set and export BASHBOT_HOME to bashbots installation dir, *usage:* . bashbot.sh source
e.g. '/usr/local/telegram-bot-bash'. see [Bashbot environemnt](#Bashbot-environment)
**Note:** If you don't set BASHBOT_HOME bashbot will use the actual directory as NEW home directory Before sourcing 'bahsbot.sh' for interactive and script use, you should export and set BASHBOT_HOME to bashbots installation dir,
which means it will create all needed files and ask for bot token and botadmin if you are not in the real bot home! e.g. '/usr/local/telegram-bot-bash'. see [Bashbot Environemt](#Bashbot-environment)
*usage:* source bashbot.sh source **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:* *Examples:*
```bash ```bash
# if you are in the bashbot directory # if you are in the bashbot directory
. bashbot.sh source
# same, but more readable in scripts
source ./bashbot.sh source source ./bashbot.sh source
# use bashbot config in BASHBOT_HOME from any directory # use bashbot config in BASHBOT_HOME from any directory
@ -27,28 +31,26 @@ unset BASHBOT_HOME
source /path/to/bashbot.sh source source /path/to/bashbot.sh source
``` ```
**Warning:** If you forget the 'source' parameter for bashbot while sourcing you may geht error messages and **Warning:** If you forget the 'source' parameter while sourcing you may geht error messages and
your current shell or script may terminate! your current shell or script may terminate!
#### Environment variable exported from bashbot #### Environment variable exported from bashbot
If you have sourced 'bashbot.sh' you have the following bashot internal variables availible to If you have sourced 'bashbot.sh' you have the following bashot internal variables availible:
locate varoius ressources:
```bash ```bash
COMMANDS # default ./commands.sh" COMMANDS # default: ./commands.sh"
MODULEDIR # default ./modules" MODULEDIR # default: ./modules"
TOKENFILE # default ./token" TOKENFILE # default: ./token"
BOTADMIN # default ./botadmin" BOTADMIN # default: ./botadmin"
BOTACL # default ./botacl" BOTACL # default: ./botacl"
TMPDIR # default ./data-bot-bash" TMPDIR # default: ./data-bot-bash"
COUNTFILE # default ./count" COUNTFILE # default: ./count"
BOTTOKEN # default content of ${TOKENFILE} BOTTOKEN # default: content of ${TOKENFILE}
URL # telegram api URL -default https://api.telegram.org/bot${BOTTOKEN}" URL # telegram api URL - default: https://api.telegram.org/bot${BOTTOKEN}"
``` ```
#### Interacctive use #### Interacctive use
For Test purposes you can use bashbot functions from bash command line after setting BASHBOT_HOME For testing your setup or sending messages yoursel you can use bashbot functions from bash command line:
and sourcing 'bashbot.sh'.
```bash ```bash
# are we running bash? # are we running bash?
echo $SHELL echo $SHELL
@ -57,11 +59,11 @@ echo $SHELL
# source bashbot.sh WITHOUT BASHBOT_HOME set # source bashbot.sh WITHOUT BASHBOT_HOME set
./bashbot.sh source ./bashbot.sh source
# output bashbot internal variables # output bashbot internal variables
echo $COMMANDS $MODULEDIR $TOKENFILE $BOTADMIN $BOTACL $TMPDIR $COUNTFILE echo $COMMANDS $MODULEDIR $TOKENFILE $BOTADMIN $BOTACL $TMPDIR $COUNTFILE
./commands.sh ./modules ./token ./botadmin ./botacl ./data-bot-bash ./count ./commands.sh ./modules ./token ./botadmin ./botacl ./data-bot-bash ./count
# source bashbot.sh WITH BASHBOT_HOME set # source bashbot.sh WITH BASHBOT_HOME set
export BASHBOT_HOME=/usr/local/telegram-bot-bash export BASHBOT_HOME=/usr/local/telegram-bot-bash
source ./bashbot.sh source source ./bashbot.sh source
@ -73,7 +75,7 @@ echo $COMMANDS $MODULEDIR $TOKENFILE $BOTADMIN $BOTACL $TMPDIR $COUNTFILE
/usr/local/telegram-bot-bash/count /usr/local/telegram-bot-bash/count
``` ```
Now you can use the bashot 'send_xxx' functions to send Message, Locations, Pictures etc. to any Telegram 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). User or Chat you are in. See [Send Messages](2_usage.md#sending-messages).
*Examples:* You can test this by sending messages to yourself: *Examples:* You can test this by sending messages to yourself:
@ -86,7 +88,7 @@ send_markdown_message "$(< $BOTADMIN)" '*Hello World!* _This is my first markd
send_html_message "$(< $BOTADMIN)" '<b>Hello World!</b> <em>This is my first HTML message</em>' 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" ]' send_keyboard "$(< $BOTADMIN)" 'Do you like it?' '[ "Yep" , "No" ]'
``` ```
Nnow something more useful ... Now something more useful ...
```bash ```bash
# sending output from system commands: # sending output from system commands:
send_normal_message "$(< $BOTADMIN)" "$(date)" send_normal_message "$(< $BOTADMIN)" "$(date)"
@ -94,7 +96,8 @@ send_normal_message "$(< $BOTADMIN)" "$(date)"
send_normal_message "$(< $BOTADMIN)" "$(uptime)" send_normal_message "$(< $BOTADMIN)" "$(uptime)"
send_normal_message "$(< $BOTADMIN)" '`'$(free)'`' send_normal_message "$(< $BOTADMIN)" '`'$(free)'`'
# same but sent as monospaced text
# same but markdown style 'code' (monospaced)
send_markdown_message "$(< $BOTADMIN)" "\`$(free)\`" send_markdown_message "$(< $BOTADMIN)" "\`$(free)\`"
``` ```
@ -147,17 +150,16 @@ Full path to JSON.sh script, default: './JSON.sh/JSON.sh', must end with '/JSON.
``` ```
##### BASHBOT_HOME ##### BASHBOT_HOME
Bashbot Home directory (where bashbot is installed). If set bashbot autodetection of installation dir is disabled Set bashbot home directory, where bashot will look for additional files.
and value of BASHBOT_HOME is used. If BASHBOT_ETC, BASHBOT_VAR or BASHBOT_JSONSH are set the have precedence over BASHBOT_HOME.
This is usefull if you want to force bashbot to always use full pathnames instead of relative ones or if you This is also usefull if you want to force bashbot to always use full pathnames instead of relative ones.
want to tell your own scripts where to look for bashbot.sh.
```bash ```bash
unset BASHBOT_HOME # autodetection (default) unset BASHBOT_HOME # autodetection (default)
export BASHBOT_HOME "" # autodetection export BASHBOT_HOME "" # autodetection
export BASHBOT_HOME "/usr/local/telegram-bot-bash" # unix like location 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 correct to make this work! export BASHBOT_HOME "/usr/local/bin" # Note: you MUST set ETC, VAR and JSONSH to other locations to make this work!
``` ```
---- ----
@ -247,5 +249,5 @@ for every poll until the maximum of BASHBOT_SLEEP ms.
#### [Prev Notes for Developers](7_develop.md) #### [Prev Notes for Developers](7_develop.md)
#### $$VERSION$$ v0.90-dev-3-g80a4778 #### $$VERSION$$ v0.90-dev-4-ge0bb9f8