Transforms

The transforms library is set of utilities for working with indexed tables. It provides highly reusable special iterators that are at the core of text and sh command parsing.

All transforms methods expect to iterate over sequences (a.k.a lists, or arrays).

All first and last arguments act in the same fashion as the first and last arguments used in string methods such as string.sub. That is, it accepts negative values, which work relative from the end. first defaults to 1, and last defaults to -1.

• transforms.sub(tbl: table, first: number, last: number or nil): table

  Behaves similarly to string.sub. Returns a sub table of tbl from first to last.

• transforms.first(tbl: table, predicate: function or table, first: number or nil, last: number or nil): number, number

  Returns the first index in tbl (between indexes first and last, inclusively) where predicate is satisfied. The 2nd return is also the ending index of the match. General examples will have the same two values, i.e. a match of 1. Technically, the predicate can return a 2nd return value to indicate where the pattern matching completed.
  Note the predicate signature

• predicate(element: any, index: number, tbl: table): any, number

  The predicate is called on each index. A falsely return means the predicate failed. A predicate generally returns true when element matches what is looked for. But the implementation of the predicate can choose to search later in tbl from index. The predicate can also choose to return the size of the match (for example it can return 1 is only 1 element matched, or return 2 if tbl[i+1] was also used to satisfy the predicate). transforms.find will then use the size returned in the range it returns.
  example:

snippet.lua

local tx = require("transforms")
print( tx.first ( { 1, 1, 3, 2, 4, 7 }, function(e, i, tbl)
  local evens = 0
  for i=i,#tbl do
    if tbl[i] % 2 == 0 then
      evens = evens + 1
    else
      break
    end
  end
  return evens > 0, evens
end))

Result: 4 5

• 'transformas.partition'
• 'transformas.begins'
• 'transforms.foreach' or 'transforms.select'
• 'transforms.where'
• 'transforms.at'