update pattern.lua

- add examples to all public functions
- allow function generators in `new` for initial values
- fixed `empty_value` handling
- remove `add` alias to `push_back`

Author: emuell

types/nerdo/library/pattern.lua

@@ -34,10 +34,12 @@ local empty_pulse_values = {
 ---pattern.from{ 1, 0.5, 1, 1 }:euclidean(12)
 ----- generate/init from functions
 ---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" }
----pattern.from{ 1, 5, 6, 4 }:map(function(index, degree) 
----  return scale("c", "minor"):chord(degree) 
+----- generate chord patterns
+---pattern.from{ 1, 5, 6, 4 }:map(function(index, degree)
+---  return scale("c", "minor"):chord(degree)
 ---end)
 ---```
 ---@class Pattern : table
@@ -50,17 +52,17 @@ pattern = {}
 ----------------------------------------------------------------------------------------------------
 
 ---Create a new empty pattern or pattern with the given length.
----@param length integer?
----@param value PulseValue? Value used as initial value when length > 0. by default 0.
+---@param length integer? Initial length of the pattern. When undefined, an empty pattern is created.
+---@param value (PulseValue|(fun(index: integer):PulseValue))? Value or generator function, which sets the initial values in the pattern.
 ---@return Pattern
 ---@nodiscard
 function pattern.new(length, value)
   local t = setmetatable({}, {
-    ---all table functions can be accessed as member functions
+    ---all pattern functions can be accessed as member functions
     __index = pattern,
     ---operator + adds two patterns
     __add = function(a, b)
-      return a:copy():add(b)
+      return a:copy():push_back(b)
     end,
     ---operator * creates a repeated pattern
     __mul = function(a, b)
@@ -70,15 +72,19 @@ function pattern.new(length, value)
   -- initialize
   if length ~= nil then
     value = value or 0
-    for _ = 1, length do
-      table.insert(t, value)
-    end
+    t:init(value, length)
   end
   return t
 end
 
 ---Create a new pattern from a set of values or tables.
 ---When passing tables, those will be flattened.
+---
+---### examples:
+---```lua
+---local p = pattern.from(1,0,1,0) -- {1,0,1,0} 
+---p = pattern.from({1,0},{1,0}) -- {1,0,1,0} 
+---```
 ---@param ... PulseValue|(PulseValue[])
 ---@return Pattern
 ---@nodiscard
@@ -87,19 +93,27 @@ function pattern.from(...)
 end
 
 -- create a shallow-copy of the given pattern (or self)
+---
+---### examples:
+---```lua
+---local p = pattern.from(1, 0)
+---local p2 = p:copy() --- {1,0}
+---```
 ---@return Pattern
 ---@nodiscard
 function pattern.copy(self)
   return pattern.from(self:unpack())
 end
 
----Create an new pattern or spread and existing pattern evenly within the given length,
----using Bresenham’s line algorithm. Similar, but not exactly like "euclidean".
+---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)`
 ---
----Shortcut for:
+---### examples:
 ---```lua
----pattern.new(1, steps):spread(length / steps):rotate(offset) -- or
----pattern.from{1,1,1}:spread(length / #self):rotate(offset)
+---local p = pattern.distributed(3, 8) --- {1,0,0,1,0,1,0}
+---p = pattern.from{1,1}:distributed(4, 1) --- {0,1,0,1}
 ---```
 ---@param steps table|integer Existing pattern or number of on steps in the pattern.
 ---@param length integer Number of total steps in the pattern.
@@ -164,6 +178,12 @@ end
 ---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](https://en.wikipedia.org/wiki/Euclidean_rhythm)
+---
+---### examples:
+---```lua
+---local p = pattern.euclidean(3, 8) -- {1,0,0,1,0,0,1,0} 
+---p = pattern.from{"x", "x", "x"}:euclidean(8, 0, "-") -- {"x","-","-","x","-","-","x","-"} 
+---```
 ---@param steps table|integer Existing pattern or number of on steps in the pattern.
 ---@param length integer Number of total steps in the pattern.
 ---@param offset integer? Optional rotation offset.
@@ -186,7 +206,7 @@ function pattern.euclidean(steps, length, offset, empty_value)
     "invalid length argument (expecting an integer > 0)")
   assert(type(offset) == "number" or offset == nil,
     "invalid offset argument (must be an integer or nil)")
-  empty_value = empty_value == nil and empty_pulse_value(steps) or 0
+  empty_value = empty_value or empty_pulse_value(steps)
   if #front == 0 then
     local result = pattern.new();
     for _ = 1, length do
@@ -224,6 +244,12 @@ end
 ----------------------------------------------------------------------------------------------------
 
 ---Shortcut for table.unpack(pattern): returns elements from this pattern as var args.
+---
+---### examples:
+---```lua
+---local p = pattern.from{1,2,3,4}
+---local v1, v2, v3, v4 = p:unpack()
+---```
 ---@return (PulseValue)[]
 ---@nodiscard
 function pattern.unpack(self)
@@ -232,6 +258,13 @@ end
 
 ---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:
+---```lua
+---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"}
+---```
 ---@param i integer Subrange start
 ---@param j integer? Subrange end (defaults to pattern length)
 ---@param empty_value PulseValue? Value used as empty value (by default 0 or guessed from existing content).
@@ -242,26 +275,41 @@ function pattern.subrange(self, i, j, empty_value)
     "invalid subrange end argument (must be an integer > 0)")
   local len = j or #self
   local a = pattern.new()
-  empty_value = empty_value == nil and empty_pulse_value(self) or 0
+  empty_value = empty_value or empty_pulse_value(self)
   for ii = i, len do
     a:push_back(self[ii] or empty_value)
   end
   return a
 end
 
 ---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:
+---```lua
+---local p = pattern.from{1,2,3,4}
+---p = p:take(2) -- {1,2}
+---p = p:take(4, "") -- {1,2,"",""}
+---```
 ---@param length integer
-function pattern.take(self, length)
+---@param empty_value PulseValue? Value used as empty value (by default 0 or guessed from existing content).
+function pattern.take(self, length, empty_value)
   assert(type(length) == "number" and length > 0,
     "invalid length argument (must be an integer > 0)")
-  return self:subrange(1, length)
+  return self:subrange(1, length, empty_value)
 end
 
 ----------------------------------------------------------------------------------------------------
 --- Modify contents
 ----------------------------------------------------------------------------------------------------
 
 ---Clear a pattern, remove all its contents.
+---
+---### examples:
+---```lua
+---local p = pattern.from{0,0}
+---p:clear() -- {}
+---```
 function pattern.clear(self)
   while #self > 0 do
     table.remove(self)
@@ -270,6 +318,13 @@ function pattern.clear(self)
 end
 
 ---Fill pattern with the given value or generator function in length.
+---
+---### examples:
+---```lua
+---local p = pattern.from{0,0}
+---p:init(1) -- {1,1}
+---p:init("X", 3) -- {"X","X", "X"}
+---```
 ---@param value PulseValue|fun(index: integer):PulseValue
 ---@param length integer?
 function pattern.init(self, value, length)
@@ -292,6 +347,14 @@ function pattern.init(self, value, length)
 end
 
 ---Apply the given function to every item in the pattern.
+---
+---### examples:
+---```lua
+---local p = pattern.from{1,3,5}
+---p:map(function(k, v) 
+---  return scale("c", "minor"):degree(v)
+---end) -- {48, 51, 55}
+---```
 ---@param fun fun(index: integer, value: PulseValue): PulseValue
 function pattern.map(self, fun)
   local num = #self
@@ -302,6 +365,12 @@ function pattern.map(self, fun)
 end
 
 ---Invert the order of items.
+---
+---### examples:
+---```lua
+---local p = pattern.from{1,2,3}
+---p:reverse() -- {3,2,1}
+---```
 function pattern.reverse(self)
   local num = #self
   for i = 1, math.floor(num / 2) do
@@ -312,6 +381,13 @@ function pattern.reverse(self)
 end
 
 ---Shift contents by the given amount to the left (negative amount) or right.
+---
+---### examples:
+---```lua
+---local p = pattern.from{1,0,0}
+---p:rotate(1) -- {0,1,0}
+---p:rotate(-2) -- {0,0,1}
+---```
 ---@param amount integer
 function pattern.rotate(self, amount)
   assert(type(amount) == "number",
@@ -332,8 +408,17 @@ end
 --- Add/remove contents
 ----------------------------------------------------------------------------------------------------
 
----Push any number of items or other pattern contents to the end of the pattern.
----When passing array alike tables or patterns, they will be unpacked.
+---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:
+---```lua
+---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}
+---```
 ---@param ... PulseValue|(PulseValue)[]
 function pattern.push_back(self, ...)
   local function add_unpacked(v)
@@ -348,23 +433,34 @@ function pattern.push_back(self, ...)
     end
   end
   local len = select("#", ...)
-  for i = 1,len  do
+  for i = 1, len do
     local v = select(i, ...)
     add_unpacked(v)
   end
   return self
 end
 
----Alias for pattern.push_back.
-pattern.add = pattern.push_back
-
----Remove an entry from the back of the pattern and returns the popped item.
+---Remove an entry from the back of the pattern. returns the popped item.
+---
+---### examples:
+---```lua
+---local p = pattern.from({1,2})
+---p:pop_back() -- {1}
+---p:pop_back() -- {}
+---p:pop_back() -- {}
+---```
 ---@return PulseValue
 function pattern.pop_back(self)
   return table.remove(self)
 end
 
 ---Duplicate the pattern n times.
+---
+---### examples:
+---```lua
+---local p = pattern.from{1,2,3}
+---patterns:repeat_n(2) -- {1,2,3,1,2,3}
+---```
 ---@param count integer
 function pattern.repeat_n(self, count)
   assert(type(count) == "number" and count > 0,
@@ -381,17 +477,28 @@ end
 ---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:
+---```lua
+---local p = pattern.from{1,1}
+---p:spread(2) -- {1,0,1,0}
+---p:spread(0.5) -- {1,1}
+---```
 ---@param amount number Spread factor (2 = double, 0.5 = half the size).
 ---@param empty_value PulseValue? Value used as empty value (by default 0 or guessed from existing content).
 function pattern.spread(self, amount, empty_value)
   assert(type(amount) == "number" and amount > 0,
     "invalid amount argument (must be an integer > 0)")
-  empty_value = empty_value == nil and empty_pulse_value(self) or 0
+  empty_value = empty_value or empty_pulse_value(self)
   local old_num = #self
+  local new_num = math.floor(old_num * amount + 0.5)
   local old = self:copy()
-  self:init(empty_value, old_num * amount)
+  self:init(empty_value, new_num)
   for i = 1, old_num do
-    self[math.floor((i - 1) * amount + 0.5) + 1] = old[i]
+    local j = math.floor((i - 1) * amount + 0.5) + 1
+    if j <= new_num then
+      self[j] = old[i]
+    end
   end
   return self
 end