[:: AlMuist's API Documentation ::]

Applications, Classes and Languages

Introduction

On this page I explain how are the concepts of applications (which is a complete project, possibly with makefiles, documentation, and so on), classes (the basic runnable component of an application) and programming languages (of which we want to be as much independent as possible) modelized in AlMuist's.

Applications

As said before, applications should later store every information about the project as well as the way it is compiled, how the program can be ran, etc. For now however it will just contain the following information:

• The programming language to generate (see below)
• All classes that compose the program, including one that is the class that is executed when the program is launched

So it is currently up to the programmer to know what amool child must be ran, and what are the names of the source files to be generated, and what command must be ran to compile and run them

For instance, if you have your project in the file myProject, you would do something like:

> acompile @myProject.mainClass MyProject.java
Reading config file /usr/local/amool/conf/amool.conf
Amool 1.3.8 compiler/parser v1.4.2 - by Maxime Gamboni
> acompile @myProject.helperClass Helper.java
Reading config file /usr/local/amool/conf/amool.conf
Amool 1.3.8 compiler/parser v1.4.2 - by Maxime Gamboni
> javac MyProject.java Helper.java
> java MyProject

Class

Classes are what the executable part of a project is made of (AlMuist's assumes the underlying language to be object oriented, like Java. To generate code for a language that is not object oriented, the notion of classes must be somehow emulated in the language description (I will make an example in C someday :-)

Java being for now the only supported language, a class, in AlMuist's API, is currently a transcription of Java classes into Amool, ie a structure that has a name, contains methods, attributes, constructors and inner/nested classes, that extends one class and implements interfaces

I won't bother you with heavy details here, you can look at the reference (okay, sorry, I have not yet written it, but it will come shortly :-), play with the below examples or those in the archive, or look at the amool implementation of classes, methods, constructors etc

Programming Languages

All application should have a child (typically named @language) that inherits from a language specification, which defines basic components of source code in that language (for instance what syntax do we use to declare a local variable of a given type ?), which can in turn be used by the rest of the application to be independent of the programming language.
I have chosen to keep these descriptions empty until I code support for another language than Java, so I will see more precisely what kind of building blocks a language should define to describe itself (so for now everything is hardcoded in Java, later I will replace all Java code by references to these generic building blocks)

Writing An Application

Let's see a little example of a silly hello-world application before entering into details:

&=!language &=super @javaLang && &&

&=super @application &&

&=name HelloWorld &&

&+mainClass.methods &=super @langMethod && @super
 &=name printHello &&
 &+early System.out.print("Hello"); &&
&&

&+early printHello();
        System.out.println(" World !!");
&&

This code tells, in order:

1. We want to generate Java code
2. This is the code for a basic application ...
3. ... named HelloWorld (as we don't override that behaviour, the name of the main (and only) class will be named HelloWorld.java)
4. Then we add a method to the main class (a dummy @mainClass is constructed by @application ), the method is named printHello and prints "Hello" to stdout.
5. Then we want to execute these two Java commands (printHello();System.out.println(" World !!");)

When compiled, this code generates the following:

> acompile @demo.mainClass
Reading config file /home/max/almuists/amool_1.3/conf/amool.conf
Amool 1.3.8 compiler/parser v1.4.2 - by Maxime Gamboni

/** (this class was generated with Amool) */
public class HelloWorld {



    /** main method */
    public static void main( String args[] ) {
        HelloWorld instance = new HelloWorld();
        instance.go(args);
   
    }
    /** the nonstatic main */
    public void go( String args[] ) {
        printHello();
        System.out.println(" World !!");
   
    }
    
    public void printHello(  ) {
        System.out.print("Hello");
   
    }


}

So what can we do when writing an application using the AlMuist's API?

The @application class gets information from the following children:

• @language which must be a language descriptor
• @name which should contain a name for the application. It is typically the name of the main file without the extension (but can be different, see mainClass.name below)
• @mainClass which is the class (see below how to make a class) that is ran when the application is executed. The @application class supplies a default one that just defines its name to that of the application but you can erase it if you want.
• @early, code that must be executed when the application starts.
• @late is like @early but all early-code is put before the first late-code. A example of use of this is application with graphical interfaces, where we want all children of a window to be constructed and attached to it before we open the window. So we put gadget creation and connection in @early, and window opening in @late.

The @langClass class gets information from the following children:

• @package, which will typically be in the current directory (to be visible from all classes) instead of the class itself but you do as you wish :-). It is a string that is the package the class is contained in.
• @import are the imported classes. When evaluated, should return the name of the classes without final semicolon, eg java.util.* or java.io.InputStream
• @extends the super class of the described class (don't mistake with the amool class, of which the super class is @langClass !) Can be omitted.
• @implements put as many definitions of this symbol as you want your class to implement interfaces.
• @comments are comments to be put at the beginning of the class (between /** **/). You can put as many definitions as you want and their values will be appended.
• @ is the name of the class
• @constructors, typically subclasses of @langConstructor, the constructors of the class. When evaluated, should produce the full definition of the constructors.
• @attributes are the attributes of the class. When evaluated, should produce the full definition of the attibute (eg String name = "toto";)
• @innerClasses, typically subclasses of @langClass are the inner or nested classes. If you want to hardcode your class then you must put its code in a child named @justClass.

For more details, have a look at the reference (coming soon!! :-) or the source code of AlMuist's.

Maxime Gamboni <>