provide bashbot function reference

README.md

@@ -92,4 +92,4 @@ No - its not less (in)secure as any other Bot written in any other language. But
 
 If you feel that there's something missing or if you found a bug, feel free to submit a pull request!
 
-#### $$VERSION$$ v0.6-rc1-11-gba80ec6
+#### $$VERSION$$ v0.60-rc2-0-gc581932

README.txt

@@ -66,6 +66,24 @@ Getting started
 * Customizing commands.sh
 * Seperate Bot logic from command
 * Test your Bot with shellcheck
+* link:doc/6_reference.md[Bashbot functions reference]
+
+Note on Keyboards
+~~~~~~~~~~~~~~~~~
+
+To make use of Keyboards easyer we changed the format of `send_keyboard`
+and `send_message "mykeyboardstartshere ..."`. Now you must provide the
+keyboards in Telegram JSON Array style "[ "yes" , "no" ]". The advantage
+is that you can create every type of keyboard without relying on bashbot
+`send_keyboard` functionality. *This is incompatible with keyboards in
+bashbot versions older than 0.6!*
+
+_Example Keyboards_:
+
+* Yes No in one row: "[ "yes" , "no" ]"
+* Yes No ind two rows: "[ "yes" ] , [ "no" ]"
+* numpad keyboard: "[ "1" , "2" , "3" ] , [ "4" , "5" , "6" ] , [ "7" ,
+"8" , "9" ] , [ "0" ]"
 
 Security Considerations
 ~~~~~~~~~~~~~~~~~~~~~~~
@@ -122,5 +140,5 @@ That's it!
 If you feel that there's something missing or if you found a bug, feel
 free to submit a pull request!
 
-latexmath:[\[VERSION\]] v0.6-rc1-7-g14eb352
+latexmath:[\[VERSION\]] v0.60-rc2-0-gc581932
-+++++++++++++++++++++++++++++++++++++++++++
+++++++++++++++++++++++++++++++++++++++++++++

bashbot.cron

@@ -7,7 +7,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.6-rc1-7-g14eb352
+#### $$VERSION$$ v0.60-rc2-0-gc581932
 
 
 SHELL=/bin/sh

bashbot.rc

@@ -1,7 +1,7 @@
 #!/bin/sh
 # description: Start or stop telegram-bash-bot
 #
-#### $$VERSION$$ v0.6-rc1-7-g14eb352
+#### $$VERSION$$ v0.60-rc2-0-gc581932
 # shellcheck disable=SC2009
 # shellcheck disable=SC2181
 

bashbot.sh

@@ -10,7 +10,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.6-rc1-7-g14eb352
+#### $$VERSION$$ v0.60-rc2-0-gc581932
 #
 # Exit Codes:
 # - 0 sucess (hopefully)

calc

@@ -3,7 +3,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.60-dev3-7-gf5538ef
+#### $$VERSION$$ v0.60-rc2-0-gc581932
 
 # adjust your language setting here
 # https://github.com/topkecleon/telegram-bot-bash#setting-up-your-environment

commands.sh

@@ -4,7 +4,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.6-rc1-7-g14eb352
+#### $$VERSION$$ v0.60-rc2-0-gc581932
 #
 # shellcheck disable=SC2154
 # shellcheck disable=SC2034
@@ -156,7 +156,7 @@ else
 			if [ "$res" -eq 0 ] ; then killproc && send_message "${CHAT[ID]}" "Command canceled.";else send_message "${CHAT[ID]}" "No command is currently running.";fi
 			;;
 		*)	# forward input to interactive chat if running
-			if tmux ls | grep -v send | grep -q $copname;then inproc; fi
+			if tmux ls | grep -v send | grep -q "$copname"; then inproc; fi
 			;;
 	esac
 fi

doc/1_firstbot.md

@@ -70,5 +70,5 @@ git clone --recursive https://github.com/topkecleon/telegram-bot-bash
 ```
 3. Change to directory ```telegram-bot.bash```, run ```./bashbot.sh init``` and follow the instructions. At this stage you are asked for your Bots token given by botfather.
 
-#### $$VERSION$$ v0.6-rc1-11-gba80ec6
+#### $$VERSION$$ v0.60-rc2-0-gc581932
 

doc/2_usage.md

@@ -154,6 +154,6 @@ Allowed values: typing for text messages, upload_photo for photos, record_video
 send_action "${CHAT[ID]}" "action"
 ```
 
-#### $$VERSION$$ v0.6-rc1-11-gba80ec6
+#### $$VERSION$$ v0.60-rc2-0-gc581932
 
 

doc/3_advanced.md

@@ -153,5 +153,5 @@ To send stickers through an *inline query*:
 answer_inline_query "$iQUERY_ID" "cached_sticker" "identifier for the sticker"
 ```
 
-#### $$VERSION$$ v0.6-rc1-11-gba80ec6
+#### $$VERSION$$ v0.60-rc2-0-gc581932
 

doc/4_expert.md

@@ -102,5 +102,5 @@ An example crontab is provided in ```bashbot.cron```.
 - if you run bashbot as an other user or a system service edit ```bashbot.cron``` to fit your needs and replace username```nobody``` with the username you want to run bashbot. copy the modified file to ```/etc/cron.d/bashbot```
 
 
-#### $$VERSION$$ v0.6-rc1-11-gba80ec6
+#### $$VERSION$$ v0.60-rc2-0-gc581932
 

doc/5_practice.md

@@ -112,5 +112,5 @@ In bashbot.sh line 490:
 Here are two warnings in bashbots scripts. The first is a hint you may use shell substitions instead of sed, this is really possible and much faster!
 The second warning is about an unused variable, this is true because in our examples CONTACT is not used but assigned in case you want to use it :-)
 
-#### $$VERSION$$ v0.6-rc1-11-gba80ec6
+#### $$VERSION$$ v0.60-rc2-0-gc581932
 

doc/6_reference.md

@@ -1,4 +1,4 @@
-## Bashbot functions reference
+## Bashbot function reference
 
 ### Send, forward, delete Messages
 
@@ -15,24 +15,41 @@ send_action "${CHAT[ID]}" "record_audio"
 
 
 ##### send_normal_message
-*usage:* 
+sen_normal_message send text only messages to chat.
+
+*usage:*  send_normal_message "${CHAT[ID]}" "message"
 
 *example:* 
+```bash
+send_normal_message "${CHAT[ID]}" "this is a text message"
+```
+
 
 ##### send_markdown_message
-*usage:* 
+Telegram supports onyl a [reduced set of Markdown](https://core.telegram.org/bots/api#markdown-style)
+
+*usage:* send_markdown_message "${CHAT[ID]}" "message"
 
 *example:* 
+```bash
+send_normal_message "${CHAT[ID]}" "this is a markdown  message, next word is *bold*"
+send_normal_message "${CHAT[ID]}" "*bold* _italic_ [text](link)"
+```
 
 ##### send_html_message
-*usage:* 
+Telegram supports onyl a [reduced set of HTML](https://core.telegram.org/bots/api#html-style)
+
+*usage:* send_html_message "${CHAT[ID]}" "message" 
 
 *example:* 
+```bash
+send_normal_message "${CHAT[ID]}" "this is a markdown  message, next word is <b>bold</b>"
+send_normal_message "${CHAT[ID]}" "<b>bold</b> <i>italic><i> <em>italic>/em> <a href="link">Text</a>"
+```
 
 ##### forward
-*usage:* 
+*usage:* forward "${CHAT[ID]}" "${MESSAGE[ID]}"
 
-*example:* 
 
 ----
 
@@ -40,23 +57,26 @@ send_action "${CHAT[ID]}" "record_audio"
 Send Message must (only) used to process the output of interactive chats and background jobs.
 **For your commands I reccommend the more dedicated send_xxx_message() functions above.**
 
-*usage:* 
+*usage:* send_message "${CHAT[ID]}" "message"
 
 *example:* - see [Usage](2_usage.md#send_message) and [Advanced Usage](3_advanced.md#Interactive-Chats)
 
 ----
 
 ##### delete_message
-*usage:* 
+If your Bot is Admin in a Chat you can delete every message, if not you can delete only your Bot messages.
 
-*example:* 
+*usage:* delete_message "${CHAT[ID]}" "${MESSAGE[ID]}"
 
 ----
 
 ##### answer_inline_query
-*usage:* 
+Inline Queries allows users to interact with your bot via directly without sending extra commands.
+answer_inline_query provide the result to a users Inline Query
 
-*example:* 
+*usage:* answer_inline_query "$iQUERY_ID" "type" "type arg 1" ... "type arg n" 
+
+*example:* - see [Advanced Usage](3_advanced.md#Inline-queries)
 
 ----
 
@@ -66,21 +86,27 @@ Send Message must (only) used to process the output of interactive chats and bac
 *usage:* 
 
 *example:* 
+```bash
+```
 
 ##### send_file
-*usage:* 
+There are some ways to send files (photos, stickers, audio, media, etc.), [see more](https://core.telegram.org/bots/api#sending-files)
+
+*usage:* send_file "${CHAT[ID]}" "file" "caption"
 
 *example:* 
+```bash
+send_file "${CHAT[ID]}" "/home/user/doge.jpg" "Lool"
+send_file "${CHAT[ID]}" "https://www.domain,com/something.gif" "Something"
+```
 
 ##### send_location
-*usage:* 
+*usage:* send_location "${CHAT[ID]}" "Latitude" "Longitude"
 
-*example:* 
 
 ##### send_venue
-*usage:* 
+*usage:* send_venue "${CHAT[ID]}" "Latitude" "Longitude" "Title" "Address" "foursquare id (optional)"
 
-*example:* 
 
 ----
 
@@ -99,102 +125,188 @@ send_keyboard "${CHAT[ID]}" "[ \"1\" , \"2\" , \"3\" ] , [ \"4\" , \"5\" , \"6\"
 ##### remove_keyboard
 *usage:* 
 
-*example:* 
 
 ### Manage users 
 
 ##### kick_chat_member
-*usage:* 
+If Bot is Admin you can kick and ban a user.
+
+*usage:*  kick_chat_member "${CHAT[ID]}" "${USER[ID]}"
 
-*example:* 
 
 ##### unban_chat_member
-*usage:* 
+If Bot is Admin you can unban a kicked user.
 
-*example:* 
+*usage:*  unban_chat_member "${CHAT[ID]}" "${USER[ID]}"
 
 ##### leave_chat
-*usage:* 
+Bot will leave chat.
 
-*example:* 
+*usage:* leave_chat "${CHAT[ID]}"
+
+```bash
+if _is_admin ; then 
+ send_markdown_message "${CHAT[ID]}" "*LEAVING CHAT...*"
+ leave_chat "${CHAT[ID]}"
+fi
+```
 
 ----
 
 ##### user_is_creator
-*usage:* 
+Returns true (0) if user is creator of chat or chat is a one2one / private chat.
 
-*example:* 
+*usage:* user_is_creator "${CHAT[ID]}" "${USER[ID]}"
+
+*alias:* _is_creator
 
 ##### user_is_admin
-*usage:* 
+Returns true (0) if user is admin or creator of chat.
+ 
+*usage:* user_is_admin "${CHAT[ID]}" "${USER[ID]}"
+
+*alias:* _is_creator
 
 *example:* 
+```bash
+if _is_admin ; then 
+  send_markdown_message "${CHAT[ID]}" "*LEAVING CHAT...*"
+  leave_chat "${CHAT[ID]}"
+fi
+```
 
 ##### user_is_botadmin
-*usage:* 
+Returns true (0) if user is owner / admin of bot. 
+botadmin is stored in file './botadmin'
+
+*usage:*  user_is_botadmin "${CHAT[ID]}" "${USER[ID]}"
+
+*alias:* _is_botadmin
 
 *example:* 
+```bash
+ _is_botadmin && send_markdown_message "${CHAT[ID]}" "You are *BOTADMIN*."
+```
 
 ##### user_is_allowed
-*usage:* 
+Bahsbot supports User Access Control, see [Advanced Usage](4_advanced.ma)
+
+*usage:* user_is_allowed "${USER[ID]}" "what" "${CHAT[ID]}"
 
 *example:* 
+```bash
+if ! user_is_allowed "${USER[ID]}" "start" "${CHAT[ID]}" ; then
+  send_normal_message "${CHAT[ID]}" "You are not allowed to start Bot."
+fi
+```
 
 ### Interactive and backgound jobs
 
 ##### startproc
-*usage:* 
+With ```startproc``` you can start scrips (or C or python program etc.). The text that the script will output will be sent in real time to the user, and all user input will be sent to the script. see [Advanced Usage](3_advanced.md#Interactive-Chats)
+
+*usage:* startproc "./script"
 
 *example:* 
+```bash
+startproc './calc'
+```
 
 ##### checkproc
-*usage:* 
+Returns true (0) if an interactive script is running in chat. 
+
+*usage:* checkprog
 
 *example:* 
+```bash
+checkproc 
+if [ "$res" -gt 0 ] ; then
+  startproc "./calc"
+else
+   send_normal_message "${CHAT[ID]}" "Calc already running ..."
+fi
+```
 
 ##### killproc
-*usage:* 
+*usage:* killproc
 
 *example:* 
+```bash
+checkprog
+if [ "$res" -eq 0 ]; then
+  killproc && send_message "${CHAT[ID]}" "Command canceled."
+else
+  send_message "${CHAT[ID]}" "Command is not running."
+fi
+```
 
 ----
 
 ##### background
-*usage:* 
+*usage:* background "./script" "jobname"
 
 *example:* 
+```bash
+background "./notify" "notify"
+```
 
 ##### checkback
-*usage:* 
+Returns true (0) if an background job is running in chat. 
+
+*usage:*  checkback "jobname"
 
 *example:* 
+```bash
+checkback "notify"
+if [ "$res" -gt 0 ] ; then
+  send_normal_message "${CHAT[ID]}" "Start notify"
+  background "./notify" "notify"
+else
+ send_normal_message "${CHAT[ID]}" "Process notify already running."
+fi
+```
 
 ##### killback
-*usage:* 
+*usage:* killback "jobname"
 
 *example:* 
+```bash
+checkback "notify"
+if [ "$res" -eq 0 ] ; then
+  send_normal_message "${CHAT[ID]}" "Kill notify"
+  killback "notify"
+else
+  send_normal_message "${CHAT[ID]}" "Process notify not run."
+fi
+```
 
 ### Bashbot internal 
 These functions are for internal use only and must not used in your bot commands.
 
 ##### send_text
-*usage:* 
+*usage:* send_text "${CHAT[ID]}" "message"
 
 ----
 
 ##### JsonDecode
-*usage:* 
+Outputs decoded string to STDOUT
+
+*usage:* JsonDecode "string"
 
 ##### JsonGetString
-*usage:* 
+Reads JSON fro STDIN and Outputs found String to STDOUT
+
+*usage:*  JsonGetString `"path","to","string"`
 
 ##### JsonGetValue
-*usage:* 
+Reads JSON fro STDIN and Outputs found Value to STDOUT
+
+*usage:*  JsonGetValue `"path","to","value"`
 
 ----
 
 ##### get_chat_member_status
-*usage:* 
+*usage:* get_chat_member_status "${CHAT[ID]}" "${USER[ID]}"
 
 ----
 
@@ -213,5 +325,5 @@ The name of your bot is availible as bash variable "$ME", there is no need to ca
 ##### inproc
 Send Input from Telegram to waiting Interactive Chat.
 
-#### $$VERSION$$ v0.6-rc1-11-gba80ec6
+#### $$VERSION$$ v0.60-rc2-0-gc581932
 

notify

@@ -2,7 +2,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.6-rc1-7-g14eb352
+#### $$VERSION$$ v0.60-rc2-0-gc581932
 
 # adjust your language setting here
 # https://github.com/topkecleon/telegram-bot-bash#setting-up-your-environment

question

@@ -3,7 +3,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.6-rc1-7-g14eb352
+#### $$VERSION$$ v0.60-rc2-0-gc581932
 
 # adjust your language setting here
 # https://github.com/topkecleon/telegram-bot-bash#setting-up-your-environment

version

@@ -1,6 +1,6 @@
 #!/bin/bash
 #
-#### $$VERSION$$ v0.6-rc1-7-g14eb352
+#### $$VERSION$$ v0.60-rc2-0-gc581932
 # shellcheck disable=SC2016
 #
 # Easy Versioning in git: