Go to the first, previous, next, last section, table of contents.

The ``jswrap`' Program

The jswrap program is a tool that helps implementing C functions in JavaScript.

Invoking The `jswrap` Program

The jswrap program is invoked as:

jswrap options... file

The jswrap program processes the command line options and according to them and the default values, it converts the input file file to the corresponding `.h' and `.c' files. The options can be one of more of the following command line options:

-g
--debug: Generate debugging information to the generated JavaScript byte-code.
-h file
--header file: Generate the C header file to file file. The default C header file name is constructed from the input file name by replacing the suffix `.jsw' with suffix `.h'.
-n
--no-error-handler: Do not generate the default error handler to the generated C files. If this option is specified, then the error handler must be defined in your code.
-o
--output file: Generate the C output to file file. The default output file name is constructed from the input file name by replacing the suffix `.jsw' with suffix `.c'.
-r
--reentrant: Generate re-entrant C functions. The option adds a `JSInterpPtr' argument to all C functions it generates.
-V
--version: Print the version number of the jswrap program.
--help: Print a short help message that describes the options that can be given to the jswrap program.

Definition File Format

The definition file contains the function definitions and their implementation in JavaScript. The function definitions are normal JavaScript function definitions but they are extended with the type information. The type information is used to generate the C header files and the glue code that is used in the function call. The definition file can also contain normal JavaScript comments. The comments are ignored and they are not copied to the generated C header and implementation files.

The syntax of the function definition is:

function [return_type] function_name (argument_type... argument[, ...])
{
  JavaScript code implementing the function.
}

Where:

return_type: specifies the return type of the function. If the return type specification is omitted, the function is a void function returning no value.
function_name: is the name of the function. The name must be a valid C identifier matching regular expression `^[A-Za-z_][A-Za-z_0-9]*'.
argument_type: specifies the type of the argument, its passing type, and the life scope of the value of the argument.
argument: is the name of the argument. The name must be a valid C identifier.

The Type Specifiers

The type specifiers specify the native C and JavaScript type that is used for the argument or for the return value. The following type are supported:

cstring: A '\0' terminated C-string. In the C, this is presented as `char *'. In the JavaScript, this is a normal string.
double: A floating point number. In the C, this is a `double' floating point number.
int: An integer Number. In the C, this is a `long' integer.
string: An arbitrary data block. In the C, this is presented as `unsigned char *, unsigned int' pair. In the JavaScript, this is a normal string. Note! Because the type's presentation in C is two types, this value can't be used as a return value of a function.

The following example shows how the types are converted to the corresponding C header file. The input file `types.jsw' is as follows:

function types (cstring vcstring, double vdouble, int vint,
                string vstring)
{
}

The resulting C header file `types.h' contains the following definitions for the function types:

void types (
        char *vcstring,
        double vdouble,
        long vint,
        unsigned char *vstring,
        unsigned int vstring_len
        );

The Pass-Type Specifiers

The passing type specifiers specify how the argument is passed to the function. The following specifies are supported:

in: An input argument. This is the default pass-type for arguments.
out: An output argument. In the JavaScript, the initial value of the argument is undefined. When the control returns from the implementation of the function, the argument's current value is returned to the calling C function. In the C, the output and input-output arguments are presented as pointers to the variables, containing the values.
inout: An input-output argument.

The following example shows show the output and input-output arguments are presented in the C header file. The input file `pass.jsw' is as follows:

function pass (out cstring vcstring, out double vdouble, inout int vint,
               inout string vstring)
{
}

The resulting C header file `pass.h' contains the following definitions for the function pass:

void pass (
        char **vcstring,
        double *vdouble,
        long *vint,
        unsigned char **vstring,
        unsigned int *vstring_len
        );

The Life Scope Specifiers

The life scope specifiers specify the liveness of the value, passed in an argument. The following specifiers are supported:

static: The argument points to static data that can't change while the execution is in the JavaScript code. This means that the JavaScript can use the same data that is given to it; it don't have to make a private copy of the data. The specifier can only be used with cstring and string types. The specifier don't have any affect for the generated C header file.

function hello (cstring user)
{
  System.stdout.writeln ("Hello, " + user + "!");
}

function int max_sum (int a, int b, int out sum)
{
  sum = a + b;

  return a > b ? a : b;
}

$ jswrap sample.jsw

/* This file is automatically generated from `hello.jsw' by jswrap. */

#ifndef HELLO_H
#define HELLO_H

void hello (
        char *user
        );

int max_sum (
        int a,
        int b,
        int *sum
        );

#endif /* not HELLO_H */

#include <js.h>
#include "hello.h"

JSInterpPtr jswrap_interp;

int
main (int argc, char *argv[])
{
  int a, b, max, sum;

  jswrap_interp = js_create_interp (NULL);

  hello ("World");

  a = 5;
  b = 7;
  max = max_sum (a, b, &sum);
  printf ("%d + %d = %d, max(%d, %d) = %d\n", a, b, sum, a, b, max);

  return 0;
}