diff --git a/addons/antiFlood.sh b/addons/antiFlood.sh index e4a8a3f..87224b9 100644 --- a/addons/antiFlood.sh +++ b/addons/antiFlood.sh @@ -4,12 +4,12 @@ # this addon counts how many files, e.g. stickers, are sent to # a chat and takes actions if threshold is reached # -#### $$VERSION$$ v0.96-dev-7-g0153928 +#### $$VERSION$$ v0.96-pre-36-g81c8771 # used events: # # BASHBOT_EVENT_TEXT message containing message text received -# BASHBOT_EVENT_CMD a command is recieved +# BASHBOT_EVENT_CMD a command is received # BASHBOT_EVENT_FILE file received # # all global variables and functions can be used in registered functions. diff --git a/addons/example.sh b/addons/example.sh index bb08160..ee22ca2 100644 --- a/addons/example.sh +++ b/addons/example.sh @@ -4,7 +4,7 @@ # Addons can register to bashbot events at statup # by providing their name and a callback per event # -#### $$VERSION$$ v0.96-dev-7-g0153928 +#### $$VERSION$$ v0.96-pre-36-g81c8771 # # If an event occours each registered event function is called. # @@ -22,7 +22,7 @@ # BASHBOT_EVENT_INLINE inline query received # BASHBOT_EVENT_MESSAGE any type of message received # BASHBOT_EVENT_TEXT message containing message text received -# BASHBOT_EVENT_CMD a command is recieved +# BASHBOT_EVENT_CMD a command is received # BASHBOT_EVENT_REPLYTO reply to message received # BASHBOT_EVENT_FORWARD forwarded message received # BASHBOT_EVENT_CONTACT contact received diff --git a/bashbot.sh b/bashbot.sh index 9301f0a..aa799c0 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.96-pre-35-g2bc8f39 +#### $$VERSION$$ v0.96-pre-36-g81c8771 # # Exit Codes: # - 0 sucess (hopefully) @@ -669,7 +669,7 @@ process_message() { MESSAGE[0]="$(JsonDecode "${UPD["result",${num},"message","text"]}" | sed 's#\\/#/#g')" MESSAGE[ID]="${UPD["result",${num},"message","message_id"]}" - # Chat ID is now parsed when update isrecieved + # Chat ID is now parsed when update isreceived #CHAT[ID]="${UPD["result",${num},"message","chat","id"]}" CHAT[LAST_NAME]="$(JsonDecode "${UPD["result",${num},"message","chat","last_name"]}")" CHAT[FIRST_NAME]="$(JsonDecode "${UPD["result",${num},"message","chat","first_name"]}")" @@ -679,7 +679,7 @@ process_message() { CHAT[ALL_ADMIN]="${UPD["result",${num},"message","chat","all_members_are_administrators"]}" CHAT[ALL_MEMBERS_ARE_ADMINISTRATORS]="${CHAT[ALL_ADMIN]}" # backward compatibility - # user ID is now parsed when update isrecieved + # user ID is now parsed when update isreceived #USER[ID]="${UPD["result",${num},"message","from","id"]}" USER[FIRST_NAME]="$(JsonDecode "${UPD["result",${num},"message","from","first_name"]}")" USER[LAST_NAME]="$(JsonDecode "${UPD["result",${num},"message","from","last_name"]}")" @@ -760,7 +760,7 @@ process_message() { SERVICE[NEWTILE]="${UPD["result",${num},"message","new_chat_title"]}" SERVICE[NEWPHOTO]="${UPD["result",${num},"message","new_chat_photo"]}" SERVICE[PINNED]="${UPD["result",${num},"message","pinned_message"]}" - # set SSERVICE to yes if a service message was recieved + # set SSERVICE to yes if a service message was received [[ "${SERVICE[*]}" =~ ^[[:blank:]]+$ ]] || SERVICE[0]="yes" diff --git a/commands.sh b/commands.sh index ca23cdc..f39cfeb 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.96-pre-35-g2bc8f39 +#### $$VERSION$$ v0.96-pre-36-g81c8771 # # adjust your language setting here, e.g.when run from other user or cron. @@ -32,7 +32,7 @@ unset IFS # copy "mycommands.sh.dist" to "mycommnds.sh" and change the strings there bashbot_info='This is bashbot, the Telegram bot written entirely in bash. It features background tasks and interactive chats, and can serve as an interface for CLI programs. -It currently can send, recieve and forward messages, custom keyboards, photos, audio, voice, documents, locations and video files. +It currently can send, receive and forward messages, custom keyboards, photos, audio, voice, documents, locations and video files. ' # diff --git a/doc/2_usage.md b/doc/2_usage.md index f3df000..ba5f7e8 100644 --- a/doc/2_usage.md +++ b/doc/2_usage.md @@ -96,7 +96,7 @@ To send a broadcast to all of users that ever used the bot run the following com ---- ## Recieve data -Evertime a Message is recieved, you can read incoming data using the following variables: +Evertime a Message is received, you can read incoming data using the following variables: ### Regular Messages @@ -169,7 +169,7 @@ Evertime a Message is recieved, you can read incoming data using the following v ### Inline queries -Evertime a Message is recieved, you can read incoming data using the following variables: +Evertime a Message is received, you can read incoming data using the following variables: * ```${iQUERY}```: Current inline query * ```$iQUERY```: This array contains the ID, First name, last name, username and user id of the sender of the current inline query. @@ -256,5 +256,5 @@ send_action "${CHAT[ID]}" "action" #### [Prev Create Bot](1_firstbot.md) #### [Next Advanced Usage](3_advanced.md) -#### $$VERSION$$ v0.96-dev3-14-g5fc4d01a +#### $$VERSION$$ v0.96-pre-36-g81c8771 diff --git a/doc/4_expert.md b/doc/4_expert.md index db7e8a7..7428719 100644 --- a/doc/4_expert.md +++ b/doc/4_expert.md @@ -40,7 +40,7 @@ To display all availible locales on your system run ```locale -a | more```. [Gen #### Bashbot UTF-8 Support Bashbot handles all messages transparently, regardless of the charset in use. The only exception is when converting from JSON data to strings. -Telegram use JSON to send / recieve data. JSON encodes strings as follow: Characters not ASCII *(>127)* are escaped as sequences of ```\uxxxx``` to be regular ASCII. In addition multibyte characters, *e.g. Emoticons or Arabic characters*, are send in double byte UTF-16 notation. +Telegram use JSON to send / receive data. JSON encodes strings as follow: Characters not ASCII *(>127)* are escaped as sequences of ```\uxxxx``` to be regular ASCII. In addition multibyte characters, *e.g. Emoticons or Arabic characters*, are send in double byte UTF-16 notation. The Emoticons ``` 😁 😘 ❤️ 😊 👍 ``` are encoded as: ``` \uD83D\uDE01 \uD83D\uDE18 \u2764\uFE0F \uD83D\uDE0A \uD83D\uDC4D ``` **This "mixed" JSON encoding needs special handling and can not decoded from** ```echo -e``` or ```printf '%s\\n'``` @@ -326,7 +326,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 recieved bashbot polls with no dealy. If no messages are availible bashbot add 100ms delay +If messages are received bashbot polls with no dealy. If no messages are availible bashbot add 100ms delay for every poll until the maximum of BASHBOT_SLEEP ms. ```bash unset BASHBOT_SLEEP # 5000ms (default) @@ -382,5 +382,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.96-dev3-17-g720dc59 +#### $$VERSION$$ v0.96-pre-36-g81c8771 diff --git a/doc/6_reference.md b/doc/6_reference.md index bb4338a..10da99d 100644 --- a/doc/6_reference.md +++ b/doc/6_reference.md @@ -404,7 +404,7 @@ fi ##### start_back Starts a script as a background job and attaches a jobname to it. All output from a background job is sent to the associated chat. -In contrast to interactive chats, background jobs do not recieve user input and can run forever. In addition you can suspend and restart running jobs, e.g. after reboot. +In contrast to interactive chats, background jobs do not receive user input and can run forever. In addition you can suspend and restart running jobs, e.g. after reboot. *usage:* start_back "${CHAT[ID]}" "script" "jobname" @@ -1035,5 +1035,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.96-dev3-5-g407e147 +#### $$VERSION$$ v0.96-pre-36-g81c8771 diff --git a/doc/7_develop.md b/doc/7_develop.md index f8e5751..68de0f3 100644 --- a/doc/7_develop.md +++ b/doc/7_develop.md @@ -31,7 +31,7 @@ you can the change the level of verbosity of the debug argument: to keep 'bashbot.sh' small, while extending functionality. In addition not every funtion is needed by all bots, so you can disable modules, e.g. by rename the respective module file to 'module.sh.off'. -Modules must use functions provided by 'bahsbot.sh' or the module itself and sould not depend on other modules or addons. +Modules must use only functions provided by 'bahsbot.sh' or the module itself and sould 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 @@ -40,11 +40,11 @@ If a not mandatory module is used in 'bashbot.sh' or 'commands.sh', the use of ` **Addons** resides in ```addons/*.sh.dist``` and are not endabled by default. To activate an addon rename it to end with '.sh', e.g. by ```cp addons/example.sh.dist addons/example.sh```. -Addons must register themself to BASHBOT_EVENTS at startup, e.g. to call a function everytime a message is recieved. +Addons must register themself to BASHBOT_EVENTS at startup, e.g. to call a function everytime a message is received. Addons works similar as 'commands.sh' and 'mycommands.sh' but are much more flexible on when functions/commands are triggered. -Another major difference is: **Addons are executed in the context of the main script**, while 'commands.sh' and 'macommands.sh' are executed as a seperate process. -This is why event functions are time critical and must return as fast as possible. +Another major difference is: **Addons are executed in the context of the main script**, while 'commands.sh' and 'mycommands.sh' are executed new child process on efery execution. +This is why event functions are time critical and must finish as fast as possible. #### Bashbot Events Addons must register functions to bashbot events by providing their name, and internal identifier and a callback function. @@ -54,13 +54,15 @@ Registered functions run in the same process as bashbot, not as a sub process, s Note: For the same reason event function MUST return immediately! Time consuming tasks must be run as a background process, e.g. "long running &" -##### MESSAGE events (all iQuery and/or Message variables are avalible): +##### SEND RECEIVE events + +executed when a Message is received, same iQuery / Message variables are avalible 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 recieved - * BASHBOT_EVENT_CMD a message containing a command is recieved (starts with /) + * 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 @@ -87,7 +89,35 @@ example_echo() { } ``` -##### Other types of events +* BASHBOT_EVENT_SEND is exceuted if data is send or uploaded to Telegram server + +In contrast to other events, BASHBOT_EVENT_SEND is excecuted in a subshell, so there is no need to spawn +a background process for longer running commands and changes to variables are not persistent! + +BASHBOT_EVENT_SEND is for logging purposes, you must not send messages while processing this event. +To avoid wrong use of EVENT_SEND, e.g. fork bomb, event processing is suspended if recursion is detected. + +*usage*: BASHBOT_EVENT_SEND[ "unique-name" ]="callback" + +"callback" is called with paramter "send" or "upload", followed by the arguments used for 'sendJson' or 'upload' functions. + +*Example:* +```bash +# register callback: +BAHSBOT_EVENT_SEND["example_log","1"]="example_log" +EXAMPLE_LOG="${BASHBOT_ETC:-.}/addons/${EXAMPLE_ME}.log" + +# Note: do not call any send message functions from EVENT_SEND! +example_log(){ + local send="$1"; shift + echo "$(date): Type: ${send} Args: $*" >>"${EXAMPLE_LOG}" +} + +``` + +##### TIMER events + +Important: The timer tick is diabled by default and must be enabled by setting BASHBOT_START_TIMER to any value not zero. * BAHSBOT_EVENT_TIMER executed every minute and can be used in 3 variants: oneshot, once a minute, every X minutes. @@ -129,32 +159,6 @@ BAHSBOT_EVENT_TIMER["example_10min","$(( (EVENT_TIMER+10) * -1 ))"]="example_in1 ``` -* BASHBOT_EVENT_SEND is exceuted if data is send or uploaded to Telegram server - -In contrast to other events, BASHBOT_EVENT_SEND is excecuted in a subshell, so there is no need to spawn -a background process for longer running commands and changes to variables are not persistent! - -BASHBOT_EVENT_SEND is for logging purposes, you must not send messages while processing this event. -To avoid wrong use of EVENT_SEND, e.g. fork bomb, event processing is suspended if recursion is detected. - -*usage*: BASHBOT_EVENT_SEND[ "unique-name" ]="callback" - -"callback" is called with paramter "send" or "upload", followed by the arguments used for 'sendJson' or 'upload' functions. - -*Example:* -```bash -# register callback: -BAHSBOT_EVENT_SEND["example_log","1"]="example_log" -EXAMPLE_LOG="${BASHBOT_ETC:-.}/addons/${EXAMPLE_ME}.log" - -# Note: do not call any send message functions from EVENT_SEND! -example_log(){ - local send="$1"; shift - echo "$(date): Type: ${send} Args: $*" >>"${EXAMPLE_LOG}" -} - -``` - ---- #### Create a stripped down Version of your Bot @@ -332,5 +336,5 @@ fi #### [Prev Function Reference](6_reference.md) -#### $$VERSION$$ v0.96-pre-9-gb23aadd +#### $$VERSION$$ v0.96-pre-36-g81c8771 diff --git a/mycommands.sh b/mycommands.sh index 8a9f34a..e39befd 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.96-pre-35-g2bc8f39 +#### $$VERSION$$ v0.96-pre-36-g81c8771 # # uncomment the following lines to overwrite info and help messages @@ -54,7 +54,7 @@ NOTBOTADMIN="Sorry, this command is allowed for bot owner only" if [ "$1" = "startbot" ];then ################### - # this function is run once after startup when the first message is recieved + # this function is run once after startup when the first message is received my_startup(){ # send message ito first user on startup send_normal_message "${CHAT[ID]}" "Hi, you was the first one after startup!" @@ -72,7 +72,7 @@ else mycommands() { ############## - # a service Message was recieved + # a service Message was received # add your own stuff here if [ -n "${SERVICE}" ]; then diff --git a/mycommands.sh.clean b/mycommands.sh.clean index a8b2905..f6fb58e 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.96-pre-35-g2bc8f39 +#### $$VERSION$$ v0.96-pre-36-g81c8771 # ########## @@ -53,7 +53,7 @@ export SILENCER="no" # export BASHBOT_CURL_ARGS="--socks5-hostname 127.0.0.1" # regular SOCKS if [ "$1" = "startbot" ];then - # run once after startup when the first message is recieved + # run once after startup when the first message is received my_startup(){ : } @@ -69,7 +69,7 @@ else mycommands() { ############## - # a service Message was recieved + # a service Message was received # add your own stuff here if [ -n "${SERVICE}" ]; then