[Gambas-user] Locating a function's source code?

[Tobias Boege]

On Thu, 18 Sep 2014, T Lee Davidson wrote:
> Hi All,
> 
> I am almost lost when it comes to browsing the source code tree for 
> specific pieces of code.
> 
> The Gambas home page (http://gambas.sourceforge.net/en/main.html) has a 
> "Browse Source Code" link, but that page only shows the latest commits. 
> And, anything I do there to try to browse the tree, just seems to take 
> me around in circles.
> 
> The HTTP access command there and the SVN command on the Wiki's "How To 
> Deal With Subversion" page (http://gambaswiki.org/wiki/howto/svn) both 
> assume that one wants to checkout a copy of the repository. I do not.
> 
> I found that I can browse the code by converting the SVN-protocol URI to 
> a HTTP-protocol URI (http://svn.code.sf.net/p/gambas/code/gambas/), and 
> use my web browser to view the code tree.
> 
> Okay, good. Now where do I go from here?
> 
> 
> Suppose I wish to view the source code for the "Hex$" function. The Wiki 
> page for that function (http://gambaswiki.org/wiki/lang/hex) does not 
> give any clue as to what component or class it belongs to. A look at the 
> gb component and the gb class does not reveal that function.
> 
> So, I guess it is a built-in function native to the interpreter (?).

Yes, everything you find under /lang in the documentation belongs to the
language, which means that it's built into the interpreter.

> If 
> I decide to go with that assumption, that brings me back to, "where do I 
> go from here?"
> 
> I know that I would look in "trunk" for code upcoming in the next major 
> release, and in "branches" if I want to see how the function is 
> implemented in my current version. But exactly where would I look?
> 
> In "app/", in "main/", somewhere else?
> 
> And how might I be able to figure this out for myself next time?
> 

There are some places to remember:

 - /gb.*: components written in C/C++
 - /comp/src/gb.*: components written in Gambas
 - /app/src/*: Gambas programs such as the IDE, the wiki and the scripter
 - /examples: the example projects available from the IDE
 - /main/gbc: compiler, informer, archiver
 - /main/gbx: interpreter
 - /main/lib: components in C/C++ without dependencies

You are clearly looking for a built-in function of the interpreter here, so
go into /main/gbx. Built-in functions do not belong to a (real[*]) class and
almost certainly begin with "SUBR_", you find them very likely in a file
whose name contains "subr".

If you don't want to download the source tree, I cannot give you any further
advice. You need to look around and with enough memory and experience with
the files, you'll eventually find what you look for.

[*] There seems to be a formal class named "." which has each intrinsic
    function as a method (see. gbx_class_info.c).

----------------------------------------------------------------------------

For the people who have a local copy of the tree: do a bold grep:

  $ grep hex -IR *
  gbx_api.c:      (void *)SUBR_hex_bin,
  gbx_exec_loop.c:        SUBR_hex_bin,    /* 40 68 */
  gbx_exec_loop.c:        SUBR_hex_bin,    /* 41 69 */
  gbx_subr.h:void SUBR_hex_bin(ushort code);
  gbx_subr_conv.c:void SUBR_hex_bin(ushort code)
  ...

SUBR_hex_bin might be what you want. From there, your real journey through
the code begins. I recommend to use ctags and an editor which is capable of
using it.

Regards,
Tobi

-- 
"There's an old saying: Don't change anything... ever!" -- Mr. Monk