[Gambas-devel] gb.api new version and documentation

[Benoit Minisini]

On Wednesday 11 May 2005 14:26, Daniel Campos wrote:
> Hi:
>
> I've updated the gb.api component, examples and documentation:
>
> 1) The "ApiPointer" class exists no more. Instead pointers are managed
> with the "Integer" or "Pointer" data type, so it wastes less memory per
> each pointer defined.  However, a static class called "Pointer" provides
> functions to manage memory easily. I think it is much more clear and
> intuitive that
> using the READ and WRITE functions. 

Actually, the job of reading and writing data from a pointer was already 
existing in the READ and WRITE method (except for the string case). So it was 
logical to use them.

Using a pointer as a stream allow to use other functions like PRINT, INPUT, 
LINE INPUT too. This could be interesting.

But I admit it may be less clear for the user.

> Now the memory allocations and 
> freeings can be made using the Alloc and Free methods from Gambas.
> The "Pointer" class still provides the "AllocString" method to help in
> string
> allocations.

The Alloc() subroutine will take a string as its argument too, and will behave 
the same way.

>
> 2) I've updated the documentation, adding the Structure and Callback
> management.
> It is updated in English and Spanish, but I'd need help from the French
> and German
> translations to update these versions (and of course, to be part of my
> little "Hall of Fame" :-))
> Please be careful when translating, as the "Pointer" part as changed a
> lot and there are
> little changes everywhere.
>
> 3) I think Gambas could keep into its core the "Pointer" alias, the
> "Free", "Alloc" and "Realloc"
> methods, and let the rest of the code in a component:
>
> (a) All this code is needed just for very specific applications
>

This is the main reason for putting code outside the interpreter. But if you 
look at the way I did, you will see that there is not too much code added. 
Many features were already done by interpreter in many ways.

Maybe the callback feature that I didn't implemented should stay in the 
component if it takes too much code to implement it.

> (b) Having the declarations in a component, declarations can be
> deleted from memory if not needed, saving memory.

If you don't need them, why declaring them ? :-)

Now EXTERN declarations are part of the class file format.

I prefer they are managed by the compiler and the interpreter because: 

* They are tied to compiler and interpreter internals like native datatypes.

* Calling convention is specific to the architecture. In general, I prefer not 
having architecture specific code in components.

* Shared libraries extension change with the architecture. For example, 
libfoo.so.6.3 on Linux and libfoo.6.3.dylib on MacOSX. The user just have to 
specify "libfoo.6.3", and the interpreter will do the translation.

>
> (c)I think is better also to use the "Api" class and the unknown method,
> as, for example, a line of code like this:
>
> "Api.gtk_init(NULL,NULL)"
>
> is more coherent with an object oriented language than simply a
> "misterious" new method
> in Gambas:
>
> "gtk_init(NULL,NULL)"
>
> The first one represents an object and a function related with the API,
> the second one makes difficult to a programmer to know where this new
> "Gambas function" comes from when reading code written by other people.

I don't think so. EXTERN declarations are private to the class, so it is not a 
huge job to find where it comes from :-) 

And I think they will stay private.

I think EXTERN calls must be used for writing components in Gambas that uses 
specific libraries, without the need of writing them in C/C++, which takes a 
longer time to do.

>
> (d) and "psicologically", having it in a component probably will prevent
> to use that feature for everything without stopping to think a little if
> all can be done without having to use external libraries.

*This* argument is good :-)

I think I will add a flag to the compiler (and the IDE) to enable/disable such 
"dangerous" features.

>
> 4) All the new stuff is placed at: http://gambas.gnulinex.org/api
>
> Regards,
>
> D. Campos
>

Regards,

-- 
Benoit Minisini
mailto:gambas at ...1...