Tutorial to Adding New Commands to yab

yab is based on the yabasic interpreter (http://www.yabasic.de). On the yabasic website you will find additional sources how to enhance the interpreter (titled "Guide into the Guts of Yabasic"). Nevertheless, this documents should give an in-depth introduction too.

You need some basic knowledge about yab, C, C++ and probably the BeAPI for adding new commands to yab. Knowledge about flex and bison are not necessary.

2   Designing a Command

A typical yab command normally is either a procedure (function returning void), a function returning a number (double or int) or a function returning a string (char*).

A command consists of

   -   the command words (lexical entities)

   -   the command rule

   -   the C wrapping function calling the C++ method

   -   the C++ method

This will be descussed in details in the upcomming sections.

2.1   The Command Words

The words needed by a command (tokens) are defined in the file yabasic.flex. Please introduce only new command words, when the existing are not sufficent to describe your new command. Browse through the file to find all yabasic and yab commands.

A command word consists of the word itself (in capital letters) and the token it returns. The token is most often simply the word itself with a t in front of it.

Example:

There are exceptions for the token name, e.g. tGet represents the comand word GET$ while tGETNUM represents GET.

New tokens have then to be declared in the file yabasic.bison too by simply adding the token name in the token list at the beginning of the file.

2.2   The Command Rule

The actual command rule (grammar) has to be added to the file yabasic.bison. If you scroll through the file you get a good idear how the grammar should look like.

Basically three sections in this file are interesting: the section for procedures, the section for nummerical functions and the section for string functions. We will investigate the different of these functions in next two subsections.

But first we have a look at the similarities. A command rule is written with a leading pipe | followed by the tokens and the arguments. At the very end, a C function identifier follows.

Example:

Here, coordinates is a subtitution for expression ',' expression and to is a subtitution for the command TO (which is just a ',' anyway).

So basically there are two types of arguments: expression is a number (of type double) and string_expression is a string (of type char*). They can be separated by commas ','. Brackets ('(' and ')') are possible too, but I have not used them often.

Thus, in this example the BUTTON command have 7 arguments, 4 numbers for the coordinates and 3 strings that will contain the own ID, the button text and the view D.

2.3   Procedures

As all procedures, the mentioned example does not return a value (it is a void function in C). It gets a internal identifier named cBUTTON. This identifier has to be declared in the file yabasic.h. Just check the list of other similar indentifiers for the location in the file.

Furthermore, in yabasic.h the name of the C function that is added to the file graphic.c has to be declared. Procedures always get a struct command *, YabInterface * as argument. The command struct contains informations about the yab arguments, line number etc. Thus, in graphic.c the C function will simply forward these information to the main C++ class (YabInterface).

Just before adding the function in grephic.c it has to be added in main.c too. There, add it to the switch that calls the functions according to their identifier. E.g.:

A typical void function in graphic.c looks like the following example:

In our example, first the 7 yab arguments are retrieved from the command struct.

Die Argumente werden auf einem Stack gelagert, also müssen Sie sie im umgekehrten Reihenfolge zurückholen! Hier wird z.B. y1 vor x1 zurückgeholt. Auch Zeichenketten und Zahlen haben unterschiedliche pop calls.

Numbers can be either double or int but for coordinates, always double should be used.

The current line number is passed in to the YabInterface class by calling yi_SetCurrentLineNumber. This line is the samefor all void functions.

Finally, the arguments are passed on to the YabInterface class by calling yi_CreateButton.

2.4   Fuctions

Functions that either return a number or a string are implemented differently. First they get a different identifier starting with an f e.g. fLISTBOXGETNUM. This identifier has to be declared in yabasic.h in the enum functions.

Die Funktionen werden durch die Anzahl ihrer Argumente sortiert!

Additionaly, the name of the C function that is added to the file graphic.c has to be declared in yabasic.h too. Differently to procedures, these functions get their argument set immediatly, e.g.:

listboxgetnum returns an int while taking a string as first argument. The further arguments YabInterface *yab, int line, const char* libname have to be added to provide the YabInterface class further informations.

Other than procedures, the stack retrieval of arguments and the function call are all done in the file function.c. These, the yab arguments are retrieved from the stack and forwarded to the wrapper function in graphic.c.

Example:

The string argument is retrieved by a1->pointer. Numerical arguments are addressed by e.g. a3->value (not in this example). The arguments are numbered from a1 to a6. More arguments are currently not supported.

Here, the result is stored as a number. For strings, the result should be stored in pointer and result = stSTRING; has to be set. Check the other cimmands in this file for further examples.

Finally, the wrapper function has to be implemented in graphic.c. For our example, this looks like the following code:

The current line number is passed on to the YabInterface class by calling yi_SetCurrentLineNumber. This line is the same for all functions. The returned number is then simply passed on by yi_ListboxgetNum.

strings have to be copied with my_strdup, e.g. return my_strdup((char*)yi_CheckMessages(yab));. It is up tp you that strings still exist in memory when copied!

3   The C++ Class YabInterface

3.1   Adding a Method

After the above described overhead, we are ready to actually write the new method. The method has a C++ name and a wrapper function with an external name starting with yi_. Both have to be defined in YabInterface.h and implemented in YabInterface.cpp.

The wrapper function takes the pointer to the YabInterface object and calls the main method:

The _L() macro that is used on all text that should be translated automagically by the ZETA local kit. It will kick in when the LOCALIZE command was used. So please use this macro whenever possilbe, to allow simple localization.

The method itself is part of the YabInterface class which is derived from BApplication. You can always expect BApplication up and running (with the interpreter in an own threat). Thus, all BApplication methods are directly accessable from your method.

3.2   Accessing yab Data Structures

yab stores various information in list objects. The probably most waned list is the of available views. These are stored in the YabList object viewList. To initialize a new widget, it is often sufficient to find the parent view. this is done by calling YabList::GetView(const char*):

New widgets should allow some usefull layouting. Please refer to the commands for BUTTON and LISTBOX to understand how different kinds of layoutung are used in yab.

If you want to find a specific widget on an unkown view, you have to cycle through that views to look for the view containing your widget. Such a loop looks like this (under the condition that MyWidget is derived from BView):

The return is set after something has been done with the widget and after unlocking the window again. This allows the lazy error checking at the end of the loop..