mirror of
https://github.com/octoleo/telegram-bot-bash.git
synced 2024-06-03 10:50:52 +00:00
176 lines
15 KiB
HTML
176 lines
15 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
||
<html xmlns="http://www.w3.org/1999/xhtml">
|
||
<head>
|
||
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
|
||
<meta http-equiv="Content-Style-Type" content="text/css" />
|
||
<meta name="generator" content="pandoc" />
|
||
<title>Bashobot Documentation - doc/5_practice.html</title>
|
||
<style type="text/css">code{white-space: pre;}</style>
|
||
<style type="text/css">
|
||
div.sourceCode { overflow-x: auto; }
|
||
table.sourceCode, tr.sourceCode, td.lineNumbers, td.sourceCode {
|
||
margin: 0; padding: 0; vertical-align: baseline; border: none; }
|
||
table.sourceCode { width: 100%; line-height: 100%; }
|
||
td.lineNumbers { text-align: right; padding-right: 4px; padding-left: 4px; color: #aaaaaa; border-right: 1px solid #aaaaaa; }
|
||
td.sourceCode { padding-left: 5px; }
|
||
code > span.kw { color: #007020; font-weight: bold; } /* Keyword */
|
||
code > span.dt { color: #902000; } /* DataType */
|
||
code > span.dv { color: #40a070; } /* DecVal */
|
||
code > span.bn { color: #40a070; } /* BaseN */
|
||
code > span.fl { color: #40a070; } /* Float */
|
||
code > span.ch { color: #4070a0; } /* Char */
|
||
code > span.st { color: #4070a0; } /* String */
|
||
code > span.co { color: #60a0b0; font-style: italic; } /* Comment */
|
||
code > span.ot { color: #007020; } /* Other */
|
||
code > span.al { color: #ff0000; font-weight: bold; } /* Alert */
|
||
code > span.fu { color: #06287e; } /* Function */
|
||
code > span.er { color: #ff0000; font-weight: bold; } /* Error */
|
||
code > span.wa { color: #60a0b0; font-weight: bold; font-style: italic; } /* Warning */
|
||
code > span.cn { color: #880000; } /* Constant */
|
||
code > span.sc { color: #4070a0; } /* SpecialChar */
|
||
code > span.vs { color: #4070a0; } /* VerbatimString */
|
||
code > span.ss { color: #bb6688; } /* SpecialString */
|
||
code > span.im { } /* Import */
|
||
code > span.va { color: #19177c; } /* Variable */
|
||
code > span.cf { color: #007020; font-weight: bold; } /* ControlFlow */
|
||
code > span.op { color: #666666; } /* Operator */
|
||
code > span.bu { } /* BuiltIn */
|
||
code > span.ex { } /* Extension */
|
||
code > span.pp { color: #bc7a00; } /* Preprocessor */
|
||
code > span.at { color: #7d9029; } /* Attribute */
|
||
code > span.do { color: #ba2121; font-style: italic; } /* Documentation */
|
||
code > span.an { color: #60a0b0; font-weight: bold; font-style: italic; } /* Annotation */
|
||
code > span.cv { color: #60a0b0; font-weight: bold; font-style: italic; } /* CommentVar */
|
||
code > span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Information */
|
||
</style>
|
||
</head>
|
||
<body>
|
||
<div id="header">
|
||
<h1 class="title">Bashobot Documentation - doc/5_practice.html</h1>
|
||
</div>
|
||
<h4 id="home"><a href="../README.html">Home</a></h4>
|
||
<h2 id="best-practices">Best Practices</h2>
|
||
<h3 id="new-to-bot-development">New to bot development?</h3>
|
||
<p>If you are new to Bot development read <a href="https://core.telegram.org/bots">Bots: An introduction for developers</a> and consult <a href="https://core.telegram.org/bots/api/">Telegram Bot API Documentation</a>.</p>
|
||
<p>In addition you should know about <a href="https://core.telegram.org/bots#3-how-do-i-create-a-bot">BotFather, the one bot to rule them all</a>. It will help you create new bots and change settings for existing ones. <a href="https://core.telegram.org/bots#generating-an-authorization-token">Commands known by Botfather</a></p>
|
||
<p>If you dont’t have a github account, it may time to <a href="https://github.com/pricing">sepup a free account now</a></p>
|
||
<h3 id="add-commands-to-mycommands.sh-only">Add commands to mycommands.sh only</h3>
|
||
<p>To ease updates never change <code>bashbot.sh</code>, instead your commands and functions must go to <code>mycommands.sh</code> . Insert your Bot commands in the <code>case ... esac</code> block of the ‘mycommands()’ function:</p>
|
||
<div class="sourceCode"><pre class="sourceCode bash"><code class="sourceCode bash"><span class="co"># file: mycommands.sh</span>
|
||
<span class="co"># your additional bahsbot commands</span>
|
||
|
||
<span class="co"># uncomment the following lines to overwrite info and help messages</span>
|
||
<span class="va">bashbot_info=</span><span class="st">'This is *MY* variant of _bashbot_, the Telegram bot written entirely in bash.</span>
|
||
<span class="st">'</span>
|
||
|
||
<span class="va">bashbot_help=</span><span class="st">'*Available commands*:</span>
|
||
<span class="st">/echo message - _echo the given messsage_</span>
|
||
<span class="st">'</span>
|
||
|
||
<span class="co"># </span><span class="al">NOTE</span><span class="co">: command can have @botname attached, you must add * in case tests... </span>
|
||
<span class="fu">mycommands()</span> <span class="kw">{</span>
|
||
|
||
<span class="kw">case</span> <span class="st">"</span><span class="va">$MESSAGE</span><span class="st">"</span><span class="kw"> in</span>
|
||
<span class="st">'/echo'</span>*<span class="kw">)</span> <span class="co"># example echo command</span>
|
||
<span class="ex">send_normal_message</span> <span class="st">"</span><span class="va">${CHAT[ID]}</span><span class="st">"</span> <span class="st">"</span><span class="va">$MESSAGE</span><span class="st">"</span>
|
||
<span class="kw">;;</span>
|
||
<span class="co"># .....</span>
|
||
<span class="kw">esac</span>
|
||
<span class="kw">}</span></code></pre></div>
|
||
<h3 id="overwrite-extend-and-disable-global-commands">Overwrite, extend and disable global commands</h3>
|
||
<p>You can overwrite a global bashbot command by placing the same commands in <code>mycommands.sh</code> and add <code>return 1</code> ad the end of your command, see ‘/kickme’ below.</p>
|
||
<p>To disable a global bashbot command place create a command simply containing ‘return 1’, see ‘/leave’ below.</p>
|
||
<p>In case you want to add some processing to the global bashbot command add <code>return 0</code>, then both command will be executed.</p>
|
||
<p><strong>Learn more about <a href="https://core.telegram.org/bots#commands">Bot commands</a>.</strong></p>
|
||
<div class="sourceCode"><pre class="sourceCode bash"><code class="sourceCode bash"><span class="co"># file: commands.sh</span>
|
||
|
||
<span class="kw">case</span> <span class="st">"</span><span class="va">$MESSAGE</span><span class="st">"</span><span class="kw"> in</span>
|
||
<span class="co">##########</span>
|
||
<span class="co"># command overwrite examples</span>
|
||
<span class="st">'info'</span>*<span class="kw">)</span> <span class="co"># output date in front of regular info</span>
|
||
<span class="ex">send_normal_message</span> <span class="st">"</span><span class="va">${CHAT[ID]}</span><span class="st">"</span> <span class="st">"</span><span class="va">$(</span><span class="fu">date</span><span class="va">)</span><span class="st">"</span>
|
||
<span class="bu">return</span> 0
|
||
<span class="kw">;;</span>
|
||
<span class="st">'/kickme'</span>*<span class="kw">)</span> <span class="co"># this will replace the /kickme command</span>
|
||
<span class="ex">send_markdown_mesage</span> <span class="st">"</span><span class="va">${CHAT[ID]}</span><span class="st">"</span> <span class="st">"*This bot will not kick you!*"</span>
|
||
<span class="bu">return</span> 1
|
||
<span class="kw">;;</span>
|
||
<span class="st">'/leave'</span>*<span class="kw">)</span> <span class="co"># disable all commands starting with leave</span>
|
||
<span class="bu">return</span> 1
|
||
<span class="kw">;;</span>
|
||
<span class="kw">esac</span></code></pre></div>
|
||
<h3 id="seperate-logic-from-commands">Seperate logic from commands</h3>
|
||
<p>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 <code>mycommands.sh</code> and call the from your command. Example:</p>
|
||
<div class="sourceCode"><pre class="sourceCode bash"><code class="sourceCode bash"><span class="co"># file: mycommands.sh</span>
|
||
<span class="co"># your additional bahsbot commands</span>
|
||
|
||
<span class="fu">mycommands()</span> <span class="kw">{</span>
|
||
|
||
<span class="kw">case</span> <span class="st">"</span><span class="va">$MESSAGE</span><span class="st">"</span><span class="kw"> in</span>
|
||
<span class="st">'/process'</span>*<span class="kw">)</span> <span class="co"># logic for /process is done in process_message </span>
|
||
<span class="va">result=</span><span class="st">"</span><span class="va">$(</span><span class="ex">process_message</span> <span class="st">"</span><span class="va">$MESSAGE</span><span class="st">"</span><span class="va">)</span><span class="st">"</span>
|
||
<span class="ex">send_normal_message</span> <span class="st">"</span><span class="va">${CHAT[ID]}</span><span class="st">"</span> <span class="st">"</span><span class="va">$result</span><span class="st">"</span>
|
||
<span class="kw">;;</span>
|
||
<span class="kw">esac</span>
|
||
|
||
<span class="kw">}</span>
|
||
|
||
<span class="co"># place your functions here</span>
|
||
|
||
<span class="fu">process_message()</span> <span class="kw">{</span>
|
||
<span class="bu">local</span> <span class="va">ARGS=</span><span class="st">"</span><span class="va">${1#</span>/* <span class="va">}</span><span class="st">"</span> <span class="co"># remove command </span>
|
||
<span class="bu">local</span> <span class="va">TEXT</span> <span class="va">OUTPUT=</span><span class="st">""</span>
|
||
|
||
<span class="co"># process every word in MESSAGE, avoid globbing</span>
|
||
<span class="kw">set</span> <span class="ex">-f</span>
|
||
<span class="kw">for</span> <span class="ex">WORD</span> in <span class="va">$ARGS</span>
|
||
<span class="kw">do</span>
|
||
<span class="co"># process links </span>
|
||
<span class="kw">if [[</span> <span class="st">"</span><span class="va">$WORD</span><span class="st">"</span> <span class="ot">==</span> <span class="st">"https://"</span>*<span class="kw"> ]]</span>; <span class="kw">then</span>
|
||
<span class="va">REPORT=</span><span class="st">"</span><span class="va">$(</span><span class="ex">dosomething_with_link</span> <span class="st">"</span><span class="va">$WORD</span><span class="st">"</span><span class="va">)</span><span class="st">"</span>
|
||
<span class="co"># no link, add as text</span>
|
||
<span class="kw">else</span>
|
||
<span class="va">TEXT=</span><span class="st">"</span><span class="va">$(</span><span class="bu">echo</span> <span class="st">"</span><span class="va">${TEXT}</span><span class="st"> </span><span class="va">$WORD</span><span class="st">"</span><span class="va">)</span><span class="st">"</span>
|
||
<span class="bu">continue</span>
|
||
<span class="kw">fi</span>
|
||
<span class="co"># compose result</span>
|
||
<span class="va">OUTPUT=</span><span class="st">"* </span><span class="va">${REPORT}</span><span class="st"> </span><span class="va">${WORD}</span><span class="st"> </span><span class="va">${TEXT}</span><span class="st">"</span>
|
||
<span class="va">TEXT=</span><span class="st">""</span>
|
||
<span class="kw">done</span>
|
||
|
||
<span class="co"># return result, reset globbing in case we had no ARGS</span>
|
||
<span class="bu">echo</span> <span class="st">"</span><span class="va">${OUTPUT}${TEXT}</span><span class="st">"</span>
|
||
<span class="kw">}</span></code></pre></div>
|
||
<h3 id="test-your-bot-with-shellcheck">Test your Bot with shellcheck</h3>
|
||
<p>Shellcheck is a static linter for shell scripts providing excellent tips and hints for shell coding pittfalls. You can <a href="https://www.shellcheck.net/">use it online</a> or <a href="https://github.com/koalaman/shellcheck#installing">install it on your system</a>. All bashbot scripts are linted by shellcheck.</p>
|
||
<p>Shellcheck examples:</p>
|
||
<div class="sourceCode"><pre class="sourceCode bash"><code class="sourceCode bash">$ <span class="ex">shellcheck</span> -x mybotcommands.inc.sh
|
||
|
||
<span class="ex">Line</span> 17:
|
||
<span class="va">TEXT=</span><span class="st">"</span><span class="va">$(</span><span class="bu">echo</span> <span class="st">"</span><span class="va">${TEXT}</span><span class="st"> </span><span class="va">$WORD</span><span class="st">"</span><span class="va">)</span><span class="st">"</span>
|
||
^<span class="ex">--</span> SC2116: Useless echo? Instead of <span class="st">'cmd $(echo foo)'</span>, just use <span class="st">'cmd foo'</span>.
|
||
</code></pre></div>
|
||
<p>As you can see my <code>mybotcommands.inc.sh</code> contains an useless echo command in ‘TEXT=’ assigment and can be replaced by <code>TEXT="${TEXT}${WORD}"</code></p>
|
||
<div class="sourceCode"><pre class="sourceCode bash"><code class="sourceCode bash">$ <span class="ex">shellcheck</span> -x examples/notify
|
||
<span class="ex">OK</span>
|
||
$ <span class="ex">shellcheck</span> -x examples/question
|
||
<span class="ex">OK</span>
|
||
$ <span class="ex">shellcheck</span> -x commands.sh
|
||
<span class="ex">OK</span>
|
||
$ <span class="ex">shellcheck</span> -x bashbot.sh
|
||
|
||
<span class="ex">In</span> bashbot.sh line 123:
|
||
<span class="va">text=</span><span class="st">"</span><span class="va">$(</span><span class="bu">echo</span> <span class="st">"</span><span class="va">$text</span><span class="st">"</span> <span class="kw">|</span> <span class="fu">sed</span> <span class="st">'s/ mynewlinestartshere /\r\n/g'</span><span class="va">)</span><span class="st">"</span> <span class="co"># hack for linebreaks in startproc scripts</span>
|
||
^<span class="ex">--</span> SC2001: See if you can use <span class="va">${variable//</span>search<span class="va">/</span>replace<span class="va">}</span> instead.
|
||
|
||
|
||
<span class="ex">In</span> bashbot.sh line 490:
|
||
<span class="va">CONTACT[USER_ID]=</span><span class="st">"</span><span class="va">$(</span><span class="fu">sed</span> -n -e <span class="st">'/\["result",'</span><span class="va">$PROCESS_NUMBER</span><span class="st">',"message","contact","user_id"\]/ s/.*\][ \t]"\(.*\)"$/\1/p'</span> <span class="op"><</span><span class="st">"</span><span class="va">$TMP</span><span class="st">"</span><span class="va">)</span><span class="st">"</span>
|
||
^<span class="ex">--</span> SC2034: CONTACT appears unused. Verify it or export it.</code></pre></div>
|
||
<p>The example show two warnings in bashbots scripts. The first is a hint you may use shell substitions instead of sed, this is fixed and much faster as the “echo | sed” solution. 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 :-)</p>
|
||
<h4 id="prev-best-practice"><a href="5_practice.html">Prev Best Practice</a></h4>
|
||
<h4 id="next-functions-reference"><a href="6_reference.html">Next Functions Reference</a></h4>
|
||
<h4 id="version-v0.90-dev2-0-gec85636"><br /><span class="math display"><em>V</em><em>E</em><em>R</em><em>S</em><em>I</em><em>O</em><em>N</em></span><br /> v0.90-dev2-0-gec85636</h4>
|
||
</body>
|
||
</html>
|