« | Main | »

JewelScript changes log

By Jewe | October 3, 2012

This post lists all changes made to the project since it’s previous public release, version The newest change is on top of the list.

New features and improvements

Added optional ‘argument names’ list to anonymous function literals

When you wanted to use one of the built-in delegate types, like for example the array::comparator delegate, it was difficult to know the names of any arguments passed into that delegate. Basically you had to look into the documentation or just guess the parameter names. An example might make this clearer:

// in the runtime, the array::comparator delegate is declared like this:
// delegate int array::comparator(var value1, var value2);

function main()
    string[] names = { "Judy", "Christopher", "Helen", "James", "Sandra", "Rick" };

    names = names.sort( function {
        // problem: what are the names of the delegate parameters??
        }, null );
    // solution: specify them
    names = names.sort( function(a, b) {
        // do something to compare 'a' with 'b'
        }, null );

Added ‘operator new’ initializer block statement

It is now possible to append a block-statement to a new expression. Within this block, the newly created instance can be directly manipulated:

class Person
    string Name;
    int Age;
    float Shoesize;

    method Person() // standard ctor

function main()
    Person per = new Person() { Name = "Steve"; Age = 34; Shoesize = 7.5; };

As you can see, inside the initializer block, you have direct access to the Person instance’s variables. You also have access to the this reference and any methods of the class, as if the block were a method within the Person class. However, the code is actually compiled as part of the main() function, so you still have access to all local variables defined in that function from inside the initializer block.

Added ‘import all’ statement

To make generating HTML documentation for your application’s native types easier, there is now the possibility to import all native types registered to the runtime with a single statement:

import all; // imports all known native types!

However, it should be noted that with very large projects and many classes, this may cause a performance hit and use a lot of memory. For this reason, even though it may seem convenient, I don’t recommend using import all for normal script programming purposes. You should only import the classes your script actually needs, so the memory footprint stays as low as possible.

As another, minor inconvenience, this change also means that you no longer can import a class named ‘all’. As a workaround, you could call the class ‘_all’ instead. Or even give it another, more sensible name. ;)

Improvements to the HTML documentation generator

The HTML documentation generator now properly sorts class- and function names alphabetically. I also added a new parameter to the API function JCLGenerateDocs(), allowing the caller to pass parameters to the generator. Here is an example using the generator from within JewelScript itself using the runtime class:

option "document=all";

import runtime;

function string main(const string[] args)
    // generate docs but ignore interfaces and classes defined by the JILRun application
        "application=JewelScript, @ignore=InputEvent, @ignore=__global");
    return "";

Added down-casting from interface type to class type using cast operator

It is now possible to cast a variable from interface type to it’s implementing class type using the cast operator:

interface IControl {}
class Button : IControl {}

function AddButton(IControl btn)
    Button button = (Button)btn;

Extended variable scope when calling functions and methods

When calling a method of a class and specifying a global constant declared in that same class, you no longer have to specify the full qualified variable name:

class CharColor
    const int Black = 0;
    const int Red = 1;
    const int Blue = 2;
    const int Green = 3;
    method CharColor(int foreground, int background)
        Foreground = foreground;
        Background = background;

    int Foreground;
    int Background;

function main()
    CharColor c = new CharColor(Red, Black); // new CharColor(CharColor::Red, CharColor::Black);

As you can see, you no longer need to specify the class name when passing a constant as a parameter to a method of the same class. The compiler will first attempt to look up the constant in the namespace of the class, then in the global namespace.

Overhaul of the built-in types

The built-in types string, array, list, iterator and table have been improved.

Several new methods have been added to the string class. Also, some of the string methods have been renamed to be more consistent with their counterparts in other languages. For example the string::findCharReverse() method has been given the widely known string::lastIndexOf() method name.

Similar to the list class, the array class now has a array::sort() method that takes a comparison delegate as a parameter.

New API functions for loading file resources

There are now convenience functions in the API that allow a native type easier file access through the runtime’s file input proc: NTLFileOpen(), NTLFileClose(), NTLFileRead(), NTLFileSeek(), NTLFileLength().

Of course a native type can implement loading of resources by any other means, too. However, there are cases where you need centralized handling of loading of resources.

One example is loading resources from compressed archives: The JILRuntime API allows you to override it’s default loading behaviour by installing a callback function that implements custom file input. That way, you can load and compile script files from a compressed archive, rather than the local file system, for example.

However, in such an application scenario, you may want all of your native types to load their resources from those archives (e.g. Bitmap class loading images from the archive, Sound class loading wave files, etc.) By using the above API functions, which normally map through to the standard C file I/O functions, you can make sure that all your application’s file I/O is handled by the same method.

Bugs fixed

Using HTML tags in class documentation no longer breaks exported XML

The HTML documentation generator allows you to use regular HTML tags within your class documentation, making it possible to improve the formatting of the generated documentation. However, since these annotations will also be written to the XML export file, the HTML tags could actually corrupt the generated XML format. This has now been fixed by properly escaping all invalid characters by their proper XML entities.

native class implementing native interface

When declaring a native class that would implement a native interface, the compiler would fail. This has been fixed.

// create native binding for MyRandom, implementing pure native interface IRandom
native class MyRandom : IRandom

Other fixes

Topics: docs | Comments Off on JewelScript changes log

Comments are closed.