mirror of
https://github.com/octoleo/telegram-bot-bash.git
synced 2024-11-25 00:37:34 +00:00
Kay Marquardt
GitHub
commit
8be95a3abf
@ -158,9 +158,10 @@ start debug`
|
||||
│ ├── BASHBOT.log # log what your bot is doing ...
|
||||
│ ├── ERROR.log # connection errors from / to Telegram API
|
||||
│ │
|
||||
│ ├── DEBUG.log # stdout/stderr of you bot (debug mode enabled)
|
||||
│ └── MESSAGE.log # full text of all message send/received (debug mode
|
||||
│ ├── DEBUG.log # stdout/stderr of you bot (debug mode
|
||||
enabled)
|
||||
│ └── MESSAGE.log # full text of all message send/received
|
||||
(debug mode enabled)
|
||||
```
|
||||
|
||||
----
|
||||
|
||||
@ -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.
|
||||
|
||||
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
|
||||
|
||||
@ -171,7 +171,7 @@ All output of the script will be sent to the user, to stop a background job use:
|
||||
```bash
|
||||
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
|
||||
./bashbot.sh suspendback
|
||||
./bashbot.sh resumeback
|
||||
|
||||
@ -50,12 +50,12 @@ If you don't know what locales are installed on your sytsem use `locale -a` to d
|
||||
##### Character classes
|
||||
|
||||
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,
|
||||
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
|
||||
# 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'`
|
||||
|
||||
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
|
||||
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 :
|
||||
```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`.
|
||||
|
||||
- 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
|
||||
@ -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:
|
||||
```bash
|
||||
# fist Hello World
|
||||
# first Hello World
|
||||
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_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" ]'
|
||||
@ -258,10 +258,10 @@ This section describe how you can customize bashbot to your needs by setting env
|
||||
|
||||
|
||||
#### Change file locations
|
||||
In standard setup bashbot is self containing, this means you can place 'telegram-bot-bash' any location
|
||||
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'.
|
||||
|
||||
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.**
|
||||
|
||||
##### BASHBOT_ETC
|
||||
@ -379,7 +379,7 @@ BASHBOT_TIMEOUT to a numeric value between 1 and 999. Any non numeric or negativ
|
||||
|
||||
##### BASHBOT_SLEEP
|
||||
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.
|
||||
```bash
|
||||
unset BASHBOT_SLEEP # 5000ms (default)
|
||||
|
||||
@ -1,7 +1,7 @@
|
||||
#### [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, 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).
|
||||
|
||||
@ -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"
|
||||
"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.
|
||||
```
|
||||
|
||||
```
|
||||
sometimes its useful to watch the bot live in the terminal:
|
||||
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 it's useful to watch the bot live in the 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=""`
|
||||
|
||||
### 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.
|
||||
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.
|
||||
|
||||
**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
|
||||
|
||||
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_MESSAGE` any of the following message types 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_REPLYTO` a reply to a message is received
|
||||
* `BASHBOT_EVENT_FORWARD` a forwarded message is received
|
||||
* `BASHBOT_EVENT_CONTACT` a contact is received
|
||||
* `BASHBOT_EVENT_LOCATION` a location or a venue is received
|
||||
* `BASHBOT_EVENT_FILE` a file is received
|
||||
* `BASHBOT_EVENT_INLINE` an inline query is received
|
||||
* `BASHBOT_EVENT_MESSAGE` any of the following message types 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_REPLYTO` a reply to a message is received
|
||||
* `BASHBOT_EVENT_FORWARD` a forwarded message is received
|
||||
* `BASHBOT_EVENT_CONTACT` a contact is received
|
||||
* `BASHBOT_EVENT_LOCATION` a location or a venue is received
|
||||
* `BASHBOT_EVENT_FILE` a file is received
|
||||
|
||||
*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:
|
||||
|
||||
- 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 not needed commands and functions from `mycommands.sh`
|
||||
- delete unused standard commands and messages from `commands.sh`
|
||||
- delete unused commands and functions from `mycommands.sh`
|
||||
- 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.
|
||||
@ -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`
|
||||
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/`.
|
||||
To update the test installation, e.g. after git pull, local changes or switch master/develop, run `dev/make-distrubition.sh` again.
|
||||
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-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/)
|
||||
```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:
|
||||
|
||||
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.*
|
||||
4. `dev/git-add.sh` - *check for changed files, update version string, run git add*
|
||||
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.
|
||||
|
||||
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
|
||||
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
|
||||
|
||||
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
|
||||
@ -328,7 +326,7 @@ The file `ALL-tests.inc.sh` must be included from all tests and provide the test
|
||||
ADMINFILE="botadmin"
|
||||
DATADIR="data-bot-bash"
|
||||
|
||||
# SUCCESS NOSUCCES -> echo "${SUCCESS}" or echo "${NOSUCCESS}"
|
||||
# SUCCESS NOSUCCESS -> echo "${SUCCESS}" or echo "${NOSUCCESS}"
|
||||
SUCCESS=" OK"
|
||||
NOSUCCESS=" FAILED!"
|
||||
|
||||
@ -358,5 +356,5 @@ fi
|
||||
|
||||
#### [Prev Function Reference](6_reference.md)
|
||||
|
||||
#### $$VERSION$$ v1.21-0-gc85af77
|
||||
#### $$VERSION$$ v1.21-24-g7cf624f
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user