External Design

[Ruslan Zasukhin]

Hi Trevor,

Ops, I only now have to note this your text.

> External Design
> 
> Though the following suggestion isn't critical it would make the Valentina
> external feel more natural to Transcript programmers.
> 
> It appears that all Valentina external calls are implemented as functions
> (XFUNCTION in the Xternal XTable definition).  Ideally some of the handlers in
> the external would be defined as commands (XCOMMAND in the Xternal XTable
> definition).  For example, Valentina_DebugLevel is currently used like this:
> 
> get Valentina_DebugLevel("kLogParams")
> 
> when the Transcript way to do this would be:
> 
> Valentina_DebugLevel "kLogParams"
> 
> The handler doesn't return any data and you are "commanding" the external to
> do something.  If the command could generate errors then the developer could
> check the result().  result() contains whatever the command returns from the
> external.  Right now the handler returns an integer when it really doesn't
> need to return anything.
> 
> Other handlers which might fall into this category include
> Valentina_FlushEachLog, Valentina_Init (and _InitClient), Valentina_ShutDown,
> etc.
> 
> If this change is made you can visually distinguish the two in the
> documentation by including "(", ")" for functions but not for commands.  For
> example, the docs currently say:
> 
> Valentina_DebugLevel([inLevel])
> 
> If this were changed to a command it would be documented as:
> 
> Valentina_DebugLevel [inLevel]
> 
> and under the description of the handler you would write
> 
> Valentina_DebugLevel([inLevel])
> Command
> Returns: integer (this really should return empty, shouldn't it?)

Well, I will check docs again.

In fact e.g. DebugLevel works as property:

// get Valentina_DebugLevel( inLevel )
// put Valentina_DebugLevel into VAR

So if Valentina see ZERO parameters, then this function RETURNS value.
ELSE it returns nothing.

I think this your text is quite old, before we have update V4REV docs ..
But I will check again.


-- 
Best regards,

Ruslan Zasukhin
VP Engineering and New Technology
Paradigma Software, Inc

Valentina - Joining Worlds of Information
http://www.paradigmasoft.com

[I feel the need: the need for speed]