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

adjust doc to mycommands and new section installation

Browse Source
This commit is contained in:
Kay Marquardt (Gnadelwartz) 2019-04-24 16:53:01 +02:00
parent a3b82f72e4
commit 0cfb9f00dc
11 changed files with 142 additions and 74 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

40
README.md
View File

@ -16,25 +16,12 @@ Most complete [UTF-8 support for bashbot](doc/4_expert.md#Bashbot-UTF-8-Support)
Bashbot [Documentation](https://github.com/topkecleon/telegram-bot-bash) and [Downloads](https://github.com/topkecleon/telegram-bot-bash/releases) are availible on www.github.com
## Install bashbot
1. Go to the directory you want to install bashbot, e.g.
* your $HOME directory (install and run with your user-ID)
* /usr/local if you want to run as service
2. [Download latest release zip from github](https://github.com/topkecleon/telegram-bot-bash/releases) and extract all files.
As an alternative you can clone the github repository to get the latest improvements/fixes,
run bashbot test suite ``All-tests.sh`` afterwards to see if code looks OK.
```
git clone https://github.com/topkecleon/telegram-bot-bash; test/ALL-tests.sh
```
3. Go to directory ```telegram-bot-bash```, run ```./bashbot.sh init``` and follow the instructions. At this point you are asked for your Bots token given by botfather.
## Update bashbot
1. [Download latest update zip from github](https://github.com/topkecleon/telegram-bot-bash/releases)
2. Extract all files and copy them to your bashbot dir
3. Run ```sudo ./bashbot.sh init``` to setup your environment after the update
## Documentation
* [Install Bashbot](doc/0_install.md)
* Install release
* Install from githup
* Update Bashbot
* Notes on Updates
* [Create a new Telegram Bot with botfather](doc/1_firstbot.md)
* [Getting Started](doc/2_usage.md)
* Managing your Bot
@ -58,21 +45,6 @@ Bashbot [Documentation](https://github.com/topkecleon/telegram-bot-bash) and [Do
* [Notes for bashbot developers](doc/7_develop.md)
* [Customize bashbot environment](doc/8_customize.md)
## Note on Keyboards
From Version 0.60 on keybord format for ```send_keyboard``` and ```send_message "mykeyboardstartshere ..."``` was changed.
Keybords are now defined in JSON Array notation e.g. "[ \\"yes\\" , \\"no\\" ]".
This has the advantage that you can create any type of keyboard supported by Telegram.
The old format is supported for backward compatibility, but may fail for corner cases.
*Example Keyboards*:
- yes no in two rows:
- OLD format: 'yes' 'no' (two strings)
- NEW format: '[ "yes" ] , [ "no" ]' (two arrays with a string)
- new layouts made easy with NEW format:
- Yes No in one row: '[ "yes" , "no" ]'
- Yes No plus Maybe in 2.row: '[ "yes" , "no" ] , [ "maybe" ]'
- numpad style keyboard: '[ "1" , "2" , "3" ] , [ "4" , "5" , "6" ] , [ "7" , "8" , "9" ] , [ "0" ]'
## Security Considerations
Running a Telegram Bot means it is connected to the public and you never know whats send to your Bot.
@ -104,4 +76,4 @@ Bashbot is not more (in)secure as any other Bot written in any other language, w
If you feel that there's something missing or if you found a bug, feel free to submit a pull request!
#### $$VERSION$$ v0.70-dev2-18-g097a841
#### $$VERSION$$ v0.70-dev2-20-ga3b82f7

4
bashbot.sh
View File

@ -12,7 +12,7 @@
# This file is public domain in the USA and all free countries.
# Elsewhere, consider it to be WTFPLv2. (wtfpl.net/txt/copying)
#
#### $$VERSION$$ v0.70-dev2-18-g097a841
#### $$VERSION$$ v0.70-dev2-20-ga3b82f7
#
# Exit Codes:
# - 0 sucess (hopefully)
@ -666,7 +666,7 @@ if [ "$1" != "source" ]; then
echo "Sending the broadcast $* to $NUMCOUNT users."
[ "$NUMCOUNT" -gt "300" ] && sleep="sleep 0.5"
shift
while read -r f; do send__markdown_message "${f//COUNT}" "$*"; $sleep; done <"${COUNTFILE}"
while read -r f; do send_markdown_message "${f//COUNT}" "$*"; $sleep; done <"${COUNTFILE}"
;;
"start")
${CLEAR}

65
doc/0_install.md Normal file
View File

@ -0,0 +1,65 @@
#### [Home](../README.md)
## Install bashbot
1. Go to the directory you want to install bashbot, e.g.
* your $HOME directory (install and run with your user-ID)
* /usr/local if you want to run as service
2. [Download latest release zip from github](https://github.com/topkecleon/telegram-bot-bash/releases) and extract all files.
3. Change into the directory ```telegram-bot-bash```
4. Create default commands with ```cp commands.sh.dist commands.sh; cp mycommands.sh.dist mycommands.sh```
5. Run ```./bashbot.sh init``` to setup the environment and enter your Bots token given by botfather.
Now your Bot is ready to start ...
### Install from Github
As an alternative to donwload the zip files, you can clone the github repository to get the latest improvements/fixes.
1. Go to the directory you want to install bashbot, e.g.
* your $HOME directory (install and run with your user-ID)
* /usr/local if you want to run as service
2. Run ```git clone https://github.com/topkecleon/telegram-bot-bash;```
3. Change into the directory ```telegram-bot-bash```
4. Run ``` test/ALL-tests.sh``` and if everthing finish OK ...
5. Run ```./bashbot.sh init``` to setup the environment and enter your Bots token given by botfather.
### Update bashbot
1. Go to the directory where you had installed bashbot, e.g.
* your $HOME directory
* /usr/local
2. [Download latest release zip from github](https://github.com/topkecleon/telegram-bot-bash/releases)
3. Extract all files to you existing bashbot dir **Note** all files execpt 'mycommands.sh' and 'commands.sh' may overwritten!**
4. Run ```sudo ./bashbot.sh init``` to setup your environment after the update
### Notes on Updates
#### Location of tmp / data dir
From version 0.70 on the tmp dir is renamed to 'data-bot-bash' to refelect the fact that not only temporyry files are stored. an existing 'tmp-bot-bash' will be automatically after update renamed.
From version 0.50 on the temporary files are no more placed in '/tmp'. instead a dedicatet tmp dir is used.
#### Changes to send_keyboard in v0.6
From Version 0.60 on keybord format for ```send_keyboard``` and ```send_message "mykeyboardstartshere ..."``` was changed.
Keybords are now defined in JSON Array notation e.g. "[ \\"yes\\" , \\"no\\" ]".
This has the advantage that you can create any type of keyboard supported by Telegram.
The old format is supported for backward compatibility, but may fail for corner cases.
*Example Keyboards*:
- yes no in two rows:
- OLD format: 'yes' 'no' (two strings)
- NEW format: '[ "yes" ] , [ "no" ]' (two arrays with a string)
- new layouts made easy with NEW format:
- Yes No in one row: '[ "yes" , "no" ]'
- Yes No plus Maybe in 2.row: '[ "yes" , "no" ] , [ "maybe" ]'
- numpad style keyboard: '[ "1" , "2" , "3" ] , [ "4" , "5" , "6" ] , [ "7" , "8" , "9" ] , [ "0" ]'
#### [Next Create Bot](1_firstbot.md)
#### $$VERSION$$ v0.70-dev2-20-ga3b82f7

3
doc/1_firstbot.md
View File

@ -59,7 +59,8 @@ group. This step is up to you actually.
13. @botfather replies with `Success! The new status is: DISABLED. /help`
#### [Prev Installation](0_install.md)
#### [Next Getting started](2_usage.md)
#### $$VERSION$$ v0.70-dev2-18-g097a841
#### $$VERSION$$ v0.70-dev2-20-ga3b82f7

6
doc/2_usage.md
View File

@ -1,9 +1,9 @@
#### [Home](../README.md)
## Gettting Started
All Commands for the Bot are in the ```commands.sh``` file (this should ease upgrades of the bot core). Here you find some examples how to process messages and send out text.
THe Bots standard commands are in the ```commands.sh``` file. Vou must not add your commands to 'commands.sh' instead place them in ```mycommands.sh```, there you also find examples how to process messages and send out text.
Once you're done editing start the Bot with ```./bashbot.sh start```.
Once you're done with editing 'mycommands.sh' start the Bot with ```./bashbot.sh start```.
If some thing doesn't work as it should, debug with ```bash -x bashbot.sh```. To stop the Bot run ```./bashbot.sh kill```
To use the functions provided in this script in other scripts simply source bashbot: ```source bashbot.sh```
@ -166,5 +166,5 @@ send_action "${CHAT[ID]}" "action"
#### [Prev Create Bot](1_firstbot.md)
#### [Next Advanced Usage](3_advanced.md)
#### $$VERSION$$ v0.70-dev2-18-g097a841
#### $$VERSION$$ v0.70-dev2-20-ga3b82f7

2
doc/3_advanced.md
View File

@ -156,5 +156,5 @@ answer_inline_query "$iQUERY_ID" "cached_sticker" "identifier for the sticker"
#### [Prev Advanced Usage](3_advanced.md)
#### [Next Expert Use](4_expert.md)
#### $$VERSION$$ v0.70-dev2-18-g097a841
#### $$VERSION$$ v0.70-dev2-20-ga3b82f7

2
doc/4_expert.md
View File

@ -104,5 +104,5 @@ An example crontab is provided in ```examples/bashbot.cron```.
#### [Prev Expert Use](4_expert.md)
#### [Next Best Practice](5_practice.md)
#### $$VERSION$$ v0.70-dev2-18-g097a841
#### $$VERSION$$ v0.70-dev2-20-ga3b82f7

88
doc/5_practice.md
View File

@ -1,49 +1,81 @@
#### [Home](../README.md)
## Best Practices
### Customize commands.sh only
To ease Updates never change ```bashbot.sh```, instead individual commands should go to ```commands.sh``` . Insert your Bot commands in the ```case ... esac``` block:
### Add commands to mycommands.sh only
To ease Updates never change ```bashbot.sh```, instead your commands and functions must go to ```mycommands.sh``` . Insert your Bot commands in the ```case ... esac``` block of the 'mycommands()' function:
```bash
case "$MESSAGE" in
'/echo') # my first own command, echo MESSAGE
send_normal_message "${CHAT[ID]}" "${MESSAGE}"
;;
# file: mycommands.sh
# your additional bahsbot commands
# uncomment the following lines to overwrite info and help messages
bashbot_info='This is *MY* variant of _bashbot_, the Telegram bot written entirely in bash.
'
bashbot_help='*Available commands*:
/echo message - _echo the given messsage_
'
mycommands() {
case "$MESSAGE" in
'/echo'*) # example echo command
send_normal_message "${CHAT[ID]}" "$MESSAGE"
;;
# .....
esac
}
```
### Reuse or disable standard commands
If you want to disable or reuse a standard bashbot command comment it out in 'commands.sh' by placing a '#' in front of
every line from ```'/command')``` to ```;;```.
**Note: Never disable the catchall command ``*)```` in 'commands.sh'!!**
```bash
#!/bin/bash
# file: commands.sh
case "$MESSAGE" in
################################################
# DEFAULT commands start here, do not edit below this!
'/info')
bashbot_info "${CHAT[ID]}"
# DEFAULT commands start here, edit messages only
#'/start')
# send_action "${CHAT[ID]}" "typing"
# _is_botadmin && _markdown_message "You are *BOTADMIN*."
# if _is_allowed "start" ; then
# _markdown_message "${bot_help}"
# else
# _message "You are not allowed to start Bot."
# fi
# ;;
*) # forward other messages to optional dispatcher
_is_function startproc && if tmux ls | grep -v send | grep -q "$copname"; then inproc; fi # interactive running
_is_function mycommands && mycommands
;;
esac
```
### Seperate logic from commands
If a command need more than 2-3 lines of code, you should use a function to seperate logic from command. Place your functions in a seperate file, e.g. ```mycommands.inc.sh``` and source it from bashbot.sh. Example:
If a command need more than 2-3 lines of code, you should use a function to seperate logic from command. Place your functions in ```mycommands.sh``` and call the from you commands. Example:
```bash
source "mycommands.inc.sh"
#!/bin/bash
# file: mycommands.sh
mycommands() {
case "$MESSAGE" in
'/process') # logic for /process is done in process_message
result="$(process_message "$MESSAGE")"
send_normal_message "${CHAT[ID]}" "$result"
;;
################################################
# DEFAULT commands start here, do not edit below this!
'/info')
bashbot_info "${CHAT[ID]}"
;;
'/start')
send_action "${CHAT[ID]}" "typing"
bashbot_help "${CHAT[ID]}"
;;
esac
```
```bash
#!/bin/bash
# file: mycommands.inc.sh
}
# place your functions here
process_message() {
local ARGS="${1#/* }" # remove command
@ -53,7 +85,6 @@ process_message() {
set -f
for WORD in $ARGS
do
set +f
# process links
if [[ "$WORD" == "https://"* ]]; then
REPORT="$(dosomething_with_link "$WORD")"
@ -68,7 +99,6 @@ process_message() {
done
# return result, reset globbing in case we had no ARGS
set +f
echo "${OUTPUT}${TEXT}"
}
@ -112,5 +142,5 @@ The second warning is about an unused variable, this is true because in our exam
#### [Prev Best Practice](5_practice.md)
#### [Next Functions Reference](6_reference.md)
#### $$VERSION$$ v0.70-dev2-18-g097a841
#### $$VERSION$$ v0.70-dev2-20-ga3b82f7

2
doc/6_reference.md
View File

@ -445,5 +445,5 @@ Send Input from Telegram to waiting Interactive Chat.
#### [Prev Best Practice](5_practice.md)
#### [Next Notes for Developers](7_develop.md)
#### $$VERSION$$ v0.70-dev2-18-g097a841
#### $$VERSION$$ v0.70-dev2-20-ga3b82f7

2
doc/7_develop.md
View File

@ -71,5 +71,5 @@ fi
#### [Prev Function Reference](6_function.md)
#### [Next Bashbot Environment](8_custom.md)
#### $$VERSION$$ v0.70-dev2-18-g097a841
#### $$VERSION$$ v0.70-dev2-20-ga3b82f7

2
doc/8_custom.md
View File

@ -131,5 +131,5 @@ for every poll until the maximum of BASHBOT_SLEEP ms.
#### [Prev Notes for Developers](7_develop.md)
#### $$VERSION$$ v0.70-dev2-18-g097a841
#### $$VERSION$$ v0.70-dev2-20-ga3b82f7