multipattern

A class containing a collection of pattern objects. Many pattern operations generate a set of patterns. This class aims to provide a convenient collection with some common methods for handling them.

Fields

Name	Type	Description
components	forma.pattern[]	the list of sub-patterns

multipattern.new

Create a new multipattern from a list of patterns.

local mp = multipattern.new()
local mp2 = multipattern.new({p1, p2, p3})

Parameters:

Name	Type	Description
components	forma.pattern[]?	an array of pattern objects

Returns:

• forma.multipattern — a new multipattern containing those patterns

multipattern.clone

Clone the multipattern.

Parameters:

Name	Type	Description
mp	forma.multipattern	multipattern to clone

Returns:

• forma.multipattern — the cloned multipattern

multipattern.merge

Merge multipatterns.

Parameters:

Name	Type	Description
``	forma.multipattern	a table of multipatterns or a list of multipattern arguments

Returns:

• forma.multipattern — a new multipattern consisting of the set of all input components

multipattern.insert

Insert a pattern into the multipattern.

Parameters:

Name	Type	Description
mp	forma.multipattern	multipattern to be operated upon
ip	forma.pattern	the new pattern to insert

Returns:

• forma.multipattern — the multipattern

multipattern.n_components

Count the number of components in a multipattern.

Parameters:

Name	Type	Description
mp	forma.multipattern	the multipattern to count

Returns:

• integer — the number of components

multipattern.map

Map a function over all patterns in this multipattern. Calls fn(pattern, index) for each sub-pattern, returning a new multipattern of their results.

local bigger = mp:map(function(p) return p:enlarge(2) end)

Parameters:

Name	Type	Description
mp	forma.multipattern	the multipattern upon which to map the function
fn	fun(p: forma.pattern, i: integer):forma.pattern	a function taking (pattern, index) and returning a new pattern

Returns:

• forma.multipattern — a new multipattern of the mapped results

multipattern.filter

Filter out sub-patterns according to a predicate. Keeps only those patterns for which predicate(pattern) == true.

local bigSegs = mp:filter(function(p) return p:size() >= 10 end)

Parameters:

Name	Type	Description
mp	forma.multipattern	the multipattern upon which to filter
fn	fun(p: forma.pattern):boolean	a predicate function

Returns:

• forma.multipattern — a new multipattern containing only the sub-patterns passing the test

multipattern.apply

Apply a named method to each pattern, returning a new multipattern. This is an alternative to :map(...) for calling an existing pattern method by name on all sub-patterns. You may also supply arguments to that method.

Note that when used with a method that generates multipatterns (e.g. connected_components), the results will be 'flattened' into a single multipattern.

local translated = mp:apply("translate", 10, 5)
-- calls p:translate(10,5) on each pattern p

Parameters:

Name	Type	Description
mp	forma.multipattern	the multipattern upon which to apply the method
method	string	the name of a function in pattern
``	any	additional arguments to pass to that method

Returns:

• forma.multipattern — a new multipattern of the method's results

multipattern.union_all

Union all sub-patterns into a single pattern. Folds over the sub-patterns with the union (+) operator, returning a single pattern.

local combined = mp:union_all()

Parameters:

Name	Type	Description
mp	forma.multipattern	the multipattern to union over

Returns:

• forma.pattern — a single pattern combining all sub-patterns

multipattern.print

Print a multipattern. Prints a multipattern to io.output. If provided, a table of subpattern labels can be used, with one entry per subpattern.

Parameters:

Name	Type	Description
mp	forma.multipattern	the multipattern to be drawn
chars	string[]?	the characters to be printed for each subpattern
domain	(forma.pattern)?	the domain in which to print