/usr/share/doc/liquidsoap/html/language.html is in liquidsoap 1.1.1-6ubuntu2.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
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 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 | <?xml version="1.0"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML \
1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head>
<meta content="text/html; charset=UTF-8" http-equiv="content-type" />
<title>Liquidsoap :: Liquidsoap scripting language</title>
<link href="css/style.css" type="text/css" rel="stylesheet" />
</head>
<body>
<div id="wrapper">
<div id="header">
<div id="logo">
<h1>Liquidsoap</h1>
<h2>audio stream generation</h2>
</div>
<div>
<ul id="menu">
<li id="menu-about">
<a href="index.html">about</a></li>
<li id="menu-doc-index">
<a href="documentation.html">documentation</a></li>
<li id="menu-doc-api">
<a href="reference.html">API</a></li>
<li id="menu-doc-snippets">
<a href="scripts/index.html">snippets</a></li>
<li id="menu-developers">
<a href="https://github.com/savonet/liquidsoap/issues">developers</a></li>
</ul>
</div>
</div>
<div id="content"><div>
<h3>Liquidsoap's scripting language</h3>
<p>
Liquidsoap's scripting language is a simple functional language,
with labels and optional parameters.
It is statically typed, but infers types – you don't have to write any types.
It allows the direct handling of liquidsoap notions such
as <a href="sources.html">sources</a> and <a href="requests.html">requests</a>,
and also provides a convenient syntax for specifying time intervals.
</p>
<h4>Constants</h4>
<p>
The constants and their syntax are quite common:
</p>
<ul>
<li>
integers, such as <code>42</code>;</li>
<li>
floats, such as <code>3.14</code>;</li>
<li>
booleans <code>true</code> and <code>false</code>;</li>
<li>
strings, such as <code>"foo"</code> or <code>'bar'</code>.</li>
</ul>
<p>
<b>Beware</b>: <code>3.0</code> is not an integer and <code>5</code> is not a float, the dot matters.
</p>
<p>
Strings might be surrounded by double or single quotes. In both cases, you can escape the quote you're using: <code>"He said: \"Hello, you\"."</code> is valid but <code>'He said: "Hello, you".'</code> is equivalent and nicer.
</p>
<p>
Also, you can include variables in a string using the <code>#{...}</code>
syntax:
<code>"foo #{quote(my_var)} bar"</code> is equivalent to
<code>"foo " ^ quote(my_var) ^ " bar"</code>.
</p>
<h4>Expressions</h4>
<p>
You can form expressions by using:
</p>
<ul>
<li>
Constants and variable identifiers. Identifiers start with an alphabetic character or an underscore, followed by alphanumerics, underscores, dots and quotes: <code>[A-Z a-z _][A-Z a-z 0-9 _.']*</code>.</li>
<li>
Lists and pairs: <code>[expr,expr,...]</code> and <code>(expr,expr)</code>.</li>
<li>
Comparison of values is done using <code>expr == expr</code> and its negation is <code>expr != expr</code>. Most other usual operations are available, allowing usual things like <code>1+1 < 11</code>.</li>
<li>
Application <code>f(x,y)</code> of arguments to a function. Application of labeled parameters is as follows: <code>f(x,foo=1,y,bar="baz")</code>. The interest of labels is that the order of two parameters doesn't matter as long as they have different labels.</li>
<li>
Anonymous functions: <code>fun (arglist) -> expr</code>. Some arguments might have a label or an optional value. For example, the definition of a function with two named parameters, the second one being optional with default value <code>13</code> is as follows: <code>fun (~foo,~bar=13) -> ...</code>.</li>
<li>
Definitions using def-end: <code>def pi = 3.14 end</code> defining a ground value, <code>def source(x) = wrap2(wrap1(x)) end</code> defining a function. The <code>=</code> is optional, you may prefer multi-line definitions without it. The arguments of a defined function are specified in the same way as for anonymous functions.</li>
<li>
Shorter definitions using the equality: <code>pi = 3.14</code>. This is never an assignment, only a new local definition!</li>
<li>
Conditionals <code>if expr then expr else expr end</code>, or more generally <code>if expr then expr (elsif expr then expr)* (else expr)? end</code>. The <code>else</code> block can be omitted if the purpose of the conditional is not to compute a value (<em>e.g.</em> an integer or a list of strings) but only to have a side effect (<em>e.g.</em> printing something in one case, not doing anything in the other).</li>
<li>
Sequencing: expressions may be sequenced, just juxtapose them. Usually one puts one expression per line. Optionally, they can be separated by a semicolon. The evaluation of a sequence triggers that of all of its sub-expressions, its value is that of the last sub-expression. Accordingly, the type of a sequence is that of its last sub-expression.</li>
<li>
Parenthesis can be used to delimit explicitly expressions. In some places where only expressions can be written, as opposed to sequences of expressions, the <code>begin .. end</code> block can be used to explicitly form a simple expression from a sequence. This notably happens with the simple form of definitions without <code>def .. end</code>, and in the body of anonymous functions. For example <code>fun (x) -> f1(x) ; f2(x)</code> will be read as <code>(fun (x) -> f1(x)) ; f2(x)</code> not as <code>fun (x) -> begin f1(x) ; f2(x) end</code>.</li>
<li>
Code blocks: <code>{ expr }</code> is a shortcut for <code>fun () -> expr</code>.</li>
</ul>
<p>
<b>No assignation, only definitions.</b> <code>x = expr</code> doesn't modify <code>x</code>, it just defines a new <code>x</code>. The expression <code>(x = s1 ; def y = x = s2 ; (x,s3) end ; (y,x))</code> evaluates to <code>((s2,s3),s1)</code>.
</p>
<p>
<b>Function.</b> The return value of a function is the evaluation of its body where parameters have been substituted by their values. Accordingly, the type of the body is the return type of the function. If the body is a sequence, the return value will thus be its last expression, and the return type its type.
</p>
<pre class="syntax liq">def foo ()
a = bar()
b = 1
"string"
end
# The return type of foo is string.
# The full type of foo is ()->string.
</pre>
<div align="right">
<a href="scripts/lang_func_type.liq">
<img class="grab" src="./images/grab.png" alt="Grab the code!">
</a>
</div></p>
<p>
<b>Type of an application.</b> The type of an application is the return type of function if all mandatory arguments are applied. With the function <code>foo</code> previously defined, <code>foo()</code> is a string. Otherwise, the application is “partial”, and the expression still has a function type.
</p>
<p>
<b>Partial application.</b> Application of arguments can be partial. For example if <code>f</code> takes two integer arguments, <code>f(3)</code> is the function waiting for the second argument. This can be useful to instantiate once for all dummy parameters of a function:
</p>
<pre class="syntax liq">out = output.icecast(%vorbis, host="streamer",port="8080",
password="sesame")
# out is a function waiting for the other parameters
out(bitrate=112, my_radio)
</pre>
<div align="right">
<a href="scripts/lang_partial_application.liq">
<img class="grab" src="./images/grab.png" alt="Grab the code!">
</a>
</div></p>
<p>
<b>Labels.</b> Labeled and unlabeled parameters can be given at any place in an application. The order of the arguments is up to permutation of arguments of distinct labels. For example <code>f(x,foo=1)</code> is the same as <code>f(foo=1,x)</code>, both are valid for any function <code>f(x,~foo,...)</code>. It makes things easier for the user, and gives its full power to the partial application.
</p>
<p>
<b>Optional arguments.</b> Functions can be defined with an optional value for some parameter (as in <code>def f(x="bla",~foo=1) = ... end</code>), in which case it is not required to apply any argument on the label <code>foo</code>. The evaluation of the function is triggered after the first application which instantiated all mandatory parameters.
</p>
<h4>Types</h4>
<p>
We believe in static typing especially for a script which is intended to run during weeks: we don't want to notice a mistake only when the special code for your rare live events is triggered! Moreover, we find it important to show that even for a simple script language like that, it is worth implementing type inference. It's not that hard, and makes life easier.
</p>
<p>
The basic types are <code>int</code>, <code>float</code>, <code>bool</code>
and <code>string</code>.
Corresponding to pairs and lists,
you get <code>(T*T)</code> and <code>[T]</code> types –
all elements of a list should have the same type.
For example, <code>[(1,"un"),(2,"deux")]</code>
has type <code>[(int*string)]</code>.
</p>
<p>
There are several types that are specific to liquidsoap, such as
<code>source</code>, <code>request</code>, <code>format</code>.
Those three types are parametrized by the kind of stream that they
carry. This is described in more details in a
<a href="stream_content.html">dedicated page</a>.
</p>
<p>
A function type is noted as <code>(arg_types) -> return_type</code>. Labeled arguments are denoted as <code>~label:T</code> or <code>?label:T</code> for optional arguments. For example the following function has type <code>(source,source,?jingle:string) -> source</code>.
</p>
<pre class="syntax liq">fun (from,to,~jingle=default) ->
add ([ sequence([single(jingle), fallback([])]),
fade.initial(to) ])
</pre>
<div align="right">
<a href="scripts/lang_fun_def.liq">
<img class="grab" src="./images/grab.png" alt="Grab the code!">
</a>
</div></p>
<h4>Time intervals</h4>
<p>
The scripting language also has a syntax extension for simply specifying time intervals.
</p>
<p>
A date can be specified as <code>_w_h_m_s</code> where <code>_</code> are integers. It has the following meaning:
</p>
<ul>
<li>
<code>w</code> stands for weekday, ranging from 0 to 7, where 1 is monday, and sunday is both 0 and 7.</li>
<li>
<code>h</code> stands for hours, ranging from 0 to 23.</li>
<li>
<code>m</code> stands for minutes, from 0 to 59.</li>
<li>
<code>s</code> stands for seconds, from 0 to 59.</li>
</ul>
<p>
All components <code>w</code>, <code>h</code>, <code>m</code> and <code>s</code> are optional. Finally, the <code>m</code> can be omitted in dates of the form <code>_h_</code> such as <code>12h30</code>.
</p>
<p>
It is possible to use 24 (resp. 60) as the upper bound for hours (resp. seconds or minutes) in an interval, for example in <code>12h-24h</code>.
</p>
<p>
Time intervals can be either of the form <code>DATE-DATE</code> or simply <code>DATE</code>. Their meaning should be intuitive: <code>10h-10h30</code> is valid everyday between 10:00 and 10:30; <code>0m</code> is valid during the first minute of every hour.
</p>
<p>
This is typically used for specifying switch predicates:
</p>
<pre class="syntax liq">switch([
({ 20h-22h30 }, prime_time),
({ 1w }, monday_source),
({ (6w or 7w) and 0h-12h }, week_ends_mornings),
({ true }, default_source)
])
</pre>
<div align="right">
<a href="scripts/switch_generic.liq">
<img class="grab" src="./images/grab.png" alt="Grab the code!">
</a>
</div></p>
<h4>Includes</h4>
<p>
You can include other files,
to compose complex configurations from
multiple blocks of utility or configuration directives.
</p>
<pre class="syntax "># Store passwords in another configuration file,
# so that the main config can be safely version-controlled.
%include "passwords.liq"
# Use the definitions from the other file here.
</pre>
<p>
In the command <code>%include "file"</code> the path is relative to
the script file. In <code>%include <file></code>, it is relative
to the library directory of liquidsoap.
</p>
</div></div>
<div>
<div id="footer"> 2003-2013 Savonet team</div>
</div>
</div>
</body></html>
|