# 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
~~~
[arguments]
~~~

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 name specification
~~~
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
~~~
(elements)
~~~

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
~~~

# 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
~~~

# extended backus-naur form
~~~
identifier     = letter , { letter | digit } ;
name           = identifier ;
slash          = "/" ;
colon          = ":" ;
ellipsis       = "..." ;
arrow          = "->" ;
double_colon   = "::" ;
space          = " " ;
newline        = "\n" ;
input          = { element } ;
output         = { element } ;
element        = argument | list | association | function_signature | alternatives | repetition | optional_arguments ;
argument       = identifier ;
list           = "(" , { element , space } , ")" ;
association    = "{" , element , arrow , element , "}" ;
function_signature = "{" , { element , arrow } , element , "}" ;
alternatives   = element , { slash , element } ;
repetition     = element , ellipsis ;
optional_arguments = "[" , { element , space } , "]" ;
function_name_spec = name , space , double_colon , space , input , arrow , output ;
multiline_signature = double_colon , newline , { input } , newline , arrow , newline , output ;
signature       = function_name_spec | multiline_signature ;
~~~

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