<?xml version="1.0" ?>
<?xml-stylesheet type="text/xsl" href="ref_to_html.xsl" ?>

<reference>

	<types>
		<type name="number">
			<example>1</example>
			<description>Only integers are supported so far. A number may be expressed by
			simply entering it without any special annotation</description>
		</type>
		<type name="string">
			<example>&#34;hello world&#34;</example>
			<description>Strings are entered by enclosing them in quotes</description>
		</type>
		<type name="symbol">
			<example>my_symbol</example>
			<description>A symbol is an identifier in uLISP. It must not contain any spaces,
			tabs or new line charachters</description>
		</type>
		<type name="sequence">
			<example>(1 2 3 4)</example>
			<description>Sequences are linked lists which are used to represent the code itself
			but may also be used as a data structure. A sequence can be created using the seq
			function</description>
		</type>
		<type name="lambda">
			<example>(L (a b) (+ a b))</example>
			<description>The classic lambda calculus (or anonmymous function). They're first
			class datatypes in uLISP</description>
		</type>
		<type name="nil">
			<example>(def a nil)</example>
			<description>Represents an empty value (eq nothing)</description>
		</type>
	</types>
	
	<functions>
		<function name="define">
			<parameters>name value</parameters>
			<example>(define truth 42)</example>
			<description>Binds the given value to the name (with respect of the scoping).
			May also be used in conjunction with lambdas</description>
		</function>
		<function name="def" alias="define" />
		<function name="lambda">
			<parameters>(param1 param2 ...) expr1 expr2 ...</parameters>
			<example>(lambda (a b) (+ a b 5))</example>
			<description>Classic lambda calculus. You may specify an arbitrary number of
			expressions. The return value of the last expression is the return value of the
			lambda</description>
		</function>
		<function name="L" alias="lambda" />
		<function name="recur">
			<parameters>(param1 param2 ...)</parameters>
			<example>(lambda (a b) (+ a b 5) (if (== b 0) a (recur a (- b 1))))</example>
			<description>Recalls the current lambda with the passed parameters. This construct
			allows recursion (and thereby some sort of looping). If recur is called outside of
			a lambda it has no effect</description>
		</function>
		<function name="t">
			<parameters />
			<example>t</example>
			<description>Returns itself as a symbol</description>
		</function>
		<function name="quote">
			<parameters>expr1 expr2 ...</parameters>
			<example>(quote (+ 1 2) 3 4)</example>
			<description>Simply returns the given expressions (unevaluated)</description>
		</function>
		<function name="'" alias="quote" />
		<function name="let">
			<parameters>(symbol1 value1 symbol2 value2 ...) expr1 expr2 ...</parameters>
			<example>(let (a 1 b 2) (println a) (println b) (println (+ a b)))</example>
			<description>Temporarily binds the values to the symbols (similiar to define).
			But this binding is only visibile with the let expression, thereby enclosing
			the scope of the definition</description>
		</function>
		<function name="first">
			<parameters>sequence</parameters>
			<example>(first (seq 1 2 3))</example>
			<description>Returns the first element of a sequence (as in the example that would
			be 1)</description>
		</function>
		<function name="car" alias="first" />
		<function name="rest">
			<parameters>sequence</parameters>
			<example>(rest (seq 1 2 3))</example>
			<description>Returns the given sequence without the first element (in the example: 2 3)
			</description>
		</function>
		<function name="cdr" alias="rest" />
		<function name="seq">
			<parameters>value1 value2 ...</parameters>
			<example>(seq (+ 1 2) 3 4)</example>
			<description>Turns the given values into a sequence which makes sequences usable
			as a data structure</description>
		</function>
		<function name="range">
			<parameters>upperLimit</parameters>
			<example>(range 100)</example>
			<description>Creates a sequence containing the values from 0 .. upperLimit</description>
		</function>
		<function name="println">
			<parameters>value1 value2 ...</parameters>
			<example>(println &#34;hello world&#34;)</example>
			<description>Prints the given values to the standard output adding a new line
			at the end</description>
		</function>
		<function name="str">
			<parameters>value1 value2 ...</parameters>
			<example>(str "result: " (+ 1 2))</example>
			<description>Concatenates several values and turns them into one single string
			</description>
		</function>
		<function name="+">
			<parameters>num1 num2 ...</parameters>
			<example>(+ 1 2 3)</example>
			<description>Sums up the given numbers</description>
		</function>
		<function name="-">
			<parameters>num1 num2 ...</parameters>
			<example>(- 42 2 30)</example>
			<description>Substracts num2 .. numn from num1</description>
		</function>
		<function name="*">
			<parameters>num1 num2 ...</parameters>
			<example>(* 2 21)</example>
			<description>Multiplies the given numbers</description>
		</function>
		<function name="if">
			<parameters>(cond) (then) (else)</parameters>
			<example>(if (== 22 23) (println &#34;can't happen&#34;) (println &#34;yipee&#34;))</example>
			<description>Evaluates the condition. If that evaluates to true the (then) expression
			is evaluated. If cond becoms false, the (else) expression is executed</description>
		</function>
		<function name="==">
			<parameters>value1 value2 ...</parameters>
			<example>(== 1 a b)</example>
			<description>Tests if the given values are equal (or identical to be more precise).
			This test is only declared for numbers and strings</description>
		</function>
		<function name="true">
			<parameters />
			<example>(if true &#34;yipee&#34; &#34;oh no&#34;)</example>
			<description>Always evaluates to true</description>
		</function>
		<function name="false">
			<parameters />
			<example>(if false &#34;oh no&#34; &#34;yipee&#34;)</example>
			<description></description>
		</function>
		<function name="nil">
			<parameters />
			<example>(def x nil)</example>
			<description>Represents null, nil, nothing</description>
		</function>
	</functions>

</reference>
