Synopsis

Evaluate and run S-Lang code.

slsh [OPTIONS] [[-|file] [arguments...]]
slsh --help

Description

The slsh program evaluates the S-Lang code given to it, either as a file or read from STDIN (the "-" option). All functions and variables in the S-Lang Run-Time library can be used, and slsh adds several additional functions, as described in the "Functions and Variables available in slsh" section.

Command-line options

The following options can be used with slsh:

Note: - and -i are mutually exclusive

Getting Help in slsh

To get information on a particular S-Lang function, use the "help" command:

slsh>  help time
time

 SYNOPSIS
  Return the current date and time as a string

 USAGE
  String_Type time ()

 DESCRIPTION
  This function returns the current time as a string of the form:

    Sun Apr 21 13:34:17 1996


 SEE ALSO
  strftime, ctime, message, substr

Example 1

unix% slsh myprog.sl

This command will execute the code in the file myprog.sl. Note that the files do not have to end in ".sl", but it is a useful idiom. If the contents of myprog.sl were:

  vmessage( "The time is %s.", time() );

then the output would look something like:

  unix% slsh myprog.sl
  The time is Fri Mar 19 11:28:40 2004

Both the vmessage() and time() functions are part of the S-Lang Run-Time Library, and so are available for use by slsh.

Example 2

If you start a S-Lang script with the line

#!/usr/bin/env slsh

and set it to be an executable, then you can run the script without having to explicitly call slsh. So if the file myprog.sl looked like:

  #!/usr/bin/env slsh
  vmessage( "The time is %s.", time() );

then the script could be run by just saying:

  unix% ./myprog.sl
  The time is Fri Mar 19 11:28:40 2004.

assuming that

chmod u+x myprog.sl

had previously been called. The following examples will use this method.

Example 3

Code that uses CIAO modules can also be run using slsh. All that needs to be done is to load the required modules before using any functions they define. In the following example we use the region module to calculate the area of a simple region.

  unix% cat reg.sl
  #!/usr/bin/env slsh
  require("region");
  variable reg = regParse( "circle(4300.45,3274.22,60.3)" );
  vmessage( "The region area is: %7.2f", regArea(reg) );

which, when run, produces

  unix% ./reg.sl
  The region area is: 11423.11

Example 4

Command-line arguments that are not recognised by slsh are made available to the S-Lang code via the __argc and __argv variables. These are analogous to the argc and argv variables of the main() routine in C code. We can use these variables to enhance the previous example to allow regions to be specified on the command line, rather than being written into the code.

  unix% cat reg2.sl
  #!/usr/bin/env slsh

  % check called correctly
  %
  if ( 2 != __argc ) {
    () = fprintf( stderr, "Usage: %s <region>\n", __argv[0] );
    exit(1);
  }

  require("region");

  % has the user given us a valid region?
  %
  variable reg = regParse( __argv[1] );
  if ( NULL == reg ) {
    () = fprintf( stderr, "Did not recognise %s as a region!\n",
                  __argv[1] );
    exit(1);
  }

  % print out the region area
  %
  vmessage( "The region area is: %7.2f", regArea(reg) );

The code has been enhanced to check that the correct number of arguments has been given and that the user-supplied argument is recognised as a region. As an example of its use:

  unix% ./reg2.sl
  Usage: ./reg2.sl <region>
  unix% ./reg2.sl "circle(4200,3200,60.3)"
  The region area is: 11423.11
  unix% ./reg2.sl "annulus(4200,3200,10,60.3)"
  The region area is: 11108.95

FUNCTIONS AND VARIABLES AVAILABLE IN SLSH

When evaluating S-Lang code by slsh you can take advantage of the following functions and variables: __argc; __argv; exit(); atexit(); and stat_mode_to_string().

__argc

This is a read-only integer variable which contains the number of arguments on the command line. It is analogous to the argc argument of the main() function in the C language.

__argv

This is a read-only String_Type array which contains the arguments on the command line. It is analogous to the argv argument of the main() function in the C language.

exit(status)

This function terminates the slsh program and uses the value of the argument (status) as the exit status. All hooks set up by the atexit() function are called before slsh exits.

atexit(function)

The atexit() function tells the system to call the supplied function (which should be sent in as a S-Lang reference) when the interpreter is about to exit due to a call to exit(). These functions are not called if the code finishes without explicitly calling exit().

The functions are pushed onto a stack which is then popped from on exit, so the function used in the last call to atexit() will be the first one called.

stat_mode_to_string(mode)

This function converts the mode of a file (the st_mode field of the structure returned by the stat_file() function) to a string in the format used by "ls -l"; e.g. "-rw-r--r--" for a file which everyone can read but only the owner can change.

ACKNOWLEDGEMENTS

The information in this page was partly taken from documentation of the S-Lang distribution, available from the S-Lang home page.