From 0cfb9f00dc920ac9af9b4995e44d991953aad05c Mon Sep 17 00:00:00 2001 From: "Kay Marquardt (Gnadelwartz)" Date: Wed, 24 Apr 2019 16:53:01 +0200 Subject: [PATCH] adjust doc to mycommands and new section installation --- README.md | 40 ++++----------------- bashbot.sh | 4 +-- doc/0_install.md | 65 ++++++++++++++++++++++++++++++++++ doc/1_firstbot.md | 3 +- doc/2_usage.md | 6 ++-- doc/3_advanced.md | 2 +- doc/4_expert.md | 2 +- doc/5_practice.md | 88 +++++++++++++++++++++++++++++++--------------- doc/6_reference.md | 2 +- doc/7_develop.md | 2 +- doc/8_custom.md | 2 +- 11 files changed, 142 insertions(+), 74 deletions(-) create mode 100644 doc/0_install.md diff --git a/README.md b/README.md index 4516cde..17aa6a8 100644 --- a/README.md +++ b/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 diff --git a/bashbot.sh b/bashbot.sh index a920afc..0768f98 100755 --- a/bashbot.sh +++ b/bashbot.sh @@ -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} diff --git a/doc/0_install.md b/doc/0_install.md new file mode 100644 index 0000000..b4ac65b --- /dev/null +++ b/doc/0_install.md @@ -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 + diff --git a/doc/1_firstbot.md b/doc/1_firstbot.md index db768e7..6bb2fa3 100644 --- a/doc/1_firstbot.md +++ b/doc/1_firstbot.md @@ -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 diff --git a/doc/2_usage.md b/doc/2_usage.md index 8e812f9..690ba18 100644 --- a/doc/2_usage.md +++ b/doc/2_usage.md @@ -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 diff --git a/doc/3_advanced.md b/doc/3_advanced.md index dabf50a..6978135 100644 --- a/doc/3_advanced.md +++ b/doc/3_advanced.md @@ -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 diff --git a/doc/4_expert.md b/doc/4_expert.md index c24617d..0c962df 100644 --- a/doc/4_expert.md +++ b/doc/4_expert.md @@ -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 diff --git a/doc/5_practice.md b/doc/5_practice.md index 0769e7b..cf65014 100644 --- a/doc/5_practice.md +++ b/doc/5_practice.md @@ -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 diff --git a/doc/6_reference.md b/doc/6_reference.md index b37ee53..b684625 100644 --- a/doc/6_reference.md +++ b/doc/6_reference.md @@ -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 diff --git a/doc/7_develop.md b/doc/7_develop.md index 442d6ed..d57e30d 100644 --- a/doc/7_develop.md +++ b/doc/7_develop.md @@ -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 diff --git a/doc/8_custom.md b/doc/8_custom.md index 2457cd8..b725cc8 100644 --- a/doc/8_custom.md +++ b/doc/8_custom.md @@ -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