LCB API's

[Ali Lloyd]

The fact that the example for the localdate doesn't actually include "local
date" is indeed confusing, and a bug.

I wonder if a judicious choice of parameter name would help with the
multiple entries for the same syntax. If we had *LeftList *is *RightList*,
etc. would that be ok?

The reason they are separate is because they are actually separate pieces
of syntax residing in different modules. They are tied to the types. I'm
not convinced it makes sense for them to all be in the same entry. However,
I do like the idea of having an additional grouped entry (a sort of
disambiguation page).

A syntax definition for LiveCode Builder looks like this

syntax ReplaceString is statement

    "replace" <Pattern: Expression> "with" <Replacement: Expression> "in"
<Target: Expression>

begin

    MCStringExecReplace(Pattern, Replacement, Target)

end syntax

ReplaceString is the 'name' of the syntax block. it is true that this
information is irrelevant from the point of view of the LiveCode Script
user. The question is, what do we replace the name with? In the LiveCode
Script dictionary, the name used is the filename of the corresponding Lcdoc
(or previously XML) file, with the hyphens replaced.

Currently the inline docs parsing takes the name from this block. Perhaps
the only option here is to add
Name: replace
and so on to every syntax declaration, as I'm not sure there is anything in
that syntax block that could be automatically formatted to the sort of
thing you're looking for.




On Tue, Sep 1, 2015 at 7:07 AM James Hale <james at thehales.id.au> wrote:

> Have to agree with Mike on this.
> I too find the LCB APIs confusing in having "names" of things that are not
> part of the syntax.
> The fact that the example for the localdate doesn't actually include
> "local date" is even more confusing.
>
> Just looking at some entries is see "ListIsList" which is an operator.
> However in looking at the syntax the actual operator is "is" in the
> context 'listA' is 'listB' although the docs present this a "left is right".
>
> I can only think that the names of the entries are derived in some way
> from the underlying meta card C function calls that are actually being used
> to provide the functionality. Great if your focus is LCB down to enabling
> functions in the engine, not so great if your focus is LCB and above.
>
> For example. "StringBeginsWithString" seems obvious.
> The actual operator according to the syntax is "begins with"
> Looking at the "list.mlc" source file this function makes a call to
> "MCListEvalBeginsWith" so I can see where the LCB name is derived.
>
> As I said this makes sense if I was concerned with authoring .mlc source
> but not so much if my focus was writing LCB files.
>
> Looking up "contains" one finds three entries.
> "Source contains Needle", "Target contains Needle" and "Target contains
> Needle". Yes the last two read the same.
> First point of confusion, what the ?*£? Is a "needle"?
> Second point, in all three entries the actual operator is "contains", only
> the context varies.
>
> Readability wise a single entry for "Contains" with the three cases
> described or three entries for contains perhaps of the form...
>     contains {string}
>     contains {byte}
>     contains {list}
>
> James
>
>
>
>
>
> _______________________________________________
> use-livecode mailing list
> use-livecode at lists.runrev.com
> Please visit this url to subscribe, unsubscribe and manage your
> subscription preferences:
> http://lists.runrev.com/mailman/listinfo/use-livecode