octoleo/telegram-bot-bash
1
1
Fork 0
mirror of https://github.com/octoleo/telegram-bot-bash.git synced 2024-11-25 08:47:34 +00:00
Code Issues Projects Releases Wiki Activity

Merge pull request #170 from dcoomber/develop

Browse Source 
Updates to 7_develop
This commit is contained in:
Kay Marquardt 2021-01-05 22:57:11 +01:00 committed by GitHub
commit 8be95a3abf
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
5 changed files with 43 additions and 44 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
README.txt
View File

@ -158,9 +158,10 @@ start debug`
│   ├── BASHBOT.log # log what your bot is doing ... │   ├── BASHBOT.log # log what your bot is doing ...
│   ├── ERROR.log # connection errors from / to Telegram API │   ├── ERROR.log # connection errors from / to Telegram API
│   │ │   │
│   ├── DEBUG.log # stdout/stderr of you bot (debug mode enabled) │   ├── DEBUG.log # stdout/stderr of you bot (debug mode
│   └── MESSAGE.log # full text of all message send/received (debug mode
enabled) enabled)
│   └── MESSAGE.log # full text of all message send/received
(debug mode enabled)
``` ```
---- ----

2
doc/0_install.md
View File

@ -97,7 +97,7 @@ This creates the installation archives in `DIST/` and a ready to run test instal
Use the installation archives to install or update bashbot as described above. Use the installation archives to install or update bashbot as described above.
To run a test bot, e.g. while development or testing latest changes, you can use the bashbot installation provided in `DIST/telegram-bot-bash`. To run a test bot, e.g. while development or testing latest changes, you can use the bashbot installation provided in `DIST/telegram-bot-bash`.
To update the test installation (_after git pull, local changes or switch master/develop_) run `dev/make-distrubition.sh` again. To update the test installation (_after git pull, local changes or switch master/develop_) run `dev/make-distribution.sh` again.
### Note for BSD and MacOS ### Note for BSD and MacOS

2
doc/3_advanced.md
View File

@ -171,7 +171,7 @@ All output of the script will be sent to the user, to stop a background job use:
```bash ```bash
kill_back "${CHAT[ID]}" "jobname" kill_back "${CHAT[ID]}" "jobname"
``` ```
You can also suspend and resume currently running background jobs from outside bashbot, e.g. in your startup schripts: You can also suspend and resume currently running background jobs from outside bashbot, e.g. in your startup scripts:
```bash ```bash
./bashbot.sh suspendback ./bashbot.sh suspendback
./bashbot.sh resumeback ./bashbot.sh resumeback

20
doc/4_expert.md
View File

@ -50,12 +50,12 @@ If you don't know what locales are installed on your sytsem use `locale -a` to d
##### Character classes ##### Character classes
In ASCII times it was clear `[:lower:]` and `[a-z]` means ONLY the lowercase letters `[abcd...xyz]`. In ASCII times it was clear `[:lower:]` and `[a-z]` means ONLY the lowercase letters `[abcd...xyz]`.
With introdution of locales, character classes and ranges contains all characters fitting the class definition. With the introduction of locales, character classes and ranges now contain all characters fitting the class definition.
This means with a Latin UTF-8 locale `[:lower:]` and `[a-z]` contains also e.g. `á ø ü` etc, This means with a Latin UTF-8 locale `[:lower:]` and `[a-z]` contains also e.g. `á ø ü` etc,
see [Unicode Latin lowercase letters](https://www.fileformat.info/info/unicode/category/Ll/list.htm) see [Unicode Latin lowercase letters](https://www.fileformat.info/info/unicode/category/Ll/list.htm)
If that's ok for your script your'e fine, but many scripts rely on the idea of ASCII ranges and may produce undesired results. If that's ok for your script you're fine, but many scripts rely on the idea of ASCII ranges and may produce undesired results.
```bash ```bash
# try with different locales ... # try with different locales ...
@ -101,11 +101,11 @@ The Emoticons ` 😁 😘 ❤️ 😊 👍 ` are encoded as: ` \uD83D\uDE01 \uD8
**This "mixed" JSON encoding needs special handling and can not decoded from** `echo -e` or `printf '%s\\n'` **This "mixed" JSON encoding needs special handling and can not decoded from** `echo -e` or `printf '%s\\n'`
Bbashbot uses an internal, pure bash implementation which is well tested now, even there may some corner cases*. Bashbot uses an internal, pure bash implementation which is well tested now, even there may some corner cases*.
### Run as other user or system service ### 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 scheduled from cron. This is recommended if you want to bashbot run as a service. Bashbot is designed 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 recommended if you want to bashbot run as a service.
Setup the environment for the user you want to run bashbot and enter desired username, e.g. nobody : Setup the environment for the user you want to run bashbot and enter desired username, e.g. nobody :
```bash ```bash
@ -154,7 +154,7 @@ To use bashbot as a system service include a working `bashbot.rc` in your init s
An example crontab is provided in `examples/bashbot.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`. - 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` - 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`
### Use bashbot from CLI and scripts ### Use bashbot from CLI and scripts
@ -231,10 +231,10 @@ 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:
```bash ```bash
# fist Hello World # first Hello World
send_normal_message "$(getConfigKey "botadmin")" "Hello World! This is my first message" send_normal_message "$(getConfigKey "botadmin")" "Hello World! This is my first message"
# now with some markdown and HTML # now with some markdown and HTML
send_markdown_message "$(getConfigKey "botadmin")" '*Hello World!* _This is my first markdown message_' send_markdown_message "$(getConfigKey "botadmin")" '*Hello World!* _This is my first markdown message_'
send_html_message "$(getConfigKey "botadmin")" '<b>Hello World!</b> <em>This is my first HTML message</em>' send_html_message "$(getConfigKey "botadmin")" '<b>Hello World!</b> <em>This is my first HTML message</em>'
send_keyboard "$(getConfigKey "botadmin")" 'Do you like it?' '[ "Yep" , "No" ]' send_keyboard "$(getConfigKey "botadmin")" 'Do you like it?' '[ "Yep" , "No" ]'
@ -258,10 +258,10 @@ This section describe how you can customize bashbot to your needs by setting env
#### Change file locations #### Change file locations
In standard setup bashbot is self containing, this means you can place 'telegram-bot-bash' any location In standard setup bashbot is self containing, this means you can place 'telegram-bot-bash' any location
and run it from there. All files - program, 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. 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.** **Note: all specified directories and files must exist or running 'bashbot.sh' will fail.**
##### BASHBOT_ETC ##### BASHBOT_ETC
@ -379,7 +379,7 @@ BASHBOT_TIMEOUT to a numeric value between 1 and 999. Any non numeric or negativ
##### BASHBOT_SLEEP ##### BASHBOT_SLEEP
Instead of polling permanently or with a fixed delay, bashbot offers a simple adaptive polling. Instead of polling permanently or with a fixed delay, bashbot offers a simple adaptive polling.
If messages are received bashbot polls with no dealy. If no messages are available bashbot add 100ms delay If messages are received bashbot polls with no delay. If no messages are available bashbot add 100ms delay
for every poll until the maximum of BASHBOT_SLEEP ms. for every poll until the maximum of BASHBOT_SLEEP ms.
```bash ```bash
unset BASHBOT_SLEEP # 5000ms (default) unset BASHBOT_SLEEP # 5000ms (default)

58
doc/7_develop.md
View File

@ -1,7 +1,7 @@
#### [Home](../README.md) #### [Home](../README.md)
## Notes for bashbot developers ## 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, modules and addons, not on develop your individual bot. Nevertheless the information provided here should help your bot development also. This section is about help and best practices for new bashbot developers. The main focus on is creating new versions of bashbot, modules and addons, not on developing your individual bot. Nevertheless the information provided here should also help you with your bot development.
If you want to provide fixes or new features [fork bashbot on github](https://help.github.com/en/articles/fork-a-repo) and provide changes as [pull request on github](https://help.github.com/en/articles/creating-a-pull-request). If you want to provide fixes or new features [fork bashbot on github](https://help.github.com/en/articles/fork-a-repo) and provide changes as [pull request on github](https://help.github.com/en/articles/creating-a-pull-request).
@ -13,19 +13,18 @@ you can the change the level of verbosity of the debug argument:
``` ```
"debug" all output is redirected to "DEBUG.log", in addition every incoming message is logged in "MESSAGE.log" and "INLINE.log" "debug" all output is redirected to "DEBUG.log", in addition every incoming message is logged in "MESSAGE.log" and "INLINE.log"
"xdebug" same as debug plus set bash option '-x' to log any executed command in "DEBUG.log" "xdebug" same as debug plus set bash option '-x' to log any executed command in "DEBUG.log"
use the command tail to watch your bot live, e.g. "tail -f DEBUG.log", to obtain more information place set -x; set +x in your code.
``` ```
``` Use the command `tail` to watch your bot live, e.g. "tail -f DEBUG.log". To obtain more information place set -x; set +x in your code.
sometimes its useful to watch the bot live in the terminal:
Sometimes it's useful to watch the bot live in the terminal:
```
"debugx" debug output and errors are sent to terminal "debugx" debug output and errors are sent to terminal
"xdebugx" same as debugx plus set bash option '-x' to show any executed command "xdebugx" same as debugx plus set bash option '-x' to show any executed command
``` ```
Logging of telegram update poll is disabled by default, also in `debug` mode. To enable it without using verbose `xdebug` mode Logging of Telegram update poll is disabled by default, also in `debug` mode. To enable it without using verbose `xdebug` mode
set `BASHBOT_UPDATELOG` to an empty value (not unset) `export BASHBOT_UPDATELOG=""` set `BASHBOT_UPDATELOG` to an empty value (not unset) `export BASHBOT_UPDATELOG=""`
### Modules and Addons ### Modules and Addons
@ -36,7 +35,7 @@ disable modules, e.g. by rename the respective module file to 'module.sh.off'.
Modules must use only functions provided by 'bashbot.sh' or the module itself and should not depend on other modules or addons. Modules must use only functions provided by 'bashbot.sh' or the module itself and should not depend on other modules or addons.
The only mandatory module is 'module/sendMessage.sh'. The only mandatory module is 'module/sendMessage.sh'.
If a not mandatory module is used in 'bashbot.sh' or 'commands.sh', the use of `_is_function` or If an optional module is used in 'bashbot.sh' or 'commands.sh', the use of `_is_function` or
`_execute_if_function` is mandatory to catch absence of the module. `_execute_if_function` is mandatory to catch absence of the module.
**Addons** resides in `addons/*.sh.dist` and are not enabled by default. To activate an addon rename it to end with '.sh', e.g. by **Addons** resides in `addons/*.sh.dist` and are not enabled by default. To activate an addon rename it to end with '.sh', e.g. by
@ -63,18 +62,17 @@ Note: For the same reason event function MUST return immediately! Time consuming
##### SEND RECEIVE events ##### SEND RECEIVE events
An RECEIVE event is executed when a Message is received, same iQuery / Message variables are available as in commands.sh A RECEIVE event is executed when a Message is received, same iQuery / Message variables are available as in commands.sh
* `BASHBOT_EVENT_INLINE` an inline query is received * `BASHBOT_EVENT_INLINE` an inline query is received
* `BASHBOT_EVENT_MESSAGE` any of the following message types is received
* BASHBOT_EVENT_MESSAGE` any of the following message types is received * `BASHBOT_EVENT_TEXT` a message containing text is received
* `BASHBOT_EVENT_TEXT` a message containing text is received * `BASHBOT_EVENT_CMD` a message containing a command is received (starts with /)
* `BASHBOT_EVENT_CMD` a message containing a command is received (starts with /) * `BASHBOT_EVENT_REPLYTO` a reply to a message is received
* `BASHBOT_EVENT_REPLYTO` a reply to a message is received * `BASHBOT_EVENT_FORWARD` a forwarded message is received
* `BASHBOT_EVENT_FORWARD` a forwarded message is received * `BASHBOT_EVENT_CONTACT` a contact is received
* `BASHBOT_EVENT_CONTACT` a contact is received * `BASHBOT_EVENT_LOCATION` a location or a venue is received
* `BASHBOT_EVENT_LOCATION` a location or a venue is received * `BASHBOT_EVENT_FILE` a file is received
* `BASHBOT_EVENT_FILE` a file is received
*usage*: BASHBOT_EVENT_xxx[ "unique-name" ]="callback" *usage*: BASHBOT_EVENT_xxx[ "unique-name" ]="callback"
@ -182,8 +180,8 @@ You don't need all these files after you're finished with your cool new bot.
Let's create a stripped down version: Let's create a stripped down version:
- delete all modules you do not need from `modules`, e.g. `modules/inline.sh` if you don't use inline queries - delete all modules you do not need from `modules`, e.g. `modules/inline.sh` if you don't use inline queries
- delete not needed standard commands and messages from `commands.sh` - delete unused standard commands and messages from `commands.sh`
- delete not needed commands and functions from `mycommands.sh` - delete unused commands and functions from `mycommands.sh`
- run `dev/make-standalone.sh` to create a a stripped down version of your bot - run `dev/make-standalone.sh` to create a a stripped down version of your bot
Now have a look at the directory `standalone`, here you find the files `bashbot.sh` and `commands.sh` containing everything to run your bot. Now have a look at the directory `standalone`, here you find the files `bashbot.sh` and `commands.sh` containing everything to run your bot.
@ -198,8 +196,8 @@ 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 v1.xx` 5. give your (dev) fork a new version tag: `git tag v1.xx`
6. setup github hooks by running `dev/install-hooks.sh` 6. setup github hooks by running `dev/install-hooks.sh`
Run `dev/make-distrubition.sh` to create installation archives and a test installation in `DIST/`. Run `dev/make-distribution.sh` to create installation archives and a test installation in `DIST/`.
To update the test installation, e.g. after git pull, local changes or switch master/develop, run `dev/make-distrubition.sh` again. To update the test installation, e.g. after git pull, local changes or switch master/develop, run `dev/make-distribution.sh` again.
Note for Debian: Debian Buster ships older versions of many utilities, pls try to install from [buster-backports](https://backports.debian.org/Instructions/) Note for Debian: Debian Buster ships older versions of many utilities, pls try to install from [buster-backports](https://backports.debian.org/Instructions/)
```bash ```bash
@ -210,7 +208,7 @@ sudo apt-get -t buster-backports install git shellcheck pandoc codespell curl
A typical bashbot develop loop looks as follow: A typical bashbot develop loop looks as follow:
1. start developing - *change, copy, edit bashbot files ...* 1. start developing - *change, copy, edit bashbot files ...*
2. after changing a bash sript: `shellcheck -x script.sh` 2. after changing a bash script: `shellcheck -x script.sh`
3. `dev/all-tests.sh` - *in case if errors back to 2.* 3. `dev/all-tests.sh` - *in case if errors back to 2.*
4. `dev/git-add.sh` - *check for changed files, update version string, run git add* 4. `dev/git-add.sh` - *check for changed files, update version string, run git add*
5. `git commit -m "COMMIT MESSAGE"; git push` 5. `git commit -m "COMMIT MESSAGE"; git push`
@ -291,15 +289,15 @@ To update version in all files run 'dev/version.sh' without parameter.
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. 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`. To run shellcheck for a single script run `shellcheck -x script.sh`, to check all scripts run `dev/hooks/pre-commit.sh`.
### bashbot test suite ### 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. Starting with version 0.70 bashbot has a test suite. To start the test suite run `dev/all-tests.sh`. all-tests.sh will return 'SUCCESS' 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. 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
@ -328,7 +326,7 @@ The file `ALL-tests.inc.sh` must be included from all tests and provide the test
ADMINFILE="botadmin" ADMINFILE="botadmin"
DATADIR="data-bot-bash" DATADIR="data-bot-bash"
# SUCCESS NOSUCCES -> echo "${SUCCESS}" or echo "${NOSUCCESS}" # SUCCESS NOSUCCESS -> echo "${SUCCESS}" or echo "${NOSUCCESS}"
SUCCESS=" OK" SUCCESS=" OK"
NOSUCCESS=" FAILED!" NOSUCCESS=" FAILED!"
@ -358,5 +356,5 @@ fi
#### [Prev Function Reference](6_reference.md) #### [Prev Function Reference](6_reference.md)
#### $$VERSION$$ v1.21-0-gc85af77 #### $$VERSION$$ v1.21-24-g7cf624f