Software: Apache/2.0.54 (Unix) mod_perl/1.99_09 Perl/v5.8.0 mod_ssl/2.0.54 OpenSSL/0.9.7l DAV/2 FrontPage/5.0.2.2635 PHP/4.4.0 mod_gzip/2.0.26.1a 

uname -a: Linux snow.he.net 4.4.276-v2-mono-1 #1 SMP Wed Jul 21 11:21:17 PDT 2021 i686 

uid=99(nobody) gid=98(nobody) groups=98(nobody) 

Safe-mode: OFF (not secure)

/usr/doc/slang-1.4.5/html/   drwxr-xr-x
Free 318.37 GB of 458.09 GB (69.5%)
                            Encoder    Tools    Proc.    FTP brute    Sec.    SQL    PHP-code    Update    Feedback    Self remove    Logout    

Viewing file:     cslang-3.html (28.56 KB)      -rw-r--r--

3. Interpreter Interface

The S-Lang library provides an interpreter that when embedded into an application, makes the application extensible. Examples of programs that embed the interpreter include the jed editor and the slrn newsreader.

Embedding the interpreter is easy. The hard part is to decide what application specific built-in or intrinsic functions should be provided by the application. The S-Lang library provides some pre-defined intrinsic functions, such as string processing functions, and simple file input-output routines. However, the basic philosophy behind the interpreter is that it is not a standalone program and it derives much of its power from the application that embeds it.

3.1 Embedding the Interpreter

Only one function needs to be called to embed the S-Lang interpreter into an application: SLang_init_slang. This function initializes the interpreter's data structures and adds some intrinsic functions:

      if (-1 == SLang_init_slang ())
        exit (EXIT_FAILURE);

     if ((-1 == SLang_init_slang ())    /* basic interpreter functions */
         || (-1 == SLang_init_slmath ()) /* sin, cos, etc... */
         || (-1 == SLang_init_stdio ()) /* stdio file I/O */
         || (-1 == SLang_init_posix_dir ()) /* mkdir, stat, etc. */
         || (-1 == SLang_init_posix_process ()) /* getpid, umask, etc. */
        )
       exit (EXIT_FAILURE);

     if (-1 == SLang_init_all ())
       exit (EXIT_FAILURE);

3.2 Calling the Interpreter

There are several ways of calling the interpreter. The most common method used by both jed and slrn is to use the SLang_load_file function to interprete a file. For example, jed starts by loading a file called site.sl:

     if (-1 == SLang_load_file ("site.sl"))
       {
         SLang_restart (1);
         SLang_Error = 0;
       }

There are several other mechanisms for interacting with the interpreter. For example, the SLang_load_string function loads a string into the interpreter and interprets it:

    if (-1 == SLang_load_string ("message (\"hello\");"))
      {
        SLang_restart (1);
        SLang_Error = 0;
      }

Typically, an interactive application will load a file via SLang_load_file and then go into a loop that consists of reading lines of input and sending them to the interpreter, e.g.,

      while (EOF != fgets (buf, sizeof (buf), stdin))
        {
           if (-1 == SLang_load_string (buf))
             SLang_restart (1);
           SLang_Error = 0;
        }

Both jed and slrn use another method of interacting with the interpreter. They read key sequences from the keyboard and map those key sequences to interpreter functions via the S-Lang keymap interface.

3.3 Intrinsic Functions

An intrinsic function is simply a function that is written in C and is made available to the interpreter as a built-in function. For this reason, the words `intrinsic' and `built-in' are often used interchangeably.

Applications are expected to add application specific functions to the interpreter. For example, jed adds nearly 300 editor-specific intrinsic functions. The application designer should think carefully about what intrinsic functions to add to the interpreter.

Restrictions on Intrinsic Functions

Intrinsic functions are required to follow a few rules to cooperate with the interpreter.

Intrinsic function must take only pointer arguments. This is because when the interpreter calls an intrinsic function, it passes value to the function by reference and not by value. For example, intrinsic with the declarations:

     int intrinsic_0 (void);
     int intrinsic_1 (char *s);
     void intrinsic_2 (char *s, int *i);
     void intrinsic_3 (int *i, double *d, double *e);

     int invalid_1 (char *s, int len);

Intrinsic functions can only return void, int, double, or char *. A function such as

    int *invalid (void);

Another restriction is that the intrinsic should regard all its parameters as pointers to constant objects and make no attempt to modify the value to which they point. For example,

      void truncate (char *s)
      {
         s[0] = 0;
      }

Adding a New Intrinsic

There are two basic mechanisms for adding an intrinsic function to the interpreter: SLadd_intrinsic_function and SLadd_intrin_fun_table. Functions may be added to a specified namespace via SLns_add_intrinsic_function and SLns_add_intrin_fun_table functions.

As an specific example, consider a function that will cause the program to exit via the exit C library function. It is not possible to make this function an intrinsic because it does not meet the specifications for an intrinsic function that were described earlier. However, one can call exit from a function that is suitable, e.g.,

     void intrin_exit (int *code)
     {
        exit (*code);
     }

     if (-1 == SLadd_intrinsic_function ("exit", (FVOID_STAR) intrin_exit,
                                         SLANG_VOID_TYPE, 1,
                                         SLANG_INT_TYPE))
       exit (EXIT_FAILURE);

     message ("Calling the exit function");
     exit (0);

The most convenient mechanism for adding new intrinsic functions is to create a table of SLang_Intrin_Fun_Type objects and add the table via the SLadd_intrin_fun_table function. The table will look like:

    SLang_Intrin_Fun_Type My_Intrinsics [] = 
    {
     /* table entries */
      MAKE_INTRINSIC_N(...),
      MAKE_INTRINSIC_N(...),
            .
            .
      MAKE_INTRINSIC_N(...),
      SLANG_END_TABLE
    };

    MAKE_INTRINSIC_N(name, funct-ptr, return-type, num-args,
                     arg-1-type, arg-2-type, ... arg-7-type)

    MAKE_INTRINSIC_N("exit", intrin_exit, SLANG_VOID_TYPE, 1,
                     SLANG_INT_TYPE, 0,0,0,0,0,0)

While MAKE_INTRINSIC_N is the main macro for constructing table entries, slang.h defines other macros that may prove useful. In particular, an entry for the intrin_exit function may also be created using any of the following forms:

    MAKE_INTRINSIC_1("exit", intrin_exit, SLANG_VOID_TYPE, SLANG_INT_TYPE)
    MAKE_INTRINSIC_I("exit", intrin_exit, SLANG_VOID_TYPE)

The table may be added via the SLadd_intrin_fun_table function, e.g.,

    if (-1 == SLadd_intrin_fun_table (My_Intrinsics, NULL))
      {
         /* an error occurred */
      }

Earlier it was mentioned that intrinsics may be added to a specified namespace. To this end, one must first get a pointer to the namespace via the SLns_create_namespace function. The following example illustrates how this function is used to add the My_Intrinsics table to a namespace called my:

   SLang_NameSpace_Type *ns = SLns_create_namespace ("my");
   if (ns == NULL)
     return -1;

   return SLns_add_intrin_fun_table (ns, My_Intrinsics, "__MY__"));

More Complicated Intrinsics

The intrinsic functions described in the previous example were functions that took a fixed number of arguments. In this section we explore more complex intrinsics such as those that take a variable number of arguments.

Consider a function that takes two double precision numbers and returns the lesser:

     double intrin_min (double *a, double *b)
     {
        if (*a < *b) return *a;
        return *b;
     }

    MAKE_INTRINSIC_2("min", intrin_min, SLANG_DOUBLE_TYPE,
                     SLANG_DOUBLE_TYPE, SLANG_DOUBLE_TYPE)

    double intrin_min_n (int *num_ptr)
    {
       double min_value, x;
       unsigned int num = (unsigned int) *num_ptr;
       
       if (-1 == SLang_pop_double (&min_value, NULL, NULL))
         return 0.0;
       num--;
       
       while (num > 0)
         {
            num--;
            if (-1 == SLang_pop_double (&x, NULL, NULL))
              return 0.0;
            if (x < min_value) min_value = x;
         }
       return min_value;
    }

    MAKE_INTRINSIC_I("min", intrin_min_n, SLANG_DOUBLE_TYPE)

      variable xmin = min (x0, x1, x2, x3, x4, 5);

The problem with this intrinsic function is that the user must explicitly specify how many numbers to compare. It would be more convenient to simply use

      variable xmin = min (x0, x1, x2, x3, x4);

    double intrin_min (void)
    {
       double min_value, x;
       
       unsigned int num = SLang_Num_Function_Args;
       
       if (-1 == SLang_pop_double (&min_value, NULL, NULL))
         return 0.0;
       num--;
       
       while (num > 0)
         {
            num--;
            if (-1 == SLang_pop_double (&x, NULL, NULL))
              return 0.0;
            if (x < min_value) min_value = x;
         }
       return min_value;
    }

    MAKE_INTRINSIC_0("min", intrin_min, SLANG_DOUBLE_TYPE)    

3.4 Intrinsic Variables

It is possible to access an application's global variables from within the interpreter. The current implementation supports the access of variables of type int, char *, and double.

There are two basic methods of making an intrinsic variable available to the interpreter. The most straight forward method is to use the function SLadd_intrinsic_variable:

     int SLadd_intrinsic_variable (char *name, VOID_STAR addr, 
                                   unsigned char data_type, 
                                   int read_only);

     int I;

     if (-1 == SLadd_intrinsic_variable ("I_Variable", &I, 
                                          SLANG_INT_TYPE, 0))
       exit (EXIT_FAILURE);

    char *S;

     if (-1 == SLadd_intrinsic_variable ("S_Variable", &S,
                                          SLANG_STRING_TYPE, 1))
       exit (EXIT_FAILURE);

It is important to note that if S were declared as an array of characters, e.g.,

     char S[256];

     char *S_Ptr = S;

One should not make the mistake of trying to use the same address for different variables as the following example illustrates:

     int do_not_try_this (void)
     {
        static char *names[3] = {"larry", "curly", "moe"};
        unsigned int i;

        for (i = 0; i < 3; i++)
          {
             int value;
             if (-1 == SLadd_intrinsic_variable (names[i], (VOID_STAR) &value,
                                                 SLANG_INT_TYPE, 1))
               return -1;
          }
        return 0;
     }

The most convenient method for adding many intrinsic variables to the interpreter is to create an array of SLang_Intrin_Var_Type objects and then add the array via SLadd_intrin_var_table. For example, the array

    static SLang_Intrin_Var_Type Intrin_Vars [] =
    {
       MAKE_VARIABLE("I_Variable", &I, SLANG_INT_TYPE, 0),
       MAKE_VARIABLE("S_Variable", &S_Ptr, SLANG_STRING_TYPE, 1),
       SLANG_END_TABLE
    };

    if (-1 == SLadd_intrin_var_table (Intrin_Vars, NULL))
      exit (EXIT_FAILURE);

Finally, variables may be added to a specific namespace via the SLns_add_intrin_var_table and SLns_add_intrinsic_variable functions.

3.5 Aggregate Data Objects

An aggregate data object is an object that can contain more than one data value. The S-Lang interpreter supports several such objects: arrays, structure, and associative arrays. In the following sections, information about interacting with these objects is given.

Arrays

An intrinsic function may interact with an array in several different ways. For example, an intrinsic may create an array and return it. The basic functions for manipulating arrays include:

   SLang_create_array
   SLang_pop_array_of_type
   SLang_push_array
   SLang_free_array
   SLang_get_array_element
   SLang_set_array_element

The first example shows how to create an return an array of strings to the interpreter. In particular, the names of the four seasons of the year will be returned:

    void months_of_the_year (void)
    {
       static char *seasons[4] =
         {
            "Spring", "Summer", "Autumn", "Winter"
         };
       SLang_Array_Type *at;
       int i, four;
       
       four = 4;
       at = SLang_create_array (SLANG_STRING_TYPE, 0, NULL, &four, 1);
       if (at == NULL)
         return;
       
       /* Now set the elements of the array */
       for (i = 0; i < 4; i++)
         {
           if (-1 == SLang_set_array_element (at, &i, &seasons[i]))
             {
                SLang_free_array (at);
                return;
             }
         }
      
      (void) SLang_push_array (at, 0);
      SLang_free_array (at);
    }

    SLang_set_array_element (at, &i, seasons[i])

   (void) SLang_push_array (at, 0);
   SLang_free_array (at);

   (void) SLang_push_array (at, 1);

The second example returns a diagonal array of a specified size to the stack. A diagonal array is a 2-d array with all elements zero except for those along the diagonal, which have a value of one:

   void make_diagonal_array (int n)
   {
      SLang_Array_Type *at;
      int dims[2];
      int i, one;

      dims[0] = dims[1] = n;
      at = SLang_create_array (SLANG_INT_TYPE, 0, NULL, dims, 2);
      if (at == NULL)
        return;
      
      one = 1;
      for (i = 0; i < n; i++)
        {
           dims[0] = dims[1] = i;
           if (-1 == SLang_set_array_element (at, dims, &one))
             {
                SLang_free_array (at);
                return;
             }
        }
      
      (void) SLang_push_array (at, 1);
   }

Now consider an example that acts upon an existing array. In particular, consider one that computes the trace of a 2-d matrix, i.e., the sum of the diagonal elements:

   double compute_trace (void)
   {
      SLang_Array_Type *at;
      double trace;
      int dims[2];

      if (-1 == SLang_pop_array_of_type (&at, SLANG_DOUBLE_TYPE))
        return 0.0;
      
      /* We want a 2-d square matrix.  If the matrix is 1-d and has only one
         element, then return that element. */
      trace = 0.0;
      if (((at->num_dims == 1) && (at->dims[0] == 1))
          || ((at->num_dims == 2) && (at->dims[0] == at->dims[1])))
        {
           double dtrace;
           int n = at->dims[0];

           for (i = 0; i < n; i++)
             {
                dims[0] = dims[1] = i;
                (void) SLang_get_array_element (at, &dims, &dtrace);
                trace += dtrace;
             }
        }
     else SLang_verror (SL_TYPE_MISMATCH, "Expecting a square matrix");
     
     SLang_free_array (at);
     return trace;
   } 

Structures

For the purposes of this section, we shall differentiate structures according to whether or not they correspond to an application defined C structure. Those that do are called intrinsic structures, and those do not are called S-Lang interpreter structures.

Interpreter Structures

The following simple example shows how to create and return a structure to the stack with a string an integer field:

    int push_struct_example (char *string_value, int int_value)
    {
       char *field_names[2];
       unsigned char field_types[2];
       VOID_STAR field_values[2];
       
       field_names[0] = "string_field";
       field_types[0] = SLANG_STRING_TYPE;
       field_values[0] = &string_value;
       
       field_names[1] = "int_field";
       field_types[1] = SLANG_INT_TYPE;
       field_values[1] = &int_value;
       
       if (-1 == SLstruct_create_struct (2, field_names, 
                                            field_types, field_values))
         return -1;
       return 0;
    }

Intrinsic Structures

Here we show how to make intrinsic structures available to the interpreter. The simplest interface is to structure pointers and not to the actual structures themselves. The latter would require the interpreter to be involved with the creation and destruction of the structures. Dealing with the pointers themselves is far simpler.

As an example, consider an object such as

    typedef struct _Window_Type
    {
       char *title;
       int row;
       int col;
       int width;
       int height;
    } Window_Type;

We can make variables of type Window_Type available to the interpreter via a table as follows:

   static SLang_IStruct_Field_Type Window_Type_Field_Table [] =
   {
     MAKE_ISTRUCT_FIELD(Window_Type, title, "title", SLANG_STRING_TYPE, 1),
     MAKE_ISTRUCT_FIELD(Window_Type, row, "row", SLANG_INT_TYPE, 0),
     MAKE_ISTRUCT_FIELD(Window_Type, col, "col", SLANG_INT_TYPE, 0),
     MAKE_ISTRUCT_FIELD(Window_Type, width, "width", SLANG_INT_TYPE, 0),
     MAKE_ISTRUCT_FIELD(Window_Type, height, "height", SLANG_INT_TYPE, 0),
     SLANG_END_TABLE
   };

     MAKE_ISTRUCT_FIELD(Window_Type, title, "title", SLANG_STRING_TYPE, 0),

Now suppose that My_Window is a pointer to a Window_Type object, i.e.,

    Window_Type *My_Window;

    if (-1 == SLadd_istruct_table (Window_Type_Field_Table,
                                   (VOID_STAR) &My_Window,
                                   "My_Window"))
      exit (1);

     define set_width_and_height (w,h)
     {
         My_Win.width = w;
         My_Win.height = h;
     }

It is extremely important to understand that the interface described in this section does not allow the interpreter to create new instances of Window_Type objects. The interface merely defines an association or correspondence between an intrinsic structure pointer and a S-Lang variable. For example, if the value of My_Window is NULL, then My_Win would also be NULL.

One should be careful in allowing read/write access to character string fields. If read/write access is allowed, then the application should always use the SLang_create_slstring and SLang_free_slstring functions to set the character string field of the structure. Finally, note that access to character array fields is not permitted via this interface. That is, a structure such as

     typedef struct
     {
        char name[32];
     }
     Name_Type;