[SparForte][Banner]
[Top Main Menu] Intro | Tutorials | Reference | Packages | Examples | Contributors   [Back Page]      [Next Page]  

Script Tutorial 1: Basic Commands Scripts

This section discusses how to assemble SparForte into runnable programs called "scripts". It also covers basic features related to writing scripts.

Comments

SparForte comments begin with a double minus sign. Any text following the comment sign to the end of the line are treated as explanatory text. For example,

=> null; -- SparForte is great

Comments are not very useful at the command prompt but they are very useful in scripts.  A script is collection of SparForte commands stored in a file.

Running Commands

One crude way to get SparForte to execute commands is to redirect the commands through standard input. For example, from BASH you could type

bash$ echo "? \"Hello World\" ; return" | spar
Type "help" for help
=> ? "Hello World" ; return
Hello World

Notice the login prompt appears. SparForte treats this as if it was an interactive session with a human user. Command prompts are written to the screen and the keyword return is necessary to terminate the session.

A better way to run short commands is to use the --exec option.

bash$ spar --exec "? \"Hello World\";"
Hello World

However, typing a long set of commands on the command prompt would be difficult.

How Scripts Differ from the Command Prompt

For a large set of commands, a better way to execute them is to write a script. A script has these advantages:

  • It will run faster because SparForte compiles scripts into its own internal byte code
  • Compound statements can be used on multiple lines
  • Command prompts and other interactive session displays will not appear

Commands typed into a script are treated slightly differently than those in an interactive session:

  • The semi-colon at the end of each command is required.
  • All variables must be declared before they are used. Assigning a value to an undeclared variable is an error. (In an interactive session, SparForte can automatically declare the variable with a warning.)
  • logout will not stop a script. Use return or let the script reach the end of file.

The first two items are necessary because in a script there's no user to interact with the commands. SparForte cannot not make assumptions or take any automatic actions.

A First Script

By convention, SparForte shell scripts have file names ending with ".sp". The following is a script called "hello.sp", a very short script to write a message on the screen.

-- hello.sp
-- this is my first SparForte script
put_line( "Hello! SparForte is wonderful." );
command_line.set_exit_status( 0 );
 

Example: A First Script

put_line and set_exit_status are built-in procedures. put_line, part of the Text_IO package, displays a message on the screen. set_exit_status(0) informs the program which ran your shell script that the script ran successfully.

You can run your shell script

=> spar hello.sp

If there are no mistakes, SparForte will respond with the message.

Hello! SparForte is wonderful.

Flow of Control

Conditional statements are SparForte constructs for making choices and providing alternative instructions. Use the if statement to make choices. The if statement can have optional elsif or else parts.

current_day : calendar.day_number := calendar.day( calendar.clock );
if current_day = 1 then
   ? "It is the first day of the month!";
end if;
 

Example: A First If Statement

The case statement can be used for decisions involving many individual values. The final "when" must always be "when others", which includes all other values not covered by the other "when"'s.

current_day : calendar.day_number := calendar.day( calendar.clock );
put( "It is the" );
case current_day is
when 1 => put( " first" );
when 2 => put( " second" );
when 3 => put( " third" );
when 4 => put( " fourth" );
when 5 => put( " fifth" );
when 6 => put( " sixth" );
when 7 => put( " seventh" );
when 8 => put( " eighth" );
when 9 => put( " ninth" );
when others => put( current_day ) @ ( "th" );
end case;
put_line( " day of the month" );
 

Example: A First Case Statement

The @ character (pronounced "itself") has two different uses in SparForte. When used at the end of a command or procedure call, @ will call the command or procedure again with a new set of parameters. Combining parameter lists with @ is called a chain. @ is especially useful with the put procedure to output several items without having to do string conversions and a long, hard to read expression.

Loops

There are several looping statements. The for loop will repeat a set of commands a specific number of times or over a specific range of numbers. The variable in the for loop doesn't need to be declared: SparForte will declare it for you automatically. A while loop will repeat a set of commands until something becomes true. A loop loop will loop indefinitely until you break out of the loop with an exit command.

for i in 1..10 loop
   put( i ) @ ( " times 2 is" ) @ ( i * 2 );
   new_line;
end loop;
 

Example: A First For Statement

The End of a Script

The logout command, which ends an interactive login session, cannot be used to stop a script. (After all, a script is not a login session.) Instead, use the return command to unconditionally stop a script and return control to the calling program or person. Set the exit status to zero to indicate there is no error.

Scripts automatically stop when it reaches its end as if there was an implicit "return" typed there.

The Delay Command

Scripts can be paused using the built-in delay command. delay will suspend the script for a specific number of seconds after which it will wake up and resume the next statement after the delay command. The number of seconds can include a fractional part.

delay 5.5; -- wait for 5 1/2 seconds
 

Example: The Delay Statement

delay is useful for putting pauses in a script, allowing the user to read what's been displayed. delay isn't suitable for synchronizing events, however, because how long a particular program runs on the computer often depends on the system load, the number of users, hardware upgrades and other factors outside of the script's control.

Study Questions

  1. What does spar -e "spar -e '? \"Hello\";';" do?
  2. What do you need to do to run "spar --break somescript.sp"?
  3. What happens when "ls" is both a command and a procedure?
  4. What is the advantage of requiring a "when others" clause in a case statement?
 
[Right Submenu]

 Command Prompt Tutorial 1: SparForte as a Calculator

 Command Prompt Tutorial 2: Basic Shell Commands

 Command Prompt Tutorial 3: Working with Databases

 Script Tutorial 1: Basic Commands Scripts

 Script Tutorial 2: Intermediate Program Scripts

 Script Tutorial 3: Data Types

 Template Tutorial 1: Basic Templates

 Template Tutorial 2: Intermediate Templates

 GCC Tutorial: Compiling SparForte Scripts

 Debugging Tutorial - Using the SparForte Debugger

 Creating a Profile Script

 Calling SparForte from C: A Tutorial

 SparForte For PHP Developers

 SparForte Best Practices

[Back to Top] Back To Top [Small Forte Symbol]