path: root/libslang/UPGRADE.txt

This document consists of two parts.  The first part describes some
changes to the interpreter that may affect existing slang macros.  The
second part describes changes that may affect applications that use
the library.

Part 1: Interpreter Changes.
============================

Changes to the slang syntax.
---------------------------
 The syntax has not changed too much since version 0.99-XX.  However
 there are a few changes that you need to be aware of so that you can
 modify your slang functions accordingly.  See slang/doc/* for more
 information about slang version 1.0.
 
 To help track areas where you code needs changed, add the following
 line to the top of each file that you load into the interpreter:
 
     _debug_info = 1;

 This will cause extra debugging information to get generated.

 The important differences that you must be aware of are listed below:

 * The parser is more sensitive to missing semi-colons.  For that
   reason, you may experience some parse errors.  Make sure each
   statement is terminated by a semi-colon.

 * The switch statement has changed--- it is cleaner.  In particular,
   the `pop' in the default case should be removed.  For example, in
   0.99-XX, the object was pushed onto the stack before each switch
   case block was executed.  In 1.0, the switch statement nolonger
   works this way.  So, if you currently have code that looks like:
       
          switch (x)
	  { case 1:                  do_something () }
	  { case 2 or case (x, 3):   do_something_else () }
	  { () > 7:                  do_big_thing ();
	  { pop ();                  do_default () }
	  
   
   You must change it to:

          switch (x)
	  { case 1:                  do_something (); }
	  { case 2 or case 3:        do_something_else (); }
	  { x > 7:                   do_big_thing (); }
	  {                          do_default (); }

   Note that this example also illustrates that you may need to insert
   some semi-colons to terminate statements.  In any event, it is a
   good idea to study your switch statements very carefully.

 * The `create_array' function has been eliminated in favor of a new,
   cleaner mechanism.  For example, instead of using
   
         a = create_array ('s', 10, 20, 2);
	 
   to create a 10x20 array of strings, you must now use
   
         a = String_Type [10, 20];
 
   Similarly, use `Integer_Type [10, 20]' to create a 10x20 array of
   integers.  [Note for JED users: See jed/lib/compat.sl for an
   implementation of create_array]
   
 * The semantics of the ``alias'' operator `&' has changed in a much
   more useful way.  Briefly, if you have code that looks like:
   
         define exec_function (f)
	 {
	    variable x = 1.0;
	    return f(x);
	 }
	 
	 variable y = exec_function (&sin);

   Then you must change it to:
   
         define exec_function (f)
	 {
	    variable x = 1.0;
	    return @f(x);
	 }
	 
	 variable y = exec_function (&sin);

   where `@' is a ``dereference'' operator.
   
 * Several intrinsic functions have changed and a few have been
   removed, or renamed.  See the documentation in slang/doc/ for more
   detailed information about each function.

   Functions ones that have been removed or renamed include:

     create_array
        Use simpler syntax, e.g.,  x = Integer_Type [10];

     _obj_info
        Use the new `typeof' function.  See documentation for more
	information.
	
     print_stack has been renamed to _print_stack
     
     `slapropos' has been renamed to `_apropos'.  It also takes an
     additional argument.
	
     `float' has been renamed to `double'.  See also `atof'.
     
     `slang_trace_function' renamed to `_trace_function'
     
     `pop_n' has been renamed to `_pop_n'
     
   The semantics of the following functions have changed:
   
      `fopen': 
         It now returns NULL upon failure.  Change code such as
      
            fp = fopen (file, "r");
	    if (fp == -1) error (...);

         to:

            fp = fopen (file, "r");
	    if (fp == NULL) error (...);
      
      `getenv', `extract_element':
         These return NULL upon failure instead of "".  This means code 
	 that looks like:
	   
	    n = 0;
	    while (elem = extract_element (list, n, ','), strlen(elem))
	      {
	         n++;
		 .
		 .
	      }

	 should be changed to:
	 
	    n = 0;
	    while (elem = extract_element (list, n, ','), elem != NULL)
	      {
	         n++;
		 .
		 .
	      }

      `fclose': It now returns -1 upon failure and sets errno, or 0 if
          successful. Previously, it returned 0 upon failure and 1
	  upon success. 
      
      `fgets': It now returns just 1 value but takes a reference as an
          argument.  That is, replace code such as:
	  
	    while (fgets (fp) > 0)
	      {
	         buf = ();
		 .
		 .
	      }
	     
	  with:
	  
	    while (-1 != fgets (&buf, fp))
	      {
	         .
		 .
	      }
	    

Part 2:  C interface changes
============================

[Please review slang/doc/text/cslang.txt for information regarding
 embedding the interpreter]

There have been many, many changes since 0.99-XX.  Most of the changes
concern the interpreter and the interpreter interface.  Other aspects
of the library, e.g., SLsmg, etc have not changed too much.  I made
every attempt to maintain as much backward compatibility as possible,
weighing the pros and cons of every change.  I think that I arrived at
a reasonable compromise, and, hopefully, you will agree.

When recompiling your application, make sure that you compile it with
warnings turned on so that prototype changes may be detected.

-----------------------------------------------------------------------
The way objects are accessed internally by the interpreter has changed
dramatically.  This has important ramifications for an any application
embedding the interpreter.  In particular, the way intrinsic objects
are made available to the interpreter has changed.

In 0.99-XX, the standard procedure was to use the MAKE_INTRINSIC macro
inside an array of SLang_Name_Type, e.g.,

    void c_fname (void) { ... }
    char *String_Variable;
    int Int_Variable;
    char String_Buf[256];

    static SLang_Name_Type My_Intrinsics [] = 
    {
       MAKE_INTRINSIC(".fname", c_fname, VOID_TYPE, 0),
       MAKE_VARIABLE(".string_vname", String_Variable, STRING_TYPE, 1),
       MAKE_VARIABLE(".string_buf_vname", String_Buf, STRING_TYPE, 1),
       MAKE_VARIABLE(".int_vname", &Int_Variable, INT_TYPE, 0),
       SLANG_END_TABLE
    };

In the new version, variables and intrinsics cannot be grouped in the
same table.  Instead two tables must be used:

    static SLang_Intrin_Fun_Type My_Intrinsic_Funs [] =
    {
       MAKE_INTRINSIC("fname", c_fname, VOID_TYPE, 0),
       SLANG_END_TABLE
    };
    
    char *String_Buf_Ptr = String_Buf;
    static SLang_Intrin_Var_Type My_Intrinsic_Funs [] =
    {
       MAKE_VARIABLE("string_vname", &String_Variable, STRING_TYPE, 1),
       MAKE_VARIABLE("int_vname", &Int_Variable, INT_TYPE, 0),
       MAKE_VARIABLE(".string_buf_vname", &String_Buf_Ptr, STRING_TYPE, 1),
       SLANG_END_TABLE
    };
    
Note that the `.' is no longer required to be the first character in
the name.  Also, the `&' address operator must be used for all
variables in the MAKE_VARIABLE macro.  Finally, intrinsic STRING_TYPE
variables must be pointers and not arrays.  This is the reason
String_Buf_Ptr was introduced.

You are encouraged to read the documentation about embedding the
interpreter because it is now possible to ensure that variables passed
to an intrinsic are type checked.  See slang/slstd.c for examples.

------------------------------------------------------------------------
0.99-XX had a very inconsistent interface.  For example, while some
functions returned 0 upon success, others returned 0 to indicate
failure.  One of the major changes to the library was to provide a
consistent return value to indicate error.  In this version, -1
indicates an error and 0 indicates success.  In particular, the
following functions were affected:

   SLdefine_for_ifdef
   SLang_execute_function
   SLexecute_function
   SLang_run_hooks
   SLang_load_object
   SLang_pop_*
   SLang_push_*
   SLsmg_resume_smg
   SLsmg_suspend_smg
   SLtt_init_video
   SLtt_reset_video

Another change involved the name space.  All external symbols now
start with `SL'.  To this end, the following functions have been
renamed:

    init_SLmath -->     SLang_init_slmath
    init_SLunix -->     SLang_init_slunix
    init_SLang -->      SLang_init_slang
    init_SLfiles -->    SLang_init_slfile
    slang_add_array --> SLang_add_intrinsic_array

Some other functions were renamed when the interface changed:

    SLang_extract_list_element --> SLextract_list_element
    SLang_Error_Routine --> SLang_Error_Hook

Some functions were not renamed but do have different prototypes:

    int SLang_run_hooks(char *, unsigned int, ...);

Some functions are nolonger available or have been replaced by newer,
more flexible versions:

    SLadd_name --> SLadd_intrinsic_variable, SLadd_intrinsic_function
    SLang_pop/push_float --> SLang_pop/push_double


Typedef Modifications
---------------------
SLang_Load_Type: The interface has been completely rewritten.  See
  the documentation.
  
Preprocessor defines:
--------------------
  __SLMATH__ if math functions available (SLang_init_slmath)
  __SLUNIX__ if unix functions available (SLang_init_slunix)
  __SLFILE__ if file I/O functions available (SLang_init_slfile)