3. Function Builders.md

Function Builders

The library contains several function builders contained in the functions object with shortcuts to them on the library index object.
Below, all functions to refer to one in the functions object, with the shortcut noted.

Matching Case By Case

• cases()

Creates a new cases function.
A new case branch can be added with one of the following on the cases() object:

• case(patterns, callback)
• caseGuarded(patterns, predicate, callback)

The predicate will take the extracted object and will return a boolean for whether the extracted values passed.
The callback will take the extracted object and can return anything.

Once all cases are added, the cases() object itself can be called with a value to match.
It will match the given value through all the cases until one is found and runs its callback.
If no case matches, an error is thrown.

The shortcut functions case and caseGuarded on the library index is a shortcut to cases().case and cases().caseGuarded.

pat
    .case(1, () => 1)
    .case(2, () => 2)
    .case(3, () => 3)(3)
→ 3

pat
    .caseGuarded($.x, ({ x }) => x.length >= 3, () => true)
    .case(_, () => false)([1, 2])
→ false

Function with Clauses

• clauses()

Creates a new clauses function.
A new clause branch can be added with one of the following on the clauses() object:

• clause(...patterns, callback)
• clauseGuarded(...patterns, predicate, callback)

Here, patterns are every argument except the last ones, to be passed into Pattern.patternOfArray, and corresponds to passed-in arguments.
The predicate will take the extracted object and will return a boolean for whether the extracted values passed.
The callback will take the extracted object and can return anything.

Once all clauses are added, the clauses() object itself can be called with a parameter list.
It will match the arguments through all the clauses until one is found and runs its callback.
If no clause matches, an error is thrown.

The shortcut functions clause and clauseGuarded on the library index is a shortcut to clauses().clause and clauses().clauseGuarded.

const fn = pat
    .clause($.x, ({ x }) => fn(x, 1))
    .clause($.x, $.y, ({ x, y }) => x + y)
    .clause([rest, $.xs], ({ xs }) => xs.reduce((a, b) => a + b), 0);

fn(5)
→ 6

fn(3, 4)
→ 7

fn(1, 2, 3, 4)
→ 10

Test Match

• tester(pattern)

Creates a new test function.
The return of tester(pattern) can then be called on a value to test if it matches.
A pattern extending Pattern can also use Pattern#test(value).

The shortcut function test(pattern, value) on the library index is a shortcut to tester(pattern)(value).

pat.test({ x: 5 }, { x: 1 })
→ false

pat.test({ x: 5 }, { x: 5 })
→ true

Get Match

• matcher(pattern)

Creates a new match function.
The return of matcher(pattern) can then be called on a value to get the extracted object if it matched, otherwise null.
A pattern extending Pattern can also use Pattern#match(value).

The shortcut function match(pattern, value) on the library index is a shortcut to matcher(pattern)(value).

pat.match({ x: $.x }, { x: 1 })
→ { x: 1 }

pat.match({ x: $.x }, { y: 5 })
→ null