pattern

Pattern

Array alike table with helper functions to ease creating rhythmic patterns.

examples:

-- using + and * operators to combine patterns
pattern.from{ 0, 1 } * 3 + { 1, 0 }

-- repeating, spreading and subsets
pattern.from{ 0, 1, { 1, 1 } }:repeat_n(4):spread(1.25):take(16)

-- euclidean patterns
pattern.euclidean(12, 16)
pattern.from{ 1, 0.5, 1, 1 }:euclidean(12)

-- generate/init from functions
pattern.new(8):init(1) --> 1,1,1,1,1,1,1,1
pattern.new(12):init(function() return math.random(0.5, 1.0) end )
pattern.new(16):init(scale("c", "minor").notes_iter())

-- generate note patterns
pattern.from{ "c4", "g4", "a4" } * 7 + { "a4", "g4", "c4" }

-- generate chords from degree values
pattern.from{ 1, 5, 6, 4 }:map(function(index, degree)
  return scale("c", "minor"):chord(degree)
end)

Functions

new(length : integer?, value : PulseValue | (index : integer) -> PulseValue?)

->Pattern

Create a new empty pattern or pattern with the given length and pulse value.

examples:

pattern.new(4,1) --> {1,1,1,1}
pattern.new(4, function() return math.random() end)

from(...PulseValue | PulseValue[])

->Pattern

Create a new pattern from an existing set of values or tables. When passing tables, those will be flattened.

examples:

pattern.from(1,0,1,0) --> {1,0,1,0}
pattern.from({1,0},{1,0}) --> {1,0,1,0}

copy(self : Pattern)

->Pattern

create a shallow-copy of the given pattern (or self)

examples:

local p = pattern.from(1, 0)
local p2 = p:copy() --> {1,0}

distributed(steps : integer | table, length : integer, offset : integer?, empty_value : PulseValue?)

->Pattern

Create an new pattern or spread and existing pattern evenly within the given length. Similar, but not exactly like euclidean.

Shortcut for pattern.from{1,1,1}:spread(length / #self):rotate(offset)

examples:

pattern.distributed(3, 8) --> {1,0,0,1,0,1,0}
pattern.from{1,1}:distributed(4, 1) --> {0,1,0,1}

euclidean(steps : integer | table, length : integer, offset : integer?, empty_value : PulseValue?)

->Pattern

Create a new euclidean rhythm pattern with the given pulses or number of new pulses in the given length and optionally rotate the contents. Euclidean Rhythm

examples:

pattern.euclidean(3, 8)
 --> {1,0,0,1,0,0,1,0}
pattern.from{"a", "b", "c"}:euclidean(8, 0, "-")
 --> {"a","-","-","b","-","-","c","-"}

unpack(self : Pattern)

->... : PulseValue

Shortcut for table.unpack(pattern): returns elements from this pattern as var args.

examples:

local p = pattern.from{1,2,3,4}
local v1, v2, v3, v4 = p:unpack()

subrange(self : Pattern, i : integer, j : integer?, empty_value : PulseValue?)

->Pattern

Get sub range from the pattern as new pattern. When the given length is past end of this pattern its filled up with empty values.

examples:

local p = pattern.from{1,2,3,4}
p = p:subrange(2,3) --> {2,3}
p = p:subrange(1,4,"X") --> {2,3,"X","X"}

take(self : Pattern, length : integer, empty_value : PulseValue?)

->Pattern

Get first n items from the pattern as new pattern. When the given length is past end of this pattern its filled up with empty values.

examples:

local p = pattern.from{1,2,3,4}
p = p:take(2) --> {1,2}
p = p:take(4, "") --> {1,2,"",""}

clear(self : Pattern)

->Pattern

Clear a pattern, remove all its contents.

examples:

local p = pattern.from{1,0}
p:clear() --> {}

init(self : Pattern, value : PulseValue | (index : integer) -> PulseValue, length : integer?)

->Pattern

Fill pattern with the given value or generator function in length.

examples:

local p = pattern.from{0,0}
p:init(1) --> {1,1}
p:init("X", 3) --> {"X","X", "X"}

map(self : Pattern, fun : (index : integer, value : PulseValue) -> PulseValue)

->Pattern

Apply the given function to every item in the pattern.

examples:

local p = pattern.from{1,3,5}
p:map(function(k, v)
  return scale("c", "minor"):degree(v)
end) --> {48, 51, 55}

reverse(self : Pattern)

->Pattern

Invert the order of items.

examples:

local p = pattern.from{1,2,3}
p:reverse() --> {3,2,1}

rotate(self : Pattern, amount : integer)

->Pattern

Shift contents by the given amount to the left (negative amount) or right.

examples:

local p = pattern.from{1,0,0}
p:rotate(1) --> {0,1,0}
p:rotate(-2) --> {0,0,1}

push_back(self : Pattern, ...PulseValue[] | PulseValue)

->Pattern

Push a single or multiple number of items or other pattern contents to the end of the pattern. Note: When passing array alike tables or patterns, they will be unpacked.

examples:

local p = pattern.new()
p:push_back(1) --> {1}
p:push_back(2,3) --> {1,2,3}
p:push_back{4} --> {1,2,3,4}
p:push_back({5,{6,7}) --> {1,2,3,4,5,6,7}

pop_back(self : Pattern)

->PulseValue

Remove an entry from the back of the pattern. returns the popped item.

examples:

local p = pattern.from({1,2})
p:pop_back() --> {1}
p:pop_back() --> {}
p:pop_back() --> {}

repeat_n(self : Pattern, count : integer)

->Pattern

Duplicate the pattern n times.

examples:

local p = pattern.from{1,2,3}
patterns:repeat_n(2) --> {1,2,3,1,2,3}

spread(self : Pattern, amount : number, empty_value : PulseValue?)

->Pattern

Expand (with amount > 1) or shrink (amount < 1) the length of the pattern by the given factor, spreading allowed content evenly and filling gaps with 0 or the given empty value.

examples:

local p = pattern.from{1,1}
p:spread(2) --> {1,0,1,0}
p:spread(1/2) --> {1,1}

tostring(self : Pattern)

->string

Serialze a pattern for display/debugging purposes.

examples:

pattern.euclidean(3, 8):tostring() --> "{1, 1, 1, 0}"

Aliases

PulseValue

boolean | string | number | table

Valid pulse value in a pattern