# function type signature notation
machine-readable function type signature syntax

# definition
## input and output separation
~~~
input -> output
~~~

inputs and outputs are separated by `->`.

## multiple arguments
~~~
element1 element2 ...
~~~

multiple arguments are separated by a single space ` `.

~~~
a b c -> d
~~~

## alternative data types
~~~
element1/element2/...
~~~

alternative data types are separated by a slash `/`.

~~~
a b/c/d -> e
a port/string/integer -> e
~~~

## alternative names
~~~
data-type:alias1:alias2
~~~

alternative names for a data type are separated by a colon `:`. data types always come first.

~~~
a b:c:d -> e
a port:input-port:source -> e
~~~

## optional arguments
~~~
[argument ...]
~~~

optional arguments are enclosed in square brackets `[]`.

~~~
a [b c] -> d
~~~

## repetition
~~~
element ...
~~~

indicates none or many consecutive occurrences of an element. use a space followed by three dots `...`.

~~~
a b ... c ... -> d
~~~

## function names
~~~
name :: arguments -> result
~~~

function names are specified by writing the identifier followed by a space and two colons ` :: `.

~~~
name :: a b -> c
~~~

## functions and dictionaries
~~~
{signature}
~~~

function signatures can be enclosed within curly brackets `{}` to represent functions or dictionaries. nesting is allowed.

~~~
{a ->}
function:{a ... -> list:b}
hashtable:{key -> value}
~~~

## lists and arrays
~~~
(element ...)
~~~

lists and arrays are denoted using round brackets `()`.

~~~
(a (b c))
~~~

## associations
~~~
{key -> value}
~~~

associations are represented similarly to functions and dictionaries using curly brackets `{}`.

## multiline signatures
~~~
::
input1
input2
->
output
~~~

multiline signatures start with two colons :: followed by a newline. inputs and outputs are listed on separate lines, with `->` on a line by itself. the signature ends with the end of the string or two successive newline characters.

~~~
::
a
b
->
c

line outside of signature
~~~

# summary
~~~
signature: input " -> " output
multiple: element (" " element) ...
alternatives: element ("/" element) ...
names: type ":" alias ...
optional: "[" element ... "]"
repetition: element " " "..."
naming: name " :: " arguments "->" result
list: "(" element ... ")"
map_or_function: "{" key_or_input " -> " value_or_output "}"
~~~

# examples
list splitting function:
~~~
list any [symbol:exclusive/inclusive] -> (list:left list:right)
~~~

function transformation:
~~~
function:{any -> boolean} function:{list:matched-elements -> list:replacements} list:source -> list
~~~

complex multiline signature:
~~~
::
function:{alist:header function:fold-lines:{string:line any:result function:next:{any:result -> any} -> any} result -> any}
function:{header port result ->} any port [string]
->
any
~~~

# parsing
[sph-lib](../software/sph-lib.html) includes a reader and writer