adjust doc to mycommands and new section installation
This commit is contained in:
Kay Marquardt (Gnadelwartz)
parent
a3b82f72e4
commit
0cfb9f00dc
40
README.md
40
README.md
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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}
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue