From 4aa7561f7c8ce4c68776d9b29628911de234e0dc Mon Sep 17 00:00:00 2001 From: "Kay Marquardt (Gnadelwartz)" Date: Thu, 14 May 2020 15:47:04 +0200 Subject: [PATCH] update doc, prepare for release --- README.html | 2 +- README.md | 2 +- README.txt | 2 +- bashbot.rc | 2 +- bashbot.sh | 2 +- commands.sh | 2 +- doc/0_install.md | 2 +- doc/1_firstbot.md | 2 +- doc/2_usage.md | 37 +++++++++++++++++++++++++++---------- doc/3_advanced.md | 2 +- doc/4_expert.md | 2 +- doc/5_practice.md | 2 +- doc/6_reference.md | 20 ++++---------------- doc/7_develop.md | 19 +++++++++++++------ mycommands.sh | 2 +- mycommands.sh.clean | 2 +- re* | 0 17 files changed, 57 insertions(+), 45 deletions(-) create mode 100644 re* diff --git a/README.html b/README.html index 3bf0ee2..deae2ec 100644 --- a/README.html +++ b/README.html @@ -223,6 +223,6 @@ It features background tasks and interactive chats, and can serve as an interfac

@Gnadelwartz

That's it!

If you feel that there's something missing or if you found a bug, feel free to submit a pull request!

-

$$VERSION$$ v0.94-dev3-0-geef955a

+

$$VERSION$$ v0.94-pre-0-gac2ec02

diff --git a/README.md b/README.md index b457ee2..8125661 100644 --- a/README.md +++ b/README.md @@ -180,4 +180,4 @@ This may happen if to many wrong requests are sent to api.telegram.org, e.g. usi If you feel that there's something missing or if you found a bug, feel free to submit a pull request! -#### $$VERSION$$ v0.94-dev3-0-geef955a +#### $$VERSION$$ v0.94-pre-0-gac2ec02 diff --git a/README.txt b/README.txt index e1375d2..e6e3e74 100644 --- a/README.txt +++ b/README.txt @@ -253,4 +253,4 @@ tor proxy on your server you may uncomment the ```BASHBOT_CURL_ARGS``` line in If you feel that there's something missing or if you found a bug, feel free to submit a pull request! -#### $$VERSION$$ v0.94-dev3-0-geef955a +#### $$VERSION$$ v0.94-pre-0-gac2ec02 diff --git a/bashbot.rc b/bashbot.rc index b4d8d83..bb97ef9 100755 --- a/bashbot.rc +++ b/bashbot.rc @@ -1,7 +1,7 @@ #!/bin/sh # description: Start or stop telegram-bash-bot # -#### $$VERSION$$ v0.94-dev3-0-geef955a +#### $$VERSION$$ v0.94-pre-0-gac2ec02 # shellcheck disable=SC2009 # shellcheck disable=SC2181 diff --git a/bashbot.sh b/bashbot.sh index 568f377..28edf03 100755 --- a/bashbot.sh +++ b/bashbot.sh @@ -11,7 +11,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.94-dev3-3-ga5975d9 +#### $$VERSION$$ v0.94-pre-0-gac2ec02 # # Exit Codes: # - 0 sucess (hopefully) diff --git a/commands.sh b/commands.sh index 63a3f07..d139b5e 100644 --- a/commands.sh +++ b/commands.sh @@ -15,7 +15,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.94-dev3-2-gbf8a911 +#### $$VERSION$$ v0.94-pre-0-gac2ec02 # # adjust your language setting here, e.g.when run from other user or cron. diff --git a/doc/0_install.md b/doc/0_install.md index 1e86154..e105298 100644 --- a/doc/0_install.md +++ b/doc/0_install.md @@ -87,5 +87,5 @@ The old format is supported for backward compatibility, but may fail for corner #### [Next Create Bot](1_firstbot.md) -#### $$VERSION$$ v0.94-dev3-0-geef955a +#### $$VERSION$$ v0.94-pre-0-gac2ec02 diff --git a/doc/1_firstbot.md b/doc/1_firstbot.md index bd325b4..f407229 100644 --- a/doc/1_firstbot.md +++ b/doc/1_firstbot.md @@ -65,5 +65,5 @@ group. This step is up to you actually. #### [Prev Installation](0_install.md) #### [Next Getting started](2_usage.md) -#### $$VERSION$$ v0.94-dev3-0-geef955a +#### $$VERSION$$ v0.94-pre-0-gac2ec02 diff --git a/doc/2_usage.md b/doc/2_usage.md index 1e362b5..267a78b 100644 --- a/doc/2_usage.md +++ b/doc/2_usage.md @@ -17,9 +17,13 @@ Have FUN! ### Files ``` . -├── bashbot.sh # main bashbot script - do not edit -├── commands.sh # command dispatcher - do not edit -├── mycommands.sh # place your functions and commands here! +├── mycommands.sh # THIS is your bot, place logic and commands here! +│ +├── mycommands.sh.clean # copy to "mycommands.sh" if you start devloping your bot +├── mycommands.sh.dist # example bot, also used for testing bashbot internally +│ +├── bashbot.sh # main bashbot script - DO NOT EDIT! +├── commands.sh # command dispatcher - DO NOT EDIT! ├── JSON.sh # bashbots JSON parser, see https://github.com/dominictarr/JSON.sh │ ├── modules # optional functions, sourced by commands.sh @@ -65,16 +69,13 @@ Start or Stop your Bot use the following commands: ``` ### User count -To count the total number of users that ever used the bot run the following command: -```bash -./bashbot.sh count + +deprecated, will be removed! ``` ### Sending broadcasts to all users -To send a broadcast to all of users that ever used the bot run the following command: -```bash -./bashbot.sh broadcast "Hey! I just wanted to let you know that the bot's been updated!" ``` +deprecated, will be removed! ---- @@ -134,6 +135,22 @@ Evertime a Message is recieved, you can read incoming data using the following v * ```${VENUE[LONGITUDE]}```: Longitude * ```${VENUE[LATITUDE]}```: Latitude * ```${VENUE[FOURSQUARE]}```: Fouresquare ID +* ```$SERVICE```: This array contains info abbout recived service messages. + * ```${SERVICE}```: set to "yes" when a service message is recived. + * ```${SERVICE[NEWMEMBER]```: New user's id + * ```${NEWMEMBER[ID]```: New user's id + * ```${NEWMEMBER[FIRSTNAME]```: New user's first name + * ```${NEWMEMBER[LASTNAME]```: New user's last name + * ```${NEWMEMBER[USERNAME]```: New user's username + * ```${NEWMEMBER[ISBOT]```: New user is a bot + * ```${SERVICE[LEFTMEMBER]```: Id of user left + * ```${SERVICE[NEWTILE]```: Text of new title + * ```${SERVICE[NEWPHOTO]```: New Chat Picture array + * ```${SERVICE[PINNED]```: Pinned Message structure + + + + ### Inline queries Evertime a Message is recieved, you can read incoming data using the following variables: @@ -223,5 +240,5 @@ send_action "${CHAT[ID]}" "action" #### [Prev Create Bot](1_firstbot.md) #### [Next Advanced Usage](3_advanced.md) -#### $$VERSION$$ v0.94-dev3-0-geef955a +#### $$VERSION$$ v0.94-pre-0-gac2ec02 diff --git a/doc/3_advanced.md b/doc/3_advanced.md index 522efa8..8fbb841 100644 --- a/doc/3_advanced.md +++ b/doc/3_advanced.md @@ -180,5 +180,5 @@ See also [answer_inline_multi, answer_inline_compose](6_reference.md#answer_inli #### [Prev Getting started](2_usage.md) #### [Next Expert Use](4_expert.md) -#### $$VERSION$$ v0.94-dev3-0-geef955a +#### $$VERSION$$ v0.94-pre-0-gac2ec02 diff --git a/doc/4_expert.md b/doc/4_expert.md index 4eccf63..db099f1 100644 --- a/doc/4_expert.md +++ b/doc/4_expert.md @@ -348,5 +348,5 @@ for every poll until the maximum of BASHBOT_SLEEP ms. #### [Prev Advanced Use](3_advanced.md) #### [Next Best Practice](5_practice.md) -#### $$VERSION$$ v0.94-dev3-0-geef955a +#### $$VERSION$$ v0.94-pre-0-gac2ec02 diff --git a/doc/5_practice.md b/doc/5_practice.md index 0f93e06..4355995 100644 --- a/doc/5_practice.md +++ b/doc/5_practice.md @@ -152,5 +152,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.94-dev3-0-geef955a +#### $$VERSION$$ v0.94-pre-0-gac2ec02 diff --git a/doc/6_reference.md b/doc/6_reference.md index d76483d..f1d3e99 100644 --- a/doc/6_reference.md +++ b/doc/6_reference.md @@ -506,19 +506,6 @@ Something wrong with /home/someuser/myfile Something wrong with data-bot-bash/../../../somevalues ``` -##### jssh_readDB -Read content of a .jssh file in JSON.sh format into given ARRAY. ARRAY name must be delared with "declare -A ARRAY" before calling readDB. - -*usage:* jssh_readDB "ARRAY" "filename" - -*example:* -```bash -# read file data-bot-bash/somevalues.jssh into array SOMEVALUES -jssh_readDB "SOMEVALUES" "${DATADIR:-.}/somevalues" - -print "${SOMEVALUES[*]}" -``` - ##### jssh_writeDB Write content of an ARRAY into jsshDB file. ARRAY name must be delared with "declare -A ARRAY" before calling writeDB. "DB" file MUST exist or nothing is written. @@ -610,8 +597,6 @@ echo "$result" this is new ``` ----- - ##### jssh_readDB Read content of a file in JSON.sh format into given ARRAY. ARRAY name must be delared with "declare -A ARRAY" upfront, @@ -662,10 +647,13 @@ whynot,subindex3=new subindex value whynot,subindex2=whynot B whynot,subindex1=whynot A ``` + https://linuxhint.com/associative_array_bash/ https://linuxconfig.org/how-to-use-arrays-in-bash-script +---- + ### Aliases - shortcuts for often used funtions Aliases are handy shortcuts for using in 'mycommands.sh', they avoid error prone typing of "${CHAT[ID]}" "${USER[ID]}" as much as possible. Do not use them in bashbot.sh, modules and addons. @@ -947,5 +935,5 @@ The name of your bot is availible as bash variable "$ME", there is no need to ca #### [Prev Best Practice](5_practice.md) #### [Next Notes for Developers](7_develop.md) -#### $$VERSION$$ v0.94-dev3-0-geef955a +#### $$VERSION$$ v0.94-pre-0-gac2ec02 diff --git a/doc/7_develop.md b/doc/7_develop.md index d6b151c..283c0fc 100644 --- a/doc/7_develop.md +++ b/doc/7_develop.md @@ -7,17 +7,24 @@ If you want to provide fixes or new features [fork bashbot on githup](https://he ### Debugging Bashbot Usually all bashbot output is discarded. -If you want to get error messages (and more) start bashbot in the current shell with ```./bashbot.sh startbot```. -In addition you can the change the level of verbosity by adding a 'debug' as third argument. +If you want to get error messages (and more) start bashbot ```./bashbot.sh startbot debug```. +you can the change the level of verbosity of the debug argument: + ``` + "debug" all output is redirected to "DEBUG.log", in addtion every incomming 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: + "debugx" debug output and errors are sent to terminal "xdebugx" same as debugx plus set bash option '-x' to show any executed command - "debug" all output is redirected to "DEBUG.log", in addtion every incomming 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" ``` -To stop bashhbot in debugging mode press CRTL+C. If this does not stop bashbot or you run it in background execute ```ps -uf | grep debug``` and kill all shown processes. ### Modules and Addons **Modules** resides in ```modules/*.sh``` and are colletions of optional bashbot functions grouped by functionality. Main reason for creating modules was @@ -321,5 +328,5 @@ fi #### [Prev Function Reference](6_reference.md) -#### $$VERSION$$ v0.94-dev3-0-geef955a +#### $$VERSION$$ v0.94-pre-0-gac2ec02 diff --git a/mycommands.sh b/mycommands.sh index 8ec4272..40953d0 100644 --- a/mycommands.sh +++ b/mycommands.sh @@ -8,7 +8,7 @@ # #### if you start to develop your own bot, use the clean version of this file: # #### mycommands.clean # -#### $$VERSION$$ v0.94-dev3-3-ga5975d9 +#### $$VERSION$$ v0.94-pre-0-gac2ec02 # # uncomment the following lines to overwrite info and help messages diff --git a/mycommands.sh.clean b/mycommands.sh.clean index 5533bf0..49cf6b7 100644 --- a/mycommands.sh.clean +++ b/mycommands.sh.clean @@ -4,7 +4,7 @@ # files: mycommands.sh.clean # copy to mycommands.sh and add all your commands and functions here ... # -#### $$VERSION$$ v0.94-dev3-3-ga5975d9 +#### $$VERSION$$ v0.94-pre-0-gac2ec02 # ########## diff --git a/re* b/re* new file mode 100644 index 0000000..e69de29