The SIMION SL™ Toolkit (version 1.2.1.0 - 2004-11-09) | |
The Simple SIMION Language (SL)™: A Tutorial(c) 2003-2004 Scientific Instrument Services, Inc. Created November 2003 by David Manura. Updated $Date: 2004/07/22 05:15:27 $.
AbstractThis document provides an introduction only on how to operate the SL Compiler tool. This document assumes you have already installed SL (install.html). For details on the SL language and syntax itself, see the Language Reference (compiler_ref.html). |
|
For your first test-drive, let's write a very simple SL program that does nothing but output ``Hello World!'' within SIMION upon completion of the ion flights.
First, create a text-file named ``hello.sl''. (A convenient place for this is in the ``c:\sim7\sl\user_files'' directory, although you may place the file anywhere.) Open this file up in your favorite text editor (or right click on it and select ``SIMION: Edit'' from within the pop-up menu). Now, enter the following text into this file and save it:
# my first SL program sub terminate print("Hello World!") endsub
Now that we have authored the SL program, we need to compile it into a PRG file that SIMION can understand. To do so, right click on the file within Windows Explorer and choose ``SIMION: Compile'' from the pop-up menu.
If everything is successful (e.g. no typing errors), a compiled hello.prg file will be created in that same folder and automatically opened in a text editor as a confirmation. This file should appear something as follows:
SEG terminate
; This PRG file was automatically generated from SL source code
; using the SIS Simplified SIMION Compiler (SL).
; WARNING: This file will be overwritten if you recompile.
SEG terminate
MESS ;Hello World!
EXIT
If, however, there was a typing error in your program, the error message will be displayed within this file as such:
; COMPILATION ERRORS:
;
; Error on line #2:
;
; # my first SL program
; sub t erminate <--[ERROR]
; print("Hello World!")
;
; [E44] Invalid subroutine: Expected "paren_identifier_list"
; but found " erminate\n print("Hello World!")".
;
MESS ; SL COMPILE FAILED
The error message shows you where the error was (i.e. line #2) and provides a diagnosis.
Now, to actually run this program in SIMION, create a potential array in the same directory and having same base name (i.e. ``hello.pa#''), adjust it, and simulate it within the SIMION Ion Optics Workbench. SIMION will utilize the generated hello.prg whenever ions are flying within the hello.pa# array. (We assume that the reader is already very familiar with such steps.)
End of first voyage.
You may prefer performing the above process entirely within the SL Editor (editor.html) framework. To do so, right click on the hello.sl file in Windows Explorer and select ``SIMION: Edit''.
By default, the SL program will open in the VIM text editor. Note the syntax highlighting.
To compile, click the hammer button (circled in red above). If successful, the below ``success'' message will display:
On failure, an error message will display, and, after pressing enter, you will be taken to the line on which the error occurs.
The SL Compiler comes with various example programs in the ``examples'' directory. (Browsable versions of many of the examples are in compiler_examples.html.) Take a look at the various SL files to gain a better understanding of the SL syntax. Try also compiling the SL files into PRG code.
Although the point-and-click method (``SIMION: Compile'') for compiling SL files will work for most users, others may find it useful to instead compile SL files from the command-line. If you don't know what a command-line is and are wondering why it's useful for lines to be commanded, you may skip this section entirely, albeit remaining in ignorance of The Better Way(TM).
First, ensure that during installation you had taken the steps necessary so that SL would be easily accessible from the command line by adding the ``<sl>\bin'' directory (typically ``c:\sim7\sl\bin'') to your system PATH. Refer back to the installation section (install.html) for details.
Now, open up a command window (Start | Run | ``cmd'' or ``command'' from the Windows Taskbar) and navigate to your the directory containing your SL file:
c: cd c:\sim7\sl\user dir
Your hello.sl file should display in the directory listing (dir). Now compile hello.sl as such:
sl hello.sl
If all is successful, you will see
success
and by doing a directory listing
dir
it will list the generated hello.prg as well. You open any file in a text editor as such
notepad hello.prg
If, however, there is an error in your program upon running ``sl hello.sl'' above, then an error message will be displayed to your screen.
To see the list of additional options you can pass to SL on the command-line do a
sl
which will display something such as
SL - The Simple SIMION Compiler
(c) 2003, Scientific Instrument Services, Inc. All Rights Reserved.
usage: sl [options...] programfiles...
--quiet quiet mode
--output filename set output file (defaults to programfile.prg
when compiling)
--gui display results in text editor
--format render SL code as HTML (don't compile)
--help displays this help info
programfiles is a space-delimited list of SL files to compile.
Use a dash (-) to read SL from standard input.
advanced options:
--noperl disable processing embedded Perl in SL
--noremote disable remote call support in SL
--noimport disable import statement in SL
example:
sl buncher.sl
If the output scrolls past your screen, you may wish to paginate it:
sl | more
The command-line that comes with Windows, however, is fairly primitive. A UNIX emulator such as the free Cygwin (http://www.cygwin.com) is often preferred and was used during the development of SL.
The ``PROJECT.txt'' file in the SL program directory contains various global compiler settings. The meaning of these settings are documented in the comment lines (those preceded by a ``#'') within this file. The PROJECT.txt file allows you to change things such as the following.
To learn about how to write SL code, see the SL Language Reference (compiler_ref.html).