Re: [ANN] Microlight 1.1

[David Manura <dm.lua@...>]

On Thu, Dec 27, 2012 at 12:55 PM, steve donovan
<steve.j.donovan@gmail.com> wrote:
> This is the first release candidate for the next iteration of
> Microlight [1].

A couple comments on only a quick look, assuming the meaning of the
functions should be clear from the documentation alone:

(1) ml.escape
  - How are "magic characters" and "escaping" defined?
string.match(s, '^'..ml.escape(s)..'$') == s for all s?

(2) ml.split
  - "split a string into a table of strings separated by a delimiter."
--> "split a delimited string into a table of strings."  (The table or
the strings in the table are not separated by a delimiter.)
  - "number of splits" unclear since splitting a string once yields
*two* parts (begin and end).
  - "table of strings" --> "array of strings"?  Compare to terminology
of "array" elsewhere.  Note: For better or worse, the 5.2 refman uses
"sequence."  Also, "a array" --> "an array" in many places.

(3) ml.expand
  - Is it obvious what $(1), $(true), and $(nil) should expand to?
(Note: In SLSLPP, the contents of $() is understood as an expression
not a name.)

(4) ml.readfile
  - no ml.writefile?  (See also lua-file-slurp.)
  - should docs mention that `nil,err` is returned on error?

(5) ml.tstring
  - "string representation" can be ambiguous in intended format.

(6) ml.collect_until(n, ...)
  - The word "until" suggests a variable number of iterations until a
predicate n is met, like "repeat ... until n".  Google
collect_until/collectUntil for examples.

(7) ml.imap
  - Note: This and other functions based on it operate in-place.

(8) ml.extend
  - Define "extend array" more formally?

(9) ml.indexby
  - Note: Equality in "indexby({one=1,two=2},{'one'}) == {1}" is
interpreted only informally.

(10) ml.ifind - Returns nil on not found?

(11) Mixing naming conventions?  equals_keys/equalskey v.s. issubset/is_subset?