summaryrefslogtreecommitdiffstats
path: root/doc/rainerscript.html
blob: 63a79040ecbda1ff1cff689ddcb4cc75ca8d9477 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html><head>
<meta http-equiv="Content-Language" content="en"><title>RainerScript</title>

</head>
<body>
<h1>RainerScript</h1>
<p><b>RainerScript is a scripting language specifically
designed and well-suited
for processing network events and configuring event processors</b>
(with the most prominent sample being syslog). While RainerScript is
theoritically usable with various softwares, it currently is being
used, and developed for, rsyslog. Please note that RainerScript may not
be abreviated as rscript, because that's somebody elses trademark.</p>
<p>RainerScript is currently under development. It has its first
appearance in rsyslog 3.12.0, where it provides complex expression
support. However, this is only a very partial implementatio of the
scripting language. Due to technical restrictions, the final
implementation will have a slightly different syntax. So while you are
invited to use the full power of expresssions, you unfortunatley need
to be prepared to change your configuration files at some later points.
Maintaining backwards-compatibility at this point would cause us to
make too much compromise. Defering the release until everything is
perfect is also not a good option. So use your own judgement.</p>
<p>A formal definition of the language can be found in <a href="rscript_abnf.html">RainerScript ABNF</a>. The
rest of this document describes the language from the user's point of
view. Please note that this doc is also currently under development and
can (and will) probably improve as time progresses. If you have
questions, use the rsyslog forum. Feedback is also always welcome.</p>
<h2>Data Types</h2>
RainerScript is a typeless language. That doesn't imply you don't need
to care about types. Of course, expressions like "A" + "B" will not
return a valid result, as you can't really add two letters (to
concatenate them, use the concatenation operator &amp;).
&nbsp;However, all type conversions are automatically done by the
script interpreter when there is need to do so.<br>
<h2>Expressions</h2>
The language supports arbitrary complex expressions. All usual
operators are supported. The precedence of operations is as follows
(with operations being higher in the list being carried out before
those lower in the list, e.g. multiplications are done before additions.<br>
<ul>
<li>expressions in parenthesis</li><li>not, unary minus</li><li>*, /, % (modulus, as in C)</li><li>+, -, &amp; (string concatenation)</li><li>==, !=, &lt;&gt;, &lt;, &gt;, &lt;=, &gt;=, contains (strings!), startswith (strings!)</li><li>and</li><li>or</li>
</ul>For example, "not a == b" probably returns not what you intended.
The script processor will first evaluate "not a" and then compare the
resulting boolean to the value of b. What you probably intended to do
is "not (a == b)". And if you just want to test for inequality, we
highly suggest to use "!=" or "&lt;&gt;". Both are exactly the same and
are provided so that you can pick whichever you like best. So inquality
of a and b should be tested as "a &lt;&gt; b". The "not" operator
should be reserved to cases where it actually is needed to form a
complex boolean expression. In those cases, parenthesis are highly
recommended.
<h2>Functions</h2>
<p>RainerScript supports a currently quite limited set of functions:
<ul>
<li>getenv(str) - like the OS call, returns the value of the environment
variable, if it exists. Returns an empty string if it does not exist.
<li>strlen(str) - returns the length of the provided string
<li>tolower(str) - converts the provided string into lowercase
</ul>
<p>The following example can be used to build a dynamic filter based on some environment
variable:
<pre>
if $msg contains getenv('TRIGGERVAR') then /path/to/errfile
</pre>
<p>[<a href="rsyslog_conf.html">rsyslog.conf overview</a>]
[<a href="manual.html">manual index</a>] [<a href="http://www.rsyslog.com/">rsyslog site</a>]</p>
<p><font size="2">This documentation is part of the
<a href="http://www.rsyslog.com/">rsyslog</a>
project.<br>
Copyright &copy; 2008, 2009 by <a href="http://www.gerhards.net/rainer">Rainer Gerhards</a> and
<a href="http://www.adiscon.com/">Adiscon</a>.
Released under the GNU GPL version 3 or higher.</font></p>
</body></html>