Re: microlight review

[Dirk Laurie <dirk.laurie@...>]

Steve D responding to David M:

>> On my suggestion about merging ml.extend and ml.inject (and perhaps
>> even ml.delete, like splice), I see there was already some discussion
>
> The latest push does some renaming: 'inject' has become insertvalues
> and 'delete' has become removerange.

Easy enough to say e.g.
    local inject = ml.insertvalues
In such cases Microlight should prefer long but descriptive
to snappy but cryptic function names.

> I'm increasingly convinced that ml.update and ml.import are different
> functions (in fact, is import actually used?) As a temporary stand-by,
> update is a synonym for import.

Yes, without thinking about it, I always use the idiom

    require"ml".import()

> The 'thirty function' limit is arbitrary, of course.

There's a tradeoff between two extremes.  You can have a hundred
conflation-free functions like Python and need to remember which
of two almost synonymous English words like `extend` and `append`
is appropriate, or you can have one super-conflated function like
a typical GUI library and remain blissfully unaware of features you
never use.  The optimum is somewhere in between, which means that
you can't afford to be dogmatic about conflation.

Conflation is much more acceptable with table argument lists. E.g.
   import{journal,into=ledger}
   update{ledger,from=journal}
would do the same thing and confuse no reader.  Positional arguments
are efficient, sure, and reminiscent of the "good" old Fortran days,
true, but actually make for hard-to-find bugs in a language where
names don't imply types and missing arguments default to nil.

>
> I've put in memoize, which was part of Jay's original proposal.  I'm
> itching a little to add writefile as well as readfile, and there has
> been a request for a good trim function.

There has also been a suggestion, complete with proof-of-concept
implementation, for a wrap function.

> A design decision that needs review is that all functions returning
> arrays label them explicitly as Array objects.  It is trivial to give
> them a new identity but I'm wondering if this is a wise move for
> generic functions.

The less imposing-of-arbitrary-standards there is to Microlight's
class implementation, including Array, the more likely it is to
be acceptable to users.

On another issue:  One of the reasons why Python can get away with
a maze of twisty little passages, all alike, is the self-documenting
system.

If I can't remember which of `append` or `extend` adds several
values in one go, I can type `help(list.extend)` and find out.

Now implementing this for general user-defined functions with a
Python-style docstring belongs to Ilua, not to Microlight, but
implementing it for Microlight functions is trivial: you keep a
table with functions (not names) as keys.  E.g.

--- in ml.lua

local helptable={}

function ml.help(fn,noprint)
   local helptext=helptable[fn]
   if helptext==nil then
      local tfunc = type(fn)
      if tfunc~='function' then
         helptext="bad argument #1 to 'help' (function expected, got "
            ..tfunc..")"
      else helptext = "No help available for this function"
   end end
   if noprint then return helptext else print(helptext) end
end

helptable[ml.wrap]=[[
wrap(str,[length=72]) Returns a string in which some other whitespace
characters have been replaced by newline characters, so that the
distance between newline characters is close to `length`.]]

--- in the user's session

> require"ml".import()
> inject = insertvalues
> help(inject)
insertvalues(tbl,dest,index,src,overwrite) Copies values from `src` into
`dest` starting at `index`, moving up present values of `src` unless
`overwrite` tests `true`.]]

Dirk