Writing Extensions

[Mark Wieder]

On 05/17/2017 12:09 AM, Ali Lloyd via use-livecode wrote:
> Mark, it would be lovely if you could be more specific. What parts of the
> docs in particular could be improved and how? What specific sticking points
> did you have?

Oh, where to start? Here are some thoughts off the top of my head:

Well, I'd love to have more parity between LCS and LCB as far as 
keywords and syntax, but I guess that's outside the scope of the 
documentation per se. But finding that constants like comma and quote 
aren't defined in LCB was a shock. Indeed, even defining a constant 
doesn't seem possible. Or at least it's not documented. Searching for 
"constant" gives nothing, even though "PiConstant" is in the dictionary.

I have no idea what the dictionary for ScriptObject is telling me. It 
has a link to MyScriptObject which has no useful information other than 
referring me back to ScripObject. The description "Use the resolve 
script object, or my script object to obtain an object of type 
ScriptObject" is self-referential at best. The Summary is better "an 
opaque type..." yep - it's opaque all right.

The dictionary entries for LCB commands are arcane CamelCase words 
seemingly drawn from thin air. CanvasOperationDrawImage, for example, 
has the syntax of "draw [ from mSrcRect of ] mImage into mDestRect of 
mCanvas". The syntax statement is understandable, but the entry should 
be "draw", not "CanvasOperationDrawImage".

Similarly, searching for "format" brings up "BooleanFormattedAsString", 
"FormatBooleanAsString", "FormatNumberAsString", and 
"NumberFormattedAsString". These refer to either the "format" command or 
the "formatted as string" modifier. The description field "Use 
NumberFormattedAsString when you want to manipulate a numeric value as 
text" doesn't reference the proper syntax for the modifier per the example.

And nothing in the "format" commands that came up in the search helped 
me figure out how to format a hex number as decimal, which is what I was 
looking for based on LCS expectations. There's no "see also" section 
which might have pointed me to the "convert" commands. The description 
of Operand as "An expression that evaluates to a number" isn't specific 
enough to help... is "FE" a number even though it's a hex number? Is 
"0xFE" a number"? Does a number have to be an integer (digging into 
StringPasedAsNumber would indicate no, but why is it necessary to do the 
digging)? Is 0123.50 a number? What's it's string value? Does it have 
the leading zero? The trailing zero? Can I control the output format?

Once I finally tried searching for convert (mind you, I don't want to 
*convert* the number, just display it differently) I was faced with a 
similar situation: "BaseConvert" (the syntax of which is actually 
"Operand converted from base Source to base Target"), "BaseConvertFrom" 
(with a syntax of "Operand converted from base Source", "BaseConvertTo" 
(syntax of "operand converted to base Target", and a reference to the 
com.livecode.typeconvert library.

So looking at BaseConvert, the Operand is specified as "An expression 
that evaluates to a string." Fair enough - I give it a hex number and I 
expect a decimal number out the back end. What's the format for a hex 
number? Is it "0xHH"? Just "HH"? Something else? Can I specify a leading 
zero? Number of expected decimal digits (what if I need three digits 
even if one or two are leading zeros?) These are easy in LCS, not so 
much in LCB.

Is it even possible to set the various delimiters? The documentation 
only talks about retrieving them. The description talks about the 
calling (script) handler's <type>Delimiter property... is this an actual 
property of the object or is just a shorthand way of talking about "the 
<type>Delimiter"?

I clicked on "type" in the Filters section. What does that do? All it 
seems to do is narrow my choices down to ScriptObject (see above).

The pointer type isn't documented.

Why is the "point" operator documented as "PointMake"? Is this just to 
differentiate between the "point" creator keyword and the "point" object 
keyword?

Some major strengths of LCS are missing in LCB, or at least don't appear 
to be in the documentation. Chunks, for instance. It's possible to get 
character chunks (and the [first|last] modifier in the offset functions 
are *very* nice), but there's no conception of words. This results in 
some ugly, convoluted, and error-prone coding to deal with things that 
are not only easy in LCS, but IMNSHO one of the things that makes 
LiveCode such a productive environment. I'm hoping this is just a 
documentation failure and not a missing feature.

The StringToJString and StringFromJString examples handler use the 
"foreign handler" construct, but "foreign" isn't in the dictionary. Nor 
is the "binds to" syntax. Nor the JObject or JString objects. Nor the 
"unsafe" keyword.

-- 
  Mark Wieder
  ahsoftware at gmail.com