Copyright: Frogbit V0.97 Copyright (c) Axiomatic Software 1996, 1997


Overview of Help

Frogbit help is broken down into topic areas so that you can quickly get the sort of help that you need.

If you click the Contents button at the top of this window you will see a number of headings (“Quick Start”, “Introduction” etc.).  Each heading covers a number of related topics, double-click a heading to show/hide its topics.

Now select one of the headings according to your general needs at this point :-

Beginners

Start with Introduction — or if you’re in a hurry try Quick Start.

Programmers new to Frogbit

Try Introduction and Quick Start.  Or you could look at some of the Examples and try running them from the IDE.  The Recipes section might be helpful too.

I want to write a program

If you haven’t started writing your program yet take a look at the Project Wizard or the Recipes heading.

I need to look something up

To look up a command or operator try clicking on the Index button at the top of this window and then select Index or Find from the top of the new window.

I want to browse through the commands and operators

Click on the Contents button at the top of this window and then select Reference.


What's New in V0.97
What’s New in V0.97

Note: this is since V0.95 because V0.96 was not publicly released.

In the IDE

•	A Project Wizard to give you a head-start in writing a program.

•	Project Notes so that you can keep notes about your program with the project.

•	Improved Run/Command Line dialog box.

•	More information is shown about the variable being monitored by a file-view window.

In the RUN program

•	A convention whereby you can be prompted for command-line arguments.

In the Programming Language

New Commands

•	refresh for updating the IDE’s debugging display.

•	status for writing to the IDE/RUN’s status line.

New Command Keywords

•	withSubdirs and withHidden in the for each command to search sub-directories, include hidden files.

•	withLast copy lines command to include the tested line in the copy.

•	= in the set command is now an alternative for equal to.

New Operators

•	dlmBy..at to select delimited fields from a record.

•	withAll..replacedBy to replace all occurrences in a string.

•	someLeft and noneLeft to replace the eof special variable.

•	lineNo, linesIn and @ for access to the inside of file-variables.

•	nextLineIn for looking ahead when reading an input file.

•	|| to generate permutations of data.

•	asLines for a neat way to represent multi-line strings.

•	after, before, except and exceptAll.

•	atIndex..len to extract a substring from a string.

•	Case-insensitive versions of comparison operators such as =, <>, contains etc.

•	length to return the length of a string

New Special Variables

•	found to indicate the outcome of the copy lines and skip lines commands.

•	nextLine for looking ahead when reading an input file.

Bugs Fixed

(not detailed here)


Quick Start: Starting the Frogbit IDE

If you haven’t already done so, run the Frogbit IDE from the Frogbit program group.  In Windows 95 :-

•	press control+escape

•	select Programs

•	select Frogbit

•	select Frogbit IDE

The main window of the IDE is split into two :-

•	on the left is a text box; this is where the Frogbit program is edited

•	on the right is a grid; this shows the values of variables when the program is run

More about the Main Window

First of all you need a program to run :-

•	you could write a new program from scratch by just typing it into the text box

•	.. or use the Project/Wizard menu-entry to generate a skeleton project for you

•	.. or load an existing project using the Project/Open menu entry.

Try loading one of the projects in the examples sub-directory.  Read through the program and the comments (lines starting with “//”) to get some idea of what it does and how it works.  You may also find the project’s notes useful.

Running the Program

Controlling Program Execution

Tracking Intermediate Results


Main Window
The IDE Main Window

Click on the picture below to get help on a particular menu, button or control :-


Project Menu

New

Wizard

Open

Save

Save As

1. (recent file)

Exit


Edit Menu

Cut

Copy

Paste

Find

Find Next

Replace


View Menu

Watches

Highlight

Notes

Profile


Run Menu

Check

Go

Pause

Halt

Step

AutoStep

Command Line


Tools Menu

Options

Fonts


Help Menu

Help Topics

Word Under Cursor

www.axiomati.demon.co.uk

About


Program Popup Menu

Cut

Copy

Paste

Find

Replace

Add Watch

Add File-View


Watches Popup Menu

Add

Edit

Delete

File-View


 Project/New

Starts a new Frogbit project.  The program text, all watches and all file-views are cleared.

If there is a project already loaded when you select this command it will be saved automatically if it is named, otherwise you will be prompted to enter a file name.


 Project/Wizard

Invokes the Project Wizard; a series of dialogs which prompt you for details of a new Frogbit project.

If and when you click on the Finish button in the last wizard dialog box the current project’s program text, watches and file-views are cleared and the wizard-generated project replaces it.


 Project/Open

Opens a Frogbit project from a file.  The program text, watches, file-views and window positions are all restored to their last saved settings.

If there is a project already loaded when you select this command it will be saved automatically if it is named, otherwise you will be prompted to enter a file name.


 Project/Save

Saves a Frogbit project to a file.  The program text, watches, file-views and window positions are all saved.

If the project has been saved before it will already be associated with a particular file, otherwise you will be prompted to enter a file name.


Project/Save As

Saves a Frogbit project to a file other than the one it is currently associated with.  You will be prompted to enter a new file name.


Project/1-4

Opens a recently-used Frogbit project from a file.  The program text, watches, file-views and window positions are all restored to their last saved settings.

If there is a project already loaded when you select this command it will be saved automatically if it is named, otherwise you will be prompted to enter a file name.


Project/Exit

Exits from Frogbit.

If there is a project loaded when you select this command it will be saved automatically if it is named, otherwise you will be prompted to enter a file name.


 Edit/Cut

Makes a copy of the selected text to the Windows clipboard and then deletes the selected text.


 Edit/Copy

Copies the selected text to the Windows clipboard.


 Edit/Paste

Inserts text from the Windows clipboard into the program text; any currently selected text is deleted.


 Edit/Find

Prompts you to enter a string to find in your program text.


 Edit/Find Next

Searches for the next occurrence of a string you looked for using Edit/Find.


 Edit/Replace

Prompts you to enter a pair of strings to substitute one for the other in your program text.


 View/Watches

Switches between showing and hiding the watches window.

You can resize the watches window by dragging the splitter bar between the program text and the watches window.


View/Highlight

Re-highlights the current line in the program text.

A line in your program can be highlighted for one of these reasons :-

•	when your program is compiled and a syntax error is found — the line in question is highlighted

•	when your program is being run and is paused — the next line to be executed is highlighted

Note: if you delete or insert lines and then select View/Highlight it will highlight the wrong line.


View/Notes

Shows the notes window and makes it current.  To hide notes, close the notes window.

Notes are just text associated with the project.  You type some text into the notes window and it will be saved and reloaded along with the project.

The text can be anything you like but here are some ideas :-

•	what the program does

•	instructions on how to use it

•	command-line arguments required

•	any fixed files or directories used

•	known bugs

•	ideas for improvements to the project


View/Profile

Displays a window showing the timings and counts for the last program run.

Note 1: Some statements (such as elseif) may have two entries in this table.  This is a known anomaly.

Note 2: refresh commands can slow a program down quite a lot but take no time according to the profile.  This is because the profile times server activity and the refresh command triggers activity in the IDE rather than in the server.  However, refresh commands do not slow down a program run using FrogbitRUN.


We haven’t decided whether it’s a bug or a feature yet.


 Run/Check

Checks the syntax of your program and compiles it into code if there are no errors.

You don’t need to check your program explicitly — if you select Run or Step the program will first be compiled if necessary.


 Run/Go

Runs the program — either from the start or from where it is paused.  It will run until one of the following happens :-

•	the end of the program is reached

•	a runtime error occurs

•	a dialog box is cancelled

•	a pause command is executed

•	you select Run/Pause or Run/Halt


 Run/Pause

Pauses a running program.

You can then either continue running it from where it left off using Run/Go or Run/Step or you can reset it using Run/Halt.


 Run/Halt

Halts a running program or resets a paused one.

Once a program is halted you cannot continue it, you can only restart it from the beginning.


 Run/Step

Executes the next line of the program.


 Run/AutoStep

Runs the program one step at a time — just as if you repeatedly selected Run/Step.

This differs from Run/Go in that the display (current program line, watches, file-views) is updated after each line has been executed.

Auto-stepping stops when one of the following occurs :-

•	the end of the program is reached

•	a runtime error occurs

•	a dialog box is cancelled

•	a pause command is executed

•	you select Run/Pause, Run/Halt or Run/AutoStep

•	you press the Escape key


Run/Command Line

Displays a dialog box allowing you to set or edit the command line arguments for when the program is run inside the Frogbit IDE.

You can enter up to six arguments, one per line.

Command line arguments are available to your program through the arg operator.


Tools/Fonts

This is used to set the fonts for the Program Window, Watches Window, File-View windows and Notes window.  Font-settings apply to all projects.

Note: you are only allowed to select fixed-pitch fonts for the Program Window and File-View windows (trust us!).


Tools/Options

(this will be implemented in a later version of Frogbit)


Help/Help Topics

Displays the Contents|Index|Find dialog for the help file.


Word Under Cursor

Displays help for the highlighted word or the word under the cursor in the Program Window.


www.axiomati.demon.co.uk

Launches your web browser and connects to the Axiomatic Software home page for the latest version of Frogbit, the latest FAQ, new examples, hints and tips.


Help/About

Displays a dialog box with information about the program.


Add Watch (program popup menu)

Prompts you to add a variable or expression to the watch window.  It defaults to the current selection or to the word under the cursor.


Add File View (program popup menu)

Prompts you for a variable to track in a new file-view window.  It defaults to the current selection or to the word under the cursor.


Add Watch (watches popup menu)

Prompts you to add a variable or expression to the watch window.  It defaults to the current selection or to the word under the cursor.


Edit Watch (watches popup menu)

Prompts you to edit the currently-selected expression in the watch window.


Delete Watch (watches popup menu)

Deletes the currently-selected expression from the watch window.


File View (watches popup menu)

Prompts you for a variable to track in a new file-view window.  It defaults to the currently-selected expression in the watch window.


Program Text

This is where you enter and edit your program.


Watches Grid
Watches Window

This shows values for variables or expressions as your program runs.  Just type an expression into the empty last row of the left-hand column.


Status Line

Messages (such as compilation error-messages) are shown here.  You can write to it while your program is running by using the status command.


Quick Start: Running the Program

See Also

You can run your program in three different ways: Go, Step or AutoStep.

Whichever way you choose the program has to be compiled into code first of all.  If there is an error in your program the offending line will be highlighted and the error will be reported on the status line below the text box.

If there is no error in the program text then execution will begin.  Once you have begun running a program the text background changes from white to cyan and you can no longer edit the program.  You must reset the program using Run/Halt from the menu (or by pressing ctrl/H, or by clicking on the [image] button) if you want to edit it before the run has finished.

 Run/Go

This runs your program at “full-speed”.  It will run to completion unless an error occurs or you interrupt the program.  While the program is running the watches, file-views and program-position will not be updated unless a refresh command is executed.

You can use this either to run your program from the beginning all the way through or you can use it to continue your program after a pause.

 Run/Step

This executes the next line of your program, after which the program pauses.  The watches are re-calculated, the file-view windows are refreshed, and the next line to be executed is highlighted.

 Run/AutoStep

This runs your program one line at a time; it is as if you repeatedly chose Run/Step.

Run/AutoStep is like Run/Go inasmuch as the program will run to completion unless something happens to stop it, but it is also like Run/Step because the display is updated after each line of your program is executed.


Controlling Program Execution

Tracking Intermediate Results


Quick Start: Controlling Program Execution

See Also

After Run/Go

All you can do is either pause it or halt it completely :-

 Run/Pause

Stops the program after execution of the current line has been completed; you can then examine or add watches/file-views, continue the program by running or stepping it, or halt the program so that you can edit it.

 Run/Halt

Stops the program — in the middle of a line if necessary — and abandons the run.

After Run/Step

Since only a single line is being executed you won’t normally have time to interrupt the program but you can use [image] Run/Halt if you need to interrupt a lengthy command.

After Run/AutoStep

You have two options here :-

•	You can cancel auto-stepping using [image] Run/Pause, [image] Run/AutoStep, or by pressing the Escape key.  Execution of the current command will be completed and then the program will be paused.

•	You can use [image] Run/Halt to interrupt a lengthy command, this will also cancel auto-stepping.

Breakpoints

The current version of Frogbit does not support dynamic breakpoints — all you can do is put a pause command into your program text.

This is acknowledged to be a pain because you have to reset your program to edit it: a later version of Frogbit will allow a variety of different sorts of dynamic breakpoint.


Running the Program

Tracking Intermediate Results


Quick Start: Tracking Intermediate Results

See Also

When you are debugging a program you will often need to examine intermediate results of the execution.  You can monitor the values of variables or expressions in the watch window, while both input and output files can be monitored using file-view windows.  You can write a single line message to the status line using the status command.

The Watches and File-View windows are normally only updated when the program pauses.  You can achieve this by :-

•	single-stepping (Run/Step or F8)

•	auto-stepping (Run/AutoStep or F12)

•	putting a pause command into your program

Alternatively, you can put a refresh command into your program.  This lets you run the program at full speed but whenever the refresh command is executed the windows will be updated.

Watches

To the right of the program text is a grid containing two columns headed “Expression” and “Value”.  You can enter any Frogbit expression or variable name in the “Expression” column (just type it in) and its result will be shown in the “Value” column.  Every time the program pauses the values will all be re-computed and re-displayed.

If evaluation of a watch causes an error a message beginning “error: ” will be shown in the “Value” column instead of a result.

To edit a watch you can either :-

•	type directly into the field — press F2 first if you want to edit the existing text

•	or use the pop-up dialog box — click the right mouse button and select ‘Edit Watch’ from the popup menu

File-Views

A watch shows its value on a single line but a file-view can be used to display multi-line variables and to show a file-variable being read or written.  A file-view can only be used for a variable, not any other form of expression.

You can add a file-view using Add File View from the pop-up menu for the program text or File View from the pop-up menu for the watches window.

When the variable is being used as a file with the read, write and other file commands the IDE highlights all the text read from or written to the variable since the file-view was last refreshed.

The status line of the file-view form gives some additional information about the variable.


Running the Program

Controlling Program Execution


INTRODUCTION

Frogbit is the name of both a programming language and of the tools used to develop programs written in it.

It is a small programming language which is designed for the manipulation of files and text.  The syntax of the language is largely based on the use of keywords rather than punctuation; this means that Frogbit programs tend to be large but readable.

A well-featured IDE (integrated development environment) is provided for the development of Frogbit programs.  The IDE has facilities for running, single-stepping and halting your program and also supports expression watches and file-view windows so that you can track intermediate results.

Future

Once your program is debugged and working you can run it routinely using the more convenient RUN tool which does not support the debugging features of the IDE.

The Frogbit Language

Frogbit is a line-oriented language: each line consists of one or more command words which may be followed by parameters.  Command parameters are usually (but not always) preceded by an identifying keyword.  It is often the case that parameters can be omitted and a default value supplied by the system.

Like most programming languages Frogbit has variables for storing intermediate results.  Frogbit has only one sort of variable: the sort that holds a string of characters.  However, a Frogbit string can be as long as you like (2 thousand megabytes is the theoretical limit) and you can do integer arithmetic with numbers stored as strings.

Future

You can make up expressions from variables, numbers and strings combined with operators.  Some operators are symbols like ‘+’, ‘*’ and ‘=’ but Frogbit also has a number of names used as operators, such as matches, beginsWith and contains.

Command words, parameter keywords, operator names and variable names are all case-insensitive — i.e., these three lines will all have the same effect :-

copy lines where (line beginsWith "[")

COPY LINES WHERE (LINE BEGINSWITH "[")

Copy lines Where (Line beginswith "[")

Introduction to Commands

Introduction to Variables

Introduction to Expressions


Introduction to Commands

See Also

Let’s begin by looking at a command which has a counterpart in most programming languages: set, used to set a variable to a new value.  For example :-

set count equal to 0

The command name and keywords have been rendered in bold type to make the examples in this help file clearer.  At present, this highlighting is not supported by the IDE.

Future

In this example the word set is the name of the command.  Some commands are specified by more than one word (e.g. copy lines).

The set command takes two parameters: a variable and an expression to be evaluated and assigned to the variable.  In this case the variable is count and the expression is 0.

•	the variable parameter of set has no keyword associated with it

•	the expression parameter has a two-word keyword equal to associated with it; the keyword must immediately precede the parameter

Alternatively ..

You can use a simple = sign instead of equal to, for example :-

set count=0


Introduction to Variables

Introduction to Expressions


Introduction to Variables

See Also

Frogbit variables can be used as in other programming languages :-

•	you can set a variable to a value using the set command

•	you can access the value of a variable by including the variable in an expression

Here are some examples using a variable called record :-

set record equal to ""

if (record beginsWith "<")

write (record & "...")

A variable name must begin with a letter and any following characters must be letters, digits or underlines.  Variables don’t need to be declared but a variable does need to be set to a value before you can use it in an expression.

Frogbit variables are also used for reading and writing text files.  Rather than reading lines directly from a disc file you first of all input the text file into a Frogbit variable and then read lines from the variable.  Similarly, you can write lines into a Frogbit variable and then output the whole variable to a text file.

A Frogbit variable being used as an input file has a next-record-pointer which initially points to the start of the text :-

•	When the read command is used the line pointed to by the next-record-pointer is read into the destination variable and the next-record-pointer is advanced to point to the next line in the text.

•	When the next-record-pointer reaches the end of the text the variable is said to be at ‘end of file’ (see someLeft and noneLeft) and attempting to read from it will cause the Frogbit program to stop with a runtime error.

A variable used as an output file has no record-pointer and no end-of-file condition because anything written to the file is simply written after the existing text.

Four basic commands are used for input and output :-

•	input is used to get the contents of a text file into a variable

•	output is used to create or overwrite a text file with the contents of a variable

•	read is used to get a single line of text from a variable

•	write is used to append a line of text to a variable’s contents

The default file-variable used in the input and read commands is called input.  The default variable for output and write is called output.  The default variable used to hold a single line read from or written to a file-variable is called line.

Because of these defaults you can shorten most programs considerably — as in this example which takes full advantage of them.  It reads file “test.in” and writes all the non-blank lines in it to file “test.out” :-

input "test.in"
do while (someLeft input)
  read
  if (line<>"")
    write
  endif
loop
output "test.out"

As well as these basic commands there are a couple of more complex and powerful commands for handling file input/output :-

•	skip lines is used to skip over lines in a variable

•	copy lines is used to copy lines from one variable to another

Here is the above example re-written using copy lines :-

input "test.in"
copy lines where (line<>"")
output "test.out"


Introduction to Commands

Introduction to Expressions


Introduction to Expressions

See Also

Frogbit expressions are made up of variables, strings and numbers combined using operators.  Some operators are symbols and others are words.

When an expression is used in a command it must be enclosed in brackets unless it is a single variable name, string or number.

Here are some example expressions :-

(prefix&line)

... this is a pair of variables (prefix and line) combined using an operator (&).  The result is made up of the two strings concatenated together.  The & operator is special in that it is the default operator and can be omitted — this example could have been written :-

(prefix line)

(count+1)

... this is a variable (count) and a number (1) combined using an operator (+).  The result is the sum of the contents of count and 1.

((line="") or (line beginsWith "//"))

... this is a more complex expression: two sub-expressions are combined using the or operator; the result of this is either true or false — true if either or both of the sub-expressions is true, false if both the sub-expressions are false.

(input withAll "testrig" replacedBy "test-rig")

... this is an example of a multi-word operator: the withAll and replacedBy are actually parts of a single operator which takes three parameters.  The result is the contents of variable input with all occurrences of “testrig” replaced by “test-rig”.

Syntax (reference)


Introduction to Commands

Introduction to Variables


Breakpoints are poorly supported in this version of the system; all there is is a pause command.  A later version will support various forms of dynamic breakpoint.


Basic floating-point arithmetic will be introduced into Frogbit at some later date.


Syntax highlighting will be introduced into Frogbit at some later date.


SYNTAX

A program is made up of one or more lines.  A line can be a comment line, a blank line or a command line.

Comment lines and blank lines have no effect when your program is run but are essential for readable programs.  Also, leading spaces and tabs on a line are ignored and readability is greatly improved when indentation is used consistently in if..endif, do..loop and for..next structures.

Sorts of program line

Comment Lines

A comment line is a line which begins with "//"; it is purely for the benefit of you and anyone else

who reads the program and it is ignored by the compiler.  Spaces and/or tabs can precede the "//".

// This program searches the given directory for files which
// contain keywords on their first line.

Blank Lines

A blank line is a line which is either completely empty or which consists solely or spaces and tabs; it is ignored by the compiler.  Judiciously placed blank lines are essential to a readable program.

Command Lines

A command line is made up of one or more command-words followed by one or more unqualified arguments and/or qualified arguments; for example :-

choose input file infile in "c:\"

... or equivalently ...

choose input file in "c:\" infile

In the above example ..

•	command-words: choose input file

•	unqualified arguments: infile

•	qualified arguments: in "c:\"

A qualified argument is an argument (i.e. an expression or variable name) which is introduced using a keyword — such as in in the example above.

An unqualified argument is one which is not preceded by a keyword — such as infile in the example above.

Spaces and tabs are ignored in command lines except inside quoted strings.

Arguments

Whether qualified or unqualified, arguments come in two varieties :-

•	variable name

•	expression

Variable Name Arguments

Commands which require variable name arguments either use the variable as a file, or they set the variable to some result produced by the command.

Such arguments can often be omitted in simple programs because most commands provide default variables into which they write their results if an argument is not given.  For example, there are two standard defaults for file-variables :-

•	input for files which are to be read from

•	output for files which are to written to

Expression Arguments

Commands which require expression arguments use the result of evaluating the expression in various ways :-

•	as a filename

•	as data to be written to a file

•	as a true or false condition ("1" means true, "0" means false)

•	... and many more

If the expression is just a quoted string, a number, or a variable it can be used without brackets, but any more complex form of expression needs brackets around it to mark it off from the other arguments :-

if flagvar
if (flagvar or (line=""))

Strings

Characters inside quotes ("...") represent themselves except for two special characters :-

double-quote

" marks the end of a quoted-string so you need to use two of them, for example :-

write "She said ""Hello""."

... writes She said "Hello".

back-quote

` introduces a non-printable character :-

•	"``" represents ` itself

•	"`n" represents linefeed (ascii 10 — 0A in hex)

•	"`p" represents a page break (ascii 12 — 0C in hex)

•	"`r" represents carriage-return (ascii 13 — 0D in hex)

•	"`t" represents tab (ascii 9 — 09 in hex)


About the Examples

Frogbit examples are stored in the examples subdirectory of the main Frogbit directory.  This directory has a Microsoft Word/Wordpad file examples.doc which lists and summarises the examples.

When you are trying to understand an example :-

•	read the project notes (if any) - use View/Notes from the menu

•	read the comments (lines beginning ‘//’)

•	use file-views on the file-variables (usually ‘input’ and ‘output’)

•	use watches on the other variables

•	single-step or auto-step the program

•	if the program has a line reading //refresh try removing the // and running the program — it’ll run more slowly but it’ll update the watches and file-views whenever the refresh command is executed

•	use the help — put the cursor over a word in the program and press F1

It is essential to have a file-view on the output variable for examples which don’t write their results to a file (i.e. examples which don’t end with an output command).


Project Wizard

Using the Project Wizard is a quick way of writing a new Frogbit program.  It creates a skeleton program to which you can add code specific to the task at hand.

The wizard consists of a sequence of dialog screens which ask you questions about the program you want to write.  The answers you give are used to write the program.

The questions asked by the wizard may not always be relevant to the program you want to write.  In such a case you should give the nearest answer (or answer None) and edit the program code when the wizard has finished.

You can move backwards and forwards through the wizard screens using the Back and Next buttons.  You can abandon the wizard using the Cancel button at any time.

If you need assistance at any point just press the Help button.

The last screen has a Finish button which is used to accept all the answers you gave and to write the Frogbit program.  The answers you gave are also kept to be used as the initial defaults next time you use the wizard.

Now use the Browse buttons labeled << and >> at the top of this help window to step through the help on the wizard screens.


Project Wizard: "Introduction"
Project Wizard: “Introduction”

This screen introduces the wizard and asks for your name, which it writes to the start of the program as a comment.  You don’t have to enter anything if you don’t want to.

When you have completed this screen you should advance to the next screen using the Next button.


Project Wizard: "Summary"
Project Wizard: “Summary”

Here you can enter a few lines summarising the purpose of the program — or any other program header you want.  This text is written to the start of the program as a series of comment lines.  You don’t have to enter anything if you don’t want to.


Project Wizard: "Type of Program"
Project Wizard: “Type of Program”

What you select here determines the sort of program which the wizard starts writing for you.  It can’t write the whole program for you but it can quickly write some of the sort of code which is common to many programs.

The wizard accepts one of these choices :-

None

If your program is not one of the following sorts of program select None and no code will be generated here.

Process Every Line

Select this if you want to read every line of the input file and process it in some way.  The wizard will generate a loop with a read command in it and leave you to write the rest of the code to process the line.

Process in Sections

This choice generates code to alternately copy  and skip sections of the input file.  The wizard shows you two extra screens on which you can specify exactly how the sections appear :-

Process in Sections - Header

Process in Sections - Body


Project Wizard: "Process in Sections - Header"
Project Wizard: “Process in Sections - Header”

Note: you only get this screen if you selected Process in Sections on the previous screen (Type of Program).

When you choose to process your input file in sections it is treated as an optional unique ‘header section’ followed by a number of repeating ‘body sections’.

Note that the header section and each body section must be made up of a number of complete lines; this wizard does not consider input formats where parts of a line contribute to different sections.

Use this screen to say :-

•	whether your input file will have any unique lines of header text before the repeating body sections you’re mainly interested in

•	if there is a header, how to know when you’ve reached the end of it

Example

First of all, select one of the choices from the Action box :-

None

Select this if your input file has no header.

Skip Header

Your input file has a header but you don’t want to copy it to the output file.

Copy Header

Your input file has a header and you do want to copy it to the output file.

Secondly, fill in the “Skip lines ..”/“Copy lines ..” box

Note: if you choose None above you don’t need to fill this in.

While/Until

Choose one of these to specify how the outcome of the condition is used in skipping or copying the header :-

While lines satisfy condition

Lines from the header will be skipped or copied as long as each one satisfies the condition — e.g. if the condition is line beginsWith "*"  then the header consists of all the lines from the start of the file up to the first one which does not begin with a “*”.

Until a line satisfies condition

Lines from the header will be skipped or copied until one is found which satisfies the condition — e.g. if the condition is line beginsWith "*" then the header consists of all the lines from the start of the file up to the first one which does begin with a “*”.

In either case, you can choose whether or not the line that satisfies the condition belongs to the header by setting Include tested line? (see below).

Condition

This is the test which is used to detect either the last line of the header or the line following the header — depending on the setting for Include tested line? (see below).

The condition will normally be an expression involving either the line variable or the nextLine variable.  For example, if the header lines all begin with three stars and the following line doesn’t then you’d enter a condition of line beginsWith “***”.

If you want to build your condition from a dialog box then click on the (build) button.  This only builds very simple conditions at present.

Include tested line?

This setting determines whether the line which satisfies the Condition belongs to the header (the alternative is that it belongs to the first body section).

The effect of this setting is to modify the condition to use either the line variable or the nextLine variable.  For example, if the end of the header is signaled by a line which begins ‘Copyright’ you would want to use a condition of line beginsWith "Copyright".  You would check the Include tested line? checkbox and the condition would automatically be set to use line.

The other possibility is that the end of the header is detected by seeing the first line of the first section in the body.  In this case you would want to ‘look ahead’ at nextLine rather than line so you would want a condition of nextLine beginsWith "Copyright".  This way the line will be left for the code which deals with the body section rather than being ‘swallowed’ by the header code.  Uncheck the Include tested line? checkbox and the condition will automatically be set to use nextLine.

Note: When you click on Include tested line? the program will automatically patch all occurrences of ‘line’ to ‘nextLine’ (or back again).  If you construct your own customised condition using these variables you may want to avoid clicking on Include tested line? so that your variables don’t get changed.


Project Wizard: "Process in Sections - Body"
Project Wizard: “Process in Sections - Body”

Note: you only get this screen if you selected Process in Sections on the screen before last (Type of Program).

When you choose to process your input file in sections it is treated as an optional unique ‘header section’ followed by a number of repeating ‘body sections’.

Note that the header section and each body section must be made up of a number of complete lines; this wizard does not consider input formats where parts of a line contribute to different sections.

Each body section is in two parts: one part is skipped and the other part is copied to the output file.

Use this screen to say :-

•	whether it’s the skipped part or the copied part which comes first

•	how to know when you’ve come to the end of each part

Example

First of all, select one of the choices from the Action box :-

Skip then Copy

The first part of the body is skipped, the second  part is copied.

Copy then Skip

The first part of the body is copied, the second  part is skipped.

Secondly, fill in each “Skip lines ..”/“Copy lines ..” box

While/Until

Choose one of these to specify how the outcome of the condition is used in skipping or copying the part :-

While lines satisfy condition

Lines from the part will be skipped or copied as long as each one satisfies the condition — e.g. if the condition is line beginsWith “ ” then the part consists of lines up to the first one which does not begin with a space.

Until a line satisfies condition

Lines from the part will be skipped or copied until one is found which satisfies the condition — e.g. if the condition is line beginsWith “ ” then the part consists of lines up to the first one which does begin with a space.

In either case, you can choose whether or not the line that satisfies the condition belongs to this part of the body section by setting Include tested line? (see below).

Condition

This is the test which is used to detect either the last line of the part or the line following the part — depending on the setting for Include tested line? (see below).

The condition will normally be an expression involving the line variable.  For example, if the lines in the part all begin with three stars and the following line doesn’t then you’d enter a condition of line beginsWith “***”.

If you want to build your condition from a dialog box then click on the (build) button.  This only builds very simple conditions at present.

Include tested line?

This setting determines whether the line which satisfies the Condition belongs to this part.

The effect of this setting is to modify the condition to use either the line variable or the nextLine variable.  For example, if the end of this part is signaled by a line which begins ‘Total’ you would want to use a condition of line beginsWith "Total".  You would check the Include tested line? checkbox and the condition would automatically be set to use line.

The other possibility is that the end of this part is detected by seeing the first line of the next part.  In this case you would want to ‘look ahead’ at nextLine rather than line so you would want a condition of nextLine beginsWith "Total".  This way the line will be left for the code which deals with the next part rather than being ‘swallowed’ by the code that deals with this part.  Uncheck the Include tested line? checkbox and the condition will automatically be set to use nextLine.

Note: When you click on Include tested line? the program will automatically patch all occurrences of ‘line’ to ‘nextLine’ (or back again).  If you construct your own customised condition using these variables you may want to avoid clicking on Include tested line? so that your variables don’t get changed.


Process in Sections Example

Here is an input file which we will use to illustrate the use of the Process in Sections - Header and Process in Sections - Body screens :-

Toad Analysis Report

Copyright © 1997 Toad Statistical Services

Group 1 - East Hampton

      | river | bank

------|-------|------

length|  15.5 | 12.1

weight|  43.4 | 36.2

Group 2 - West Hampton

      | river | bank

------|-------|------

length|  17.9 | 14.7

weight|  45.3 | 39.8

This input file has a header section followed by two body sections :-

Header

Toad Analysis Report

Copyright © 1997 Toad Statistical Services

1st Body Section

Group 1 - East Hampton

      | river | bank

------|-------|------

length|  15.5 | 12.1

weight|  43.4 | 36.2

2nd Body Section

Group 2 - West Hampton

      | river | bank

------|-------|------

length|  17.9 | 14.7

weight|  45.3 | 39.8

Note that the header and each body section ends with a blank line.  We choose to ignore blank lines in determining where sections begin and end in this example and merely regard them as noise — this is because report programs may well generate different numbers of blank lines in different versions or when outputting to different printers.

The Problem

We will now show how to use the Project Wizard to write a program which simply extracts the lines with length and weight data — for the example data this would output :-

length|  15.5 | 12.1

weight|  43.4 | 36.2

length|  17.9 | 14.7

weight|  45.3 | 39.8

Filling in the Header Screen

“Action”

The first question is whether there is a header at all, and if so, whether to skip it or copy it to the output file.  In this case there is a header but you don’t want it in the output file, so select Skip Header.

“Skip lines”

Now you have to say how the program knows when its reached the end of the header.  Since we decided not to rely on blank lines you should look instead for the first line of the first body section — “Group 1 - East Hampton”.

First you have to select either While or Until and in this case you should select Until because you want to skip header lines until the line you’re looking for is seen.  You could have selected While and still made it work but the condition would have come out longer (it would have had ‘not’ in front of it).

Next there is the condition itself which needs to test for a line which begins with the word “Group”.

Simple conditions can be built using a dialog box so click on the (build) button and fill in the dialog box thus :-

•	Compare nextLine to String — enter “Group” here (but without any quotes around it)

•	Comparison Type — the line you’re looking for begins with “Group”, so select “Begins With”

•	Negate Condition — our condition reads “nextLine beginsWith "Group"” which is what you’re looking for, so don’t check this checkbox

•	Ignore upper/lower-case — unless you expect sections beginning with “group” and “GROUP” as well as “Group” you should leave this unchecked

Now you’ve told the wizard how to tell when the header is ended you have to let it know whether the tested line is included in the header — i.e., whether it’s the last line of the header or the first line after the end of the header.  In this case you don’t want the tested line included in the header so leave the checkbox unchecked.

Filling in the Body Screen

Each body is considered to consist of two parts: a copied part and a skipped part.

What if it doesn’t fit this pattern?

“Action”

The first question is which order the two parts are in: skip-then-copy or copy-then-skip?  In this case you want to skip the titles and then copy the rest so click on Skip then Copy.  (If the thought of the blank line after the weight line is worrying you — relax, we’ll sort it out later.)

“Skip lines” and “Copy lines”

When you filled in the Header Screen earlier you had to fill in a couple of boxes to say how to recognise the end of the header section.  On this screen there are two boxes to fill in: one for the copied part and one for the skipped part.

The boxes are automatically labeled according to whether you’re doing a copy-then-skip or a skip-then-copy.  In this case the boxes are labeled Skip lines and Copy lines in that order.

“Skip lines”

Select Until.

The condition needs to test for a line which begins with dashes, three of them will do.

Click on the (build) button and fill in the dialog box thus :-

•	Compare nextLine to String — enter “---” here (but without any quotes around it)

•	Comparison Type — the line you’re looking for begins with “---”, so select “Begins With”

•	Negate Condition — our condition reads “nextLine beginsWith "---"” which is what you’re looking for, so don’t check this checkbox

•	Ignore upper/lower-case — leave this unchecked

Now you’ve told the wizard how to tell when this part is ended you have to let it know whether the tested line is included.  In this case you do want the tested line included in this part (after all, you don’t want it copied by the Copy lines code which follows) so check this checkbox.

“Copy lines”

Select Until.

The condition needs to test for a line which begins with the word “Group”.

Click on the (build) button and fill in the dialog box thus :-

•	Compare nextLine to String — enter “Group” here (but without any quotes around it)

•	Comparison Type — the line you’re looking for begins with “Group”, so select “Begins With”

•	Negate Condition — our condition reads “nextLine beginsWith "Group"” which is what you’re looking for, so don’t check this checkbox

•	Ignore upper/lower-case — unless you expect sections beginning with “group” and “GROUP” as well as “Group” you should leave this unchecked

In this case you don’t want the tested line included so leave the checkbox unchecked.

Refining the program

This is the code generated by these options :-

// process header section from input

skip lines until (nextLine beginsWith "Group")

// process each body section from input

do while (someLeft input)

  skip lines until (line beginsWith "---")

  copy lines until (nextLine beginsWith "Group") withLast

loop

This code is not quite right because (as we mentioned earlier) it incorrectly outputs the blank lines as well as the lines with data on them.  This is easily remedied by appending a where qualifier to the copy lines command :-

copy lines until (nextLine beginsWith "Group") withLast where (line<>"")


Process in Sections Example - Note

Each body is considered to consist of two parts: a copied part and a skipped part.

In some cases you may have to define the body sections in a data file in an unnatural way to accommodate this assumption.  For example, if in your file the natural way of looking at a body section is that it has a skipped part, a copied part and then another skipped part you could handle it like this :-

The Natural way of looking at it

header

A (skipped)

1st body section

B (skipped)

C (copied)

D (skipped)

2nd body section

E (skipped)

F (copied)

G (skipped)

Unfortunately the Project Wizard only handles bodies which contain two parts: either a skipped-part followed by a copied-part, or a copied-part followed by a skipped-part.

If you look at the file a little differently you can still do it :-

The Unnatural way of looking at it

header

A,B (skipped)

1st body section

C (copied)

D,E (skipped)

2nd body section

F (copied)

G (skipped)

This way the last body section in the file will have its last bit missing but since it’s being skipped anyway the program will still work.


Project Wizard: "Input File"
Project Wizard: “Input File”

Use this screen to specify the input file for the program.  The wizard supports four styles of input file :-

None

If your program has no input file (or if it uses input file(s) in a complex fashion) select None and no input file handling code will be generated.

Fixed

This setting is used when your program always inputs from the same file.  You must enter the actual filename in the Fixed Name field.

Command Line Argument

This setting generates code to take the input file name from the first command line argument; especially useful if you intend to create shortcuts to the program using Frogbit RUN.

Common Dialog Box

This setting generates code to prompt the user to select an input file using a standard Windows common dialog box.

Switch to Input File’s Directory?

The final control on this screen is used to generate a line of code to make the current directory follow that of the input file; this makes any file references which follow default to the directory of the input file.


Project Wizard: "Output File"
Project Wizard: “Output File”

Use this screen to specify the output file for the program.  The wizard supports five styles of output file :-

None

If your program has no output file (or if it uses output file(s) in a complex fashion) select None and no output-file handling code will be generated.

Fixed

This setting is used when your program always outputs to the same file.  You should enter the actual filename in the Fixed Name field.

Command Line Argument

This setting generates code to take the output file name from the first or second command line argument; especially useful if you intend to create shortcuts to the program using Frogbit RUN.  If the input file is being taken from the first argument then the output file is taken from the second argument, otherwise the first argument is used

Derived from the Input file name

This setting generates code to set the output file to be the same as the input file but with a different extension.  You should enter the extension to be used in the Derived Extension field.

Common Dialog Box

This setting generates code to prompt the user to select an output file using a standard Windows common dialog box.


Project Wizard: "Finish"
Project Wizard: “Finish”

Here you can see a preview of the program code which will be written and can accept (Finish), abandon (Cancel) or opt to revise (Back) the entries you have made.


Build Condition

Use this form to quickly build a simple condition expression using either the line variable or the nextLine variable.  At present it can only build a few simple expressions.

Compare line/nextLine to String:

This is what you’re looking for in the line.  For example, to look for a line which begins with “Group” you would enter Group here.

Comparison Type

This is the way you want to compare your string with the line.  To continue our example of looking for a line which begins with “Group” you would select BeginsWith here.

Negate Condition

To look for a line which does not equal/contain/begin with/end with/match your string you would check this checkbox.  In our example you’d leave it unchecked.

Ignore upper/lower case

Check this checkbox to compare your string against the line regardless of whether they are in upper case, lower case or a mixture.  In our example you could check the checkbox if there was a possibility of the file having relevant lines beginning with “GROUP” or “group” as well as “Group”.


copy lines

See Also	Examples

Format

copy lines {from filevar} {to filevar} {where condition} {while condition} {until condition} {withLast}

Summary

Copy lines from the from-filevar to the to-filevar.  Only lines satisfying the where-condition are copied.

Stop when any of these things happen :-

•	there are no more lines to be read from the from-filevar

•	a while-condition evaluates to false

•	an until-condition evaluates to true

... whichever comes first.

Normally, a line which satisfies a while-condition or until-condition is not itself copied (it is available in variable line).  If you do want the last line copied then use the withLast qualifier.

You can tell whether the terminating line was found using the found special variable :-

•	if the terminating line was found then found=true

•	otherwise found=false

To help define how it works here is how you’d program a copy lines command using simpler commands :-

// examples\commands\copylines\copylines1
copy lines from data to report where (not (line beginsWith "--")) until (line contains "***END***")

— is equivalent to —

// examples\commands\copylines\copylines2
do while (someLeft data)
  read from data
  leave if (line contains "***END***")
  if (not (line beginsWith "--"))
    write to report
  endif
loop

Notes

•	copy lines can be written copylines.

•	Lines are read into the variable line.

•	After a copy lines command the variable line contains the last line read, or "" if the end of the input file was reached.

•	Either while or until can be used, but not both.

Defaults

•	from input

•	to output

•	where true

•	while true

•	until false


skip lines


copy lines: examples
copy lines

copy lines where (line beginsWith "Public Sub")

Copy lines which begin with "Public Sub" from input to output — until input is exhausted.

copy lines to table until (line="***")

Copy lines from input to table until a line "***" is found — that line is read from input but not written to table.

copy lines to table until (line="***") withLast

As above, but if a line "***" is found it is written to table.

copy lines to table until ((nextLineIn input)="***") withLast

As above, but if a line "***" is found it is not even read from input, let alone written to table.

Load examples: examples\commands\copylines


skip lines

See Also	Examples

Format

skip lines {from filevar} {while condition} {until condition}

Summary

Skip over lines in the filevar.

Stop when any of these things happen :-

•	there are no more lines to be read from the from-filevar

•	a while-condition evaluates to false

•	an until-condition evaluates to true

... whichever comes first.

You can tell whether the terminating line was found using the found special variable :-

•	if the terminating line was found then found=true

•	otherwise found=false

To help define how it works here is how you’d program a skip lines command using simpler commands :-

// examples\commands\skiplines\skiplines1
skip lines from data until (line beginsWith "==")

— is equivalent to —

// examples\commands\skiplines\skiplines2
do while (someLeft data)
  read from data
  leave if (line beginsWith "==")
loop

Notes

•	skip lines can be written skiplines.

•	Lines are read into the variable line.

•	After a skip lines command the variable line contains the last line read, or "" if the end of the file was reached.

•	Either while or until can be used, but not both.

Defaults

•	from input

•	while true

•	until false


copy lines


skip lines: examples
skip lines

skip lines until (line beginsWith "Section")

Skip over lines in input until either input is exhausted or a line beginning with "Section" is found — that line is read from input (into line).

skip lines from tests until (line<>"")

Skip over blank lines in tests — if a non-blank line is found before tests is exhausted it is read (into line).

Load examples: examples\commands\skiplines


read

See Also	Examples

Format

read {variable} {from filevar}

Summary

Reads a single line from the filevar into the variable.  Error if the filevar is exhausted.

Defaults

•	line

•	from input


write


read: examples
read

read

Read a line from input into variable line.

read record from data

Read a line from data into variable record.


write

See Also	Examples

Format

write {expression} {to filevar}

Summary

Write the expression to the filevar.

Defaults

•	line

•	to output


read


write: examples
write

write

Write the contents of variable line to output.

write record to data

Write the contents of variable record to data.


input (command)

See Also	Examples

Format

input filepath {to filevar}

Summary

Read the entire contents of the disc file called filepath into the filevar .

Notes

•	If no directory is given explicitly in the filepath the file is read from the current directory.

Defaults

•	to input


output


input: examples
input

input "c:\data\scores.dat"

Load the contents of file c:\data\scores.dat into input.

input chosenFile to data

Load the contents of the file named by the chosenFile variable into data.


reset

See Also	Examples

Format

reset {filevar}

Summary

Resets the next-record-pointer of the filevar to the beginning of the file.  This means that read, copy lines and skip lines will again read records beginning with the first one in the file.

Defaults

•	input


input


reset: examples
reset

reset

Reset the input file-variable.

reset data

Reset the data file-variable.


output (command)

See Also	Examples

Format

output filepath {from filevar}

Summary

Write the entire contents of the filevar to a disc file called filepath.

Warning: when the program is run this command overwrites any existing file of the name given as filepath without any warning or confirmation.

Notes

•	If no directory is given explicitly in the filepath the file is written to the current directory.

Defaults

•	from output


input


output: examples
output

output "c:\data\scores.dat"

Save the contents of output to file c:\data\scores.dat.

output chosenFile from results

Save the contents of results to the file named by the chosenFile variable.


set

Examples

Format

set variable equal to expression

set variable=expression

Summary

Set the variable to the result of evaluating the expression.  The variable can either be a simple variable-name or an expression using @.

Notes

•	equal to can be written equalto.


set: examples
set

set results equal to ""

Set the variable results to an empty string.

set backupPath=(path withExt ".BAK")

Set the variable backupPath to the result of replacing the extension part of the filespec in variable path with ".BAK".

set (output@2)="Hello"

Set the second line of the output variable to “Hello”.


if..else..elseif..endif

Examples

Standard Format

if condition
...
else
...
endif

Summary

The if command is used when you want to do one of two things depending on the circumstances :-

•	if the condition evaluates to true (i.e. "1") the lines between the if and the else are executed

•	if the condition evaluates to false (i.e. "0")  the lines between the else and the endif are executed

You can omit the else and the lines following it; this simply means that if the condition evaluates to false nothing is executed until after the endif line.

You can nest if structures as much as you like, for example :-

if (a="age")

  write ("age is " b)

else

  if (a="sex")

    write ("sex is " b)

  else

    error ("unknown data-type: " a)

  endif

endif

Note the indentation used in this example; it is highly recommended that you do this in your own programs, otherwise they can become very difficult to follow.

elseif can be used to shorten nested if structures where an if line immediately follows an else line.  Here is the previous example rewritten using elseif :-

if (a="age")

  write ("age is " b)

elseif (a="sex")

  write ("sex is " b)

else

  error ("unknown data-type: " a)

endif

Note that there is one fewer endif.

Notes

•	Any number of elseif parts can be used.

•	elseif can be written else if.

•	endif can be written end if.


if..else..elseif..endif: examples
if..else..elseif..endif

if ((ext=".TXT") or (ext=".CSV"))

  write "Text:"

  write fileContents

elseif (ext=".EXE")

  write ("Executable: " path)

elseif (ext=".FB")

  write "Frogbit program:"

  write fileContents

else

  write ("*** unknown file type: " ext)

endif

Since Frogbit doesn’t have a case-statement this is how you have to do it.


do..loop

See Also	Examples

Format

do {while condition} {until condition}
...
loop {while condition} {until condition}

Summary

The do command is used when you want to do something more than once.  The statements between do and loop will be executed repeatedly until one of the following happens :-

•	a while condition becomes false (i.e. "0")

•	an until condition becomes true (i.e. "1")

•	a leave command is executed

Notes

•	You can only use one while or until qualifier in a do..loop — you can’t use both on the do or both on the loop and you can’t use one on the do and one on the loop.

•	A condition on the do is tested before anything inside the do..loop is executed but a condition on the loop is tested for the first time when the statements inside do..loop have been executed once.


for each..next

leave


do..loop: examples
do..loop

do

  write "hello"

loop

Write "hello" to output forever ... or until you press the Halt button.

do while (someLeft input)

  read

  if (line beginsWith "<<")

    write line

  else

    write (line ">>")

  endif

loop

Copy the rest of input to output but any line beginning with "<<" has ">>" written after it.


for each..next

See Also	Examples

Format

for each file expression {in expression} {withSubDirs} {withHidden}
...
next

Summary

Scan the disc directory given by the in-expression for files matching the list of file masks given by the file-expression.

A file mask is a filename, possibly containing wildcard ‘?’ or ‘*’ characters; for example: “*.txt” or “a*.doc”.  If more than one file mask is given they are separated by ‘;’s — for example: “*.txt;*.prn”.

For every file in the given directory which matches a file mask, the commands between for and next are executed with the special variable afile set to the full path to the matching file.

If withSubDirs is given then all directories of the original directory will also be searched, as will all their directories and so on.

If withHidden is given then hidden files will be found as well as normal non-hidden ones.

Notes

•	for each can be written foreach.

•	Any value assigned to the afile special variable will be lost when the program exits from the loop.

•	If a file matches more than one file mask it will be processed once for each match; for example: “amber.txt” will match both patterns in “a*.*;*.txt” and so will be processed twice.

Defaults

•	in current directory


do..loop

leave

afile


for each..next: examples
for each..next

for each file "*.INI" in "c:\windows"

  input afile

  write (afile "-->")

  copy lines where (line matches "[~]")

next

Scan the c:\windows directory for files with a .INI extension.  Write to output the name of any such file followed by any lines in the file which begin with "[" and end with "]".

for each file "readme.txt;read.me;readme.1st" in "c:\" withSubDirs

  write ((fileExtOf afile) " found in " (driveDirOf afile))

next

Scan all the directories on the C: drive for files named ‘readme.txt’, ‘read.me’ or ‘readme.1st’ and write each ones name+extension and drive+directory to output.


leave

See Also	Examples

Format

leave {if condition}

Summary

This command can only be used between do and loop or between for each and next.  If the condition is true (i.e. "1") it has the effect of immediately exiting from the do..loop (or for each..next) structure and continuing execution after the loop (or next) statement.

Notes

•	If loops are nested only the immediately enclosing do..loop or for each..next is exited from.

Defaults

•	if true


for each..next

do..loop


leave: examples
leave

do
  read

  if (line="****")

    write "(end of data)"

    leave

  endif

  write

loop

Read lines from input and write them to output until "****" is read, at which point write "(end of data)" and exit from the loop.  Note that this is to illustrate the use of leave but it could in fact have been done more elegantly and efficiently using the copy lines command.

for each file "*.TXT" in selectedDir

  input afile

  skip lines until (line contains searchString)

  leave if (not found)

next

Scan the directory given by selectedDir for files with a ".TXT" extension and search each one for a line containing the string given by searchString; the leave command quits the loop as soon as the string is found in any file.


choose

Examples

The choose command comes in two distinct varieties: choose input/output file and choose list item.  Since these are quite different they are described separately.

choose input/output file

Format

choose {input/output} file {variable} {in expression} {title expression} {defaultExt expression} {filename expression} {filter expression}

Summary

Invites the user to select a file using a Windows common dialog box.  You should use the appropriate keyword input or output, depending on whether the file is intended for reading from or for writing to.  The parameters consist of a variable which gets set to the selected file-path, and a number of qualifiers which control the behaviour of the dialog-box :-

•	in gives the initial directory

•	title gives a title for the dialog-box

•	defaultExt gives the file-extension to be returned if none is specified by the user

•	filename gives the file-name to appear as the user’s selection

•	filter gives a list of file filters to appear in the pull-down list in the dialog-box

Notes

•	The words choose input file or choose output file must come first.

•	If the user cancels the dialog box the program pauses in the IDE or exits in Frogbit RUN.

Defaults

•	chosenFile

•	in current directory

•	title ("Open" for choose input file, "Save As" for choose output file)

•	defaultExt ""

•	filename ""

•	filter ""

choose list item

Format

choose list item {variable} from expression {title expression}

Summary

Invites the user to select an item from a list.  The parameters consist of a variable which gets set to the selected item, and a number of qualifiers which control the behaviour of the dialog-box :-

•	from indicates the expression which evaluates to a multi-line string used to fill the list box; each line is in the format tag;prompt where tag is what is returned if the item is selected and prompt is what to put in the list box; if there is no ‘;’ the tag and the prompt are each just the whole line

•	title gives a title for the dialog-box

Notes

•	The words choose list item must come first.

•	If the user cancels the dialog box the program pauses in the IDE or exits in Frogbit RUN.

Defaults

•	chosenItem

•	title "Choose list item .."


choose: examples
choose

choose input file inFile in selectedDir
choose output file outFile in selectedDir filename (inFile withExt ".out")

Prompt the user for a file intended to be input from, starting in the directory given by selectedDir.  Then prompt them for a file intended for output, starting in the same directory and prompting with the input file name but with a ".out" extension.

set choices equal to ""

for each file "*.ini" in "c:\windows"

  write (afile ";" (fileOf afile)) to choices

next

choose list item from choices title "Copy file to clipboard .."

input chosenItem to clipboard

Prompt the user with a listbox consisting of the file-names of all the files matching "*.ini" in directory "c:\windows".  Input the contents of the chosen file to the clipboard.


File Filters

See Also

When you use the choose command to select an input or output file you can specify one or more file filters to appear in the Files of type drop-down list :-

•	the filter string is made up of a sequence of filter items separated by “|” characters

•	each filter item consists of a description followed by a “|” and then the wildcard mask for selecting the files

•	more than one wildcard mask can be given; separate them by “;”s

For example :-

"Text files|*.txt"

"Data files|*.dat;*.inp;*.res|Output files|*.out;*.prn"


choose


error

Examples

Format

error expression {if condition}

Summary

Report a fatal runtime error with the message given by expression.  If a condition is given the error will only be reported if condition evaluates to true.

Notes

•	If condition is given and it evaluates to false the message expression will not be evaluated.

Defaults

•	if true


error: examples
error

error "Input file is empty"

error "Unexpected end of file" if (noneLeft input)


pause

Examples

Format

pause {if condition}

Summary

Pauses the program as if the Pause menu option or toolbar button had been used.  If a condition is given the program will only pause if condition evaluates to true.

Defaults

•	if true


pause: examples
pause

pause

pause if (noneLeft input)


in

Examples

Format

in directory

Summary

Changes the current directory.  Any commands which use disc files such as input, output, choose and for each will now use the given directory unless they explicitly specify a different directory.

The directory may include a drive.


in: examples
in

in "c:\mydata"

in selectedDir


refresh

Examples

Format

refresh {if condition}

Summary

If the program is being run from the IDE this command causes all the watch and file-view windows to be updated.  If a condition is given the windows will only be refreshed if condition evaluates to true.

Defaults

•	if true

Notes

•	refresh has no effect when used by a program launched using FrogbitRUN.  To be precise, the condition (if any) will be evaluated but no further action will be taken (the program will not be slowed down as it is with the IDE).

•	Using refresh in the IDE inside a loop can be very helpful while you’re debugging a program but it will slow it down considerably.  If you want to run a program at full speed inside the IDE you should comment-out any refresh commands (at least the ones in inner-loops).


refresh: examples
refresh

refresh

refresh if (noneLeft input)


status

Examples

Format

status message

Summary

This command writes the given message to the status line.  It works in both the IDE and FrogbitRUN.


status: examples
status

status "Scanned report OK"

status ("Processing file " afile)


withDrive

withDir

withFile

withExt

withDriveDir

withFileExt

driveOf

dirOf

fileOf

extOf

driveDirOf

fileExtOf


Operator Priorities

When an expression is parsed the priorities of the operators used in it determine how it is interpreted.  For example, the expression 2+3*5 is interpreted as if it were bracketed 2+(3*5) because ‘*’ has a higher priority than ‘+’.

The rules are :-

1.	Bracketing overrides everything else.

2.	Higher priority operators bind more tightly than lower priority operators.

3.	Equal priority operators bind to the left.

When in doubt: use brackets.

There are three sorts of operator :-

•	a monadic operator takes a single operand on its right, such as ‘-’ in (3*-5) and ‘not’ in (not (a and b)

•	a dyadic operator takes two operands, such as ‘*’ in (3*5) and ‘matches’ in (line matches "~(a),~(b)")

•	a multi-word operator takes three or more operands, such as ‘withAll..replacedBy’ in (input withAll "testrig" replacedBy "test-rig")

Monadic operators have a higher priority than all dyadic operators.  Multi-word operators have a lower priority than all dyadic operators.

Dyadic operators have priorities as follows :-

weakest

•	and

•	or

weakish

•	<

•	>

•	=

•	<>

•	contains

•	matches

•	without

•	beginsWith

•	endsWith

•	withDrive

•	withDir

•	withFile

•	withExt

•	withDriveDir

•	withFileExt

strongish

•	&

•	+

•	-

•	|

•	||

•	rj

•	lj

•	after

•	before

•	except

•	exceptAll

stronger

•	*

•	/

strongest

•	@


and

See Also

Summary

(a and b) evaluates to true if both a and b are true.

Example

if (showall and (line contains "<<"))

  write line

endif

If variable showAll is true and the current line contains "<<" then write the line to output.


or

not


or

See Also

Summary

(a or b) evaluates to true unless both a and b are false.

Example

if ((line contains "+") or (line contains "<<"))

  write line

endif

If either the current line contains "+" or the current line contains "<<" (or both) then write the line to output.


and

not


not

See Also

Summary

(not a) evaluates to true if a is false, or to false if a is true.

Example

if (not (line contains "+"))

  write line

endif

If the current line does not contain "+" then write the line to output.


and

or


<

See Also

Summary

(a < b) evaluates to true if a is less than b when they are interpreted as numbers.

Example

leave if (index<min)

Leave the current loop if variable index is less than variable min.


>


>

See Also

Summary

(a > b) evaluates to true if a is greater than b when they are interpreted as numbers.

Example

leave if (index>max)

Leave the current loop if variable index is greater than variable max.


<


=

See Also

Summary

(a = b) evaluates to true if a is equal to b.

Notes

•	This operator is nothing to do with the = keyword used in the set command.

•	= is case-sensitive, use =? for a case-insensitive comparison.

Example

leave if (firstWord="data")

Leave the current loop if variable firstWord is equal to the string "data".

leave if (firstWord=?"data")

Leave the current loop if variable firstWord is equal to the string "data", "DATA", "Data" or any other version of "data" regardless of letter-case.


<>

contains

beginsWith

endsWith

matches


<>

See Also

Summary

(a <> b) evaluates to true if a is not equal to b.

Notes

•	<> is case-sensitive, use <>? for a case-insensitive comparison.

Example

leave if (firstWord <> "data")

Leave the current loop if variable firstWord is not equal to the string "data".

leave if (firstWord<>?"data")

Leave the current loop unless variable firstWord is equal to the string "data", "DATA", "Data" or any other version of "data" regardless of letter-case.


=


contains

See Also

Summary

(a contains b) evaluates to true if a contains b as a substring (or a equals b).

Notes

•	contains is case-sensitive, use contains? for a case-insensitive comparison.

Example

leave if (line contains "end")

Leave the current loop if variable line includes the string "end".

leave if (line contains? "end")

Leave the current loop if variable firstWord contains the string "end", "END", "End" or any other version of "end" regardless of letter-case.


=

contains

beginsWith

endsWith

matches


beginsWith

See Also

Summary

(a beginsWith b) evaluates to true if a begins with string b (or a equals b).

Notes

•	beginsWith is case-sensitive, use beginsWith? for a case-insensitive comparison.

Example

leave if (line beginsWith "data")

Leave the current loop if variable line begins with the string "data".

leave if (line beginsWith? "data")

Leave the current loop if variable firstWord begins with the string "data", "DATA", "Data" or any other version of "data" regardless of letter-case.


endsWith

=

<>

contains

matches


endsWith

See Also

Summary

(a endsWith b) evaluates to true if a ends with string b (or a equals b).

Notes

•	endsWith is case-sensitive, use endsWith? for a case-insensitive comparison.

Example

leave if (line endsWith "data")

Leave the current loop if variable line ends with the string "data".

leave if (line endsWith? "data")

Leave the current loop if variable firstWord ends with the string "data", "DATA", "Data" or any other version of "data" regardless of letter-case.


beginsWith

=

<>

contains

matches


matches

See Also

Summary

(a matches b) evaluates to true if a matches pattern b.

This is a complex and powerful operator and it has a whole section of help to itself :-

Matching

Notes

•	matches is case-sensitive, use matches? for a case-insensitive comparison.

Example

leave if (line matches "Total expenditure: ~(total) ")

If variable line matches the pattern "Total expenditure: ~(total) " then :-

•	leave the current loop

•	set variable total to the indicated part of line as a side-effect

leave if (line matches? "Total expenditure: ~(total) ")

As above, but the line doesn’t have to match in letter-case — for example, a line reading “TOTAL EXPENDITURE: 43.2 ” will do.


=

<>

contains

beginsWith

endsWith


Matching

The matches operator is used to extract information from a line of text.  You can use this operator to perform tasks which might take dozens of lines in most programming languages.

Warning: don’t use the matches operator with a very long string (such as a whole text-file) because it may take a very long time.  It should be ok if you do it line-by-line.  The code generated to do matching will be better optimised in a later release of Frogbit.

Overview

The matches operator takes two parameters: a plain string and a pattern string.  If the string “matches” the pattern it returns true, otherwise false.

To take the simplest case first of all: a pattern string which doesn’t contain any spaces or “~”s will only match a plain string if they are the exactly the same :-

"Report-date=26-Mar-97" matches "Report-date=26-Mar-97"

To match regardless of letter-case use the matches? Operator instead :-

"REPORT-DATE=26-Mar-97" matches? "Report-date=26-Mar-97"

This sort of pattern isn’t very useful — you might just as well use the = operator which is somewhat faster than matches.  To be of any use a pattern has to contain spaces and/or “~”s.

Spaces

A space in a pattern matches one or more spaces or tabs.  If you want to match two or more spaces/tabs you use two spaces in the pattern, and so on.  For example, this evaluates to true :-

"Report-date:    26-Mar-97     " matches "Report-date: 26-Mar-97 "

“~”s

A “~” in a pattern matches anything.  For example, all these expressions evaluate to true :-

"Report-date=26-Mar-97" matches "Report-date=~"

"Report-date=26-Mar-97" matches "~=26-Mar-97"

"Report-date=26-Mar-97" matches "Report~26-Mar-97"

"Report-date=26-Mar-97" matches "Report-date=~-Mar-~"

The “~” is called an anonymous pattern variable.

Even better than this is the facility to extract the sub-strings which match the “~”s and put them into variables; for example, this expression evaluates to true :-

"Report-date=26-Mar-97" matches "Report-date=~(date)"

... but as a side-effect the variable date is set to "26-Mar-97".

The “~(date)” is called a pattern variable.

Two questions you may be asking :-

What if I want to put a real “~” into the pattern string?

Put two successive “~”s into the pattern string; for example, this evaluates to true :-

"alpha~beta" matches "alpha~~beta"

What if I want to match a sub-string which happens to be followed by a “(“?

Use a pattern variable without any variable name between the “(..)” and then put the “real” opening bracket; for example, this evaluates to true :-

"abc(def)ghi" matches "~()(def)~(x)"

The “~()” in the pattern matches “abc”, the “(def)”s match each other and “~(x)” matches “ghi” so variable x gets set to “ghi”.

But this wouldn’t have worked :-

"abc(def)ghi" matches "~(def)~(x)"

... because the “~(def)” in the pattern would have been seen as a pattern variable — variable def gets set to “” and variable x gets set to “abc(def)ghi”.

Example


Matching Example

Let’s consider a very simple application: interpreting a Windows .INI file.  A .INI file is a text file which contains three different sorts of line :-

•	blank lines — these can be ignored

•	a section name in ‘[section]’ format — this marks the start of a new section

•	a setting in ‘variable=value’ format — this gives the value of a variable in the current section

Our task is to read a .INI file and to output each setting line in the form :-

section:variable:value

For example, if this is the original .INI file :-

[printers]
LPT1=Hewlett Packard
LPT2=Epson
COM1=Canon

[fonts]

[users]
JD=Jane Doe
GW=George Washington

... the output from our program would be :-

printers:LPT1:Hewlett Packard
printers:LPT2:Epson
printers:COM1:Canon
users:JD:Jane Doe
users:GW:George Washington

Plan

Here’s what we need to do with the three sorts of line in a .INI file :-

•	blank lines — ignore them

•	section headers (‘[section]’) — update our variable which holds the current section name

•	settings lines (‘variable=value’) — write a line to the output file

The Program

This program can be found in your examples directory in the matching subdirectory.

// examples\matching\matching.fp

input "example.ini"

// 'section' keeps track of the current section
set section equal to ""

// scan the .INI file ...
do while (someLeft input)

  // read a line from the .INI file
  read

  // ignore blank lines
  if (line="")
    // (do nothing)

  // extract section from "[...]" lines
  elseif (line matches "[~(section)]")
    // (nothing else to do — 'section' has been set)

  // process "variable=value" lines
  elseif (line matches "~(variable)=~(value)")
    error "setting found before first section name" if (section="")
    write (section ":" variable ":" value)

  else
    error ("unrecognised line: " line)
  endif

loop

output "example.out"


&

See Also

Summary

(a & b) evaluates to the string formed by concatenating a and b together.

Notes

•	This is the default operator so it can be omitted entirely.

Example

write (name & ": " & address)

Write variable name followed by the string ": " followed by variable address.  The & operator is usually omitted :-

write (name ": " address)


|


|

See Also

Summary

(a | b) evaluates to the string formed by ‘merging’ a and b together.  If a and b each only contain a single line of text ‘merging’ is no different from concatenation.  If one or both contain more than one line of text the following procedure is followed :-

•	concatenate the 1st line of a with the 1st line of b and make this the 1st line of the result

•	concatenate the 2nd line of a with the 2nd line of b and make this the 2nd line of the result

•	... and so on

However, if the strings have different numbers of lines then the string with fewer lines is re-scanned as many times as necessary to make it up to the number of lines in the longer string.  This explanation will probably not make much sense until you’ve seen the example below ...

Example

Consider two multi-line variables :-

years

1979
1980
1981

names

Smith
Jones
Taylor
Johnson
Bryant

If  we merge the variables like this :-

years | "," | names

... we get this :-

1979,Smith
1980,Jones
1981,Taylor
1979,Johnson
1980,Bryant

Since years has fewer lines than names the first two years have been re-used for lines 4 and 5.  Also note that the single line in the "," string has been repeated for all 5 lines.

Any trailing blank lines in the parameters are ignored.


&

||


||

See Also

Summary

(a || b) evaluates to the string formed by ‘multi-merging’ a and b together.  If a and b each only contain a single line of text ‘multi-merging’ is no different from concatenation.  If one or both contain more than one line of text then the following procedure is followed :-

•	concatenate the 1st line of a with the 1st line of b and call this the 1st line of the output

•	concatenate the 1st line of a with the 2nd line of b and call this the 2nd line of the output

•	... for all the lines in b, then :-

•	concatenate the 2nd line of a with the 1st line of b

•	concatenate the 2nd line of a with the 2nd line of b

•	... and so on.

This explanation will probably not make much sense until you’ve seen the example below ...

Example

Consider two multi-line variables :-

years

1979
1980
1981

names

Smith
Jones
Taylor
Johnson
Bryant

If  we multi-merge the variables like this :-

years || "," || names

... we get this :-

1979,Smith
1979,Jones
1979,Taylor
1979,Johnson
1979,Bryant
1980,Smith
1980,Jones
1980,Taylor
1980,Johnson
1980,Bryant
1981,Smith
1981,Jones
1981,Taylor
1981,Johnson
1981,Bryant

Any trailing blank lines in the parameters are ignored.


&

|


rj

See Also

Summary

(a rj b) evaluates to the string a right-justified within a field b characters wide.

Notes

•	If a is already longer than b characters it is not truncated.

Example

write ("test" rj 6)

Writes the string “  test” (that’s “test” with two spaces in front).


lj


lj

See Also

Summary

(a lj b) evaluates to the string a left-justified within a field b characters wide.

Notes

•	If a is already longer than b characters it is not truncated.

Example

write ("test" lj 6)

Writes the string “test  ” (that’s “test” with two spaces after it).


rj


trim

See Also

Summary

(trim a) evaluates to a with leading and trailing spaces and tabs removed.  Spaces and tabs inside the string are not removed.

Example

write (trim "  ab c `t ")

This writes “ab c”.

`t represents the tab character in a string


without


without

See Also

Summary

(a without b) evaluates to a with all the characters in b removed.

Example

write ("Example: use of 'without'" without "':")

This writes “Example use of without”.


trim


+

See Also

Summary

(a + b) evaluates to the sum of a and b.

(+a) evaluates to a interpreted as a number.

Notes

•	Only integer arithmetic in the range -2147483648 .. 2147483647 is supported.

Example

write (49+7)

This writes “56”.


-

*

/


-

See Also

Summary

(a - b) evaluates to the difference of a and b.

(-a) evaluates to (0-a).

Notes

•	Only integer arithmetic in the range -2147483648 .. 2147483647 is supported.

Example

write (49-7)

This writes “42”.


+

*

/


*

See Also

Summary

(a * b) evaluates to the product of a and b.

Notes

•	Only integer arithmetic in the range -2147483648 .. 2147483647 is supported.

Example

write (49*7)

This writes “343”.


+

-

/


/

See Also

Summary

(a / b) evaluates to the ratio of a and b.

Notes

•	Only integer arithmetic in the range -2147483648 .. 2147483647 is supported.

•	Any remainder is lost.

Example

write (49/7)

This writes “7”.


+

-

*


withDrive

See Also

Summary

If a is a file path and b is a filepath or a drive then (a withDrive b) returns a file path made from the directory, file and extension of a but the drive of b.

Notes

Directories and extensions

Example

write ("c:\windows\notepad.exe" withDrive "h:")

This writes “h:\windows\notepad.exe”.


withDir

See Also

Summary

If a is a file path and b is a filepath or a directory name then (a withDir b) returns a file path made from the drive, file and extension of a but the directory of b.

Notes

Directories and extensions

Example

write ("c:\windows\notepad.exe" withDir "\bin\")

This writes “c:\bin\notepad.exe”.


withFile

See Also

Summary

If a is a file path and b is a filepath or a filename then (a withFile b) returns a file path made from the drive, directory and extension of a but the filename of b.

Notes

Directories and extensions

Example

write ("c:\windows\notepad.exe" withFile "calc")

This writes “c:\windows\calc.exe”.


withExt

See Also

Summary

If a is a file path and b is a filepath or an extension then (a withExt b) returns a file path made from the drive, directory and filename of a but the extension of b.

Notes

Directories and extensions

Example

write ("c:\windows\notepad.exe" withExt ".com")

This writes “c:\windows\notepad.com”.


withDriveDir

See Also

Summary

If a is a file path and b is a filepath or a drive and directory then (a withDriveDir b) returns a file path made from the filename and extension of a but the drive and directory of b.

Notes

Directories and extensions

Example

write ("c:\windows\notepad.exe" withDriveDir "h:\bin\")

This writes “h:\bin\notepad.exe”.


withFileExt

See Also

Summary

If a is a file path and b is a filepath or a filename and extension then (a withFileExt b) returns a file path made from the drive and directory of a but the filename and extension of b.

Notes

Directories and extensions

Example

write ("c:\windows\notepad.exe" withFileExt "test.com")

This writes “c:\windows\test.com”.


@

See Also

Summary

(a @ b) returns the b’th line from the input file-variable a — the first line is line 1.  a must be a variable name.

A run-time error will be reported if b is less than 1 or greater than ((linesIn a)+1).  When b equals ((linesIn a)+1) the result is “”.

This operator is unique in that an expression involving it can be used instead of the destination variable in the set command.  This lets you write to individual lines of a file-variable rather than to the whole file-variable.  And if the string you’re assigning is itself made up of more than one line it appears as a number of lines in the file-variable.

Assigning a value to the ((linesIn a)+1)’th line of a has the effect of appending a line to it.  In other words, these two lines are equivalent :-

set (a@((linesIn a)+1))="Hello"

write "Hello" to a

Examples

set lastLine equal to (input@(linesIn input))

Set variable lastLine to the last line in file-variable input.

set (report@1)=((report@1) " - processed by Frogbit")

Appends a comment to the first line of file-variable report.

set (report@1)="This was processed by Frogbit"

Completely replaces the first line of file-variable report with a new line.

set (report@1)=((report@1) "`n... processed by Frogbit")

Inserts a new line after the first line of file-variable report (“`n” represents a newline character in a Frogbit string).


lineNo

linesIn


after

See Also

Summary

(a after b) returns the text which follows the first occurrence of b in a.

Notes

•	If b evaluates to "" then a is returned.

•	If b does not occur in a then "" is returned.

•	after is case-sensitive, use after? for a case-insensitive comparison.

Example

set comment equal to (line after "//")

Sets variable comment to the text following the first “//” in variable line.


before

except

exceptAll

dlmBy..at


before

See Also

Summary

(a before b) returns the text which precedes the first occurrence of b in a.

Notes

•	If b evaluates to "" then "" is returned.

•	If b does not occur in a then a is returned.

•	before is case-sensitive, use before? for a case-insensitive comparison.

Example

set name equal to (line before ":")

Sets variable name to the text preceding the first “:” in variable line.


after

except

exceptAll

dlmBy..at


except

See Also

Summary

(a except b) returns a with the first occurrence of b in a removed.

Notes

•	If b evaluates to "" then a is returned.

•	If b does not occur in a then a is returned.

•	except is case-sensitive, use except? for a case-insensitive comparison.

Example

set info equal to (line except "==> ")

Sets variable info to the contents of variable line, with the first occurrence of “==> ” (if any) removed.


after

before

exceptAll

dlmBy..at


exceptAll

See Also

Summary

(a exceptAll b) returns a with all occurrences of b in a removed.

Notes

•	If b evaluates to "" then a is returned.

•	If b does not occur in a then a is returned.

•	exceptAll is case-sensitive, use exceptAll? for a case-insensitive comparison.

Example

set info equal to (line exceptAll " (see below)")

Sets variable info to the contents of variable line with all occurrences of the text “ (see below)” removed.


after

before

except

dlmBy..at


driveOf

See Also

Summary

If a is a file path (driveOf a) returns the drive part of a.

Notes

Directories and extensions

Example

write (driveOf "c:\windows\notepad.exe")

This writes “c:”.


dirOf

See Also

Summary

If a is a file path (dirOf a) returns the directory part of a.

Notes

Directories and extensions

Example

write (dirOf "c:\windows\notepad.exe")

This writes “\windows\”.


fileOf

See Also

Summary

If a is a file path (fileOf a) returns the filename part of a.

Notes

Directories and extensions

Example

write (fileOf "c:\windows\notepad.exe")

This writes “notepad”.


extOf

See Also

Summary

If a is a file path (extOf a) returns the extension part of a.

Notes

Directories and extensions

Example

write (extOf "c:\windows\notepad.exe")

This writes “.exe”.


driveDirOf

See Also

Summary

If a is a file path (driveDirOf a) returns the drive and directory parts of a.

Notes

Directories and extensions

Example

write (driveDirOf "c:\windows\notepad.exe")

This writes “c:\windows\”.


fileExtOf

See Also

Summary

If a is a file path (fileExtOf a) returns the filename and extension parts of a.

Notes

Directories and extensions

Example

write (fileExtOf "c:\windows\notepad.exe")

This writes “notepad.exe”.


withAll..replacedBy

See Also

Summary

(a withAll fromString replacedBy toString) returns a with all occurrences of fromString replaced by toString.

Notes

•	If a fromString of "" is given a run-time error is reported.

Example

write ("a+b+c" withAll "+" replacedBy "&")

This writes “a&b&c”.


without

contains


dlmBy..at

See Also

Summary

(a dlmBy delimiterString at index) returns the index’th substring of a as delimited by delimiterString.

Notes

•	The first substring is accessed using an index of 1 (i.e. not 0).

•	An index which is less than 1 causes a run-time error.

•	An index which is greater than the number of substrings returns "".

•	A delimiterString of "" causes a run-time error.

•	dlmBy..at is case-sensitive, use dlmBy?..at for a case-insensitive comparison.

Example

write ("cat+dog+duck" dlmBy "+" at 2)

This writes “dog”.


contains


atIndex..len

See Also

Summary

(a atIndex startIndex len length) returns a substring of a starting at the startIndex’th character of length length.

Notes

•	The first character’s startIndex is 1 (i.e. not 0).

•	A startIndex which is less than 1 causes a run-time error.

•	A startIndex which is greater than the length of a returns "".

•	If length exceeds the number of remaining characters from startIndex there is no error — the remaining characters are returned.

Example

write ("cat+dog+duck" atIndex 5 len 3)

This writes “dog”.


dlmBy..at


asLines

Summary

(asLines a) returns a with each ‘|’ character replaced by a newline character.  It is useful when you want to assign a multi-line string to a variable so that you can use the variable as a file-variable.  You can embed a newline character directly in a string using “`n” but the form with ‘|’s is much easier to read.

Example

set years=(asLines "1987|1988|1989|1990|1991")

This sets variable years to a multi-line string of five lines :-

1987
1988
1989
1990
1991


length

Summary

(length a) returns the number of characters in a.

Example

set width=(length line)

This sets variable width to the number of characters in line.


someLeft

See Also

Summary

(someLeft a) returns true if there are any lines left to be read in the input file-variable a.  a must be a variable name.

It is illegal to read from a file-variable when it is already exhausted.

Notes

•	The reset command resets a file so that someLeft will again return true (unless the file is empty).

Example

do while (someLeft input)


noneLeft


noneLeft

See Also

Summary

(noneLeft a) returns true if there are no more lines left to be read in the input file-variable a.  a must be a variable name.

It is illegal to read from a file-variable when it is already exhausted.

Notes

•	The reset command resets a file so that noneLeft will again return false (unless the file is empty).

Example

do until (noneLeft input)


someLeft


lineNo

See Also

Summary

(lineNo a) returns the number of the next line to be read from input file-variable a — the first line is line 1.  a must be a variable name.

When the last line has been read from the file-variable (and noneLeft is true) then lineNo will return (linesIn a)+1.

Notes

•	The reset command resets a file so that lineNo will again return 1.

Example

set prevline equal to (input@((lineNo input)-1))


linesIn

@


linesIn

See Also

Summary

(linesIn a) returns the number of lines in the input file-variable a.  a must be a variable name.

Example

set lastLine equal to (input@(linesIn input))


lineNo

@


nextLineIn

See Also

Summary

(nextLineIn a) returns the next unread line in the input file-variable a, or “” if there are no more unread lines in a.  a must be a variable name.

Example

copy lines until ((nextLineIn input) beginsWith "Section")


lineNo

@

line


arg

See Also

Summary

(arg a) returns the command-line argument at position a, where a is a positive whole number.  If the specified argument was not given then “” is returned.

Notes

•	When using the IDE you can set the command-line arguments for each project using the Run/Command Line menu-option.

Example

write (arg 2)


Run/Command Line

nargs


Note

Directory names which are not followed by a filename or extension must end in “\” or “/” — e.g., using “\windows” will not work, you need to use “\windows\”.

Extensions must begin with an explicit “.” — e.g. using “exe” will not work, you need to use “.exe”.


true and false

See Also

true and false are set by the system when your program is run: true=‘1’ and false=‘0’.

The if command and the if qualifier in the error, leave, pause and refresh commands all act upon the value of an expression known as a condition.  They perform a certain action if the condition evaluates to true — i.e. ‘1’ — and no action or some other action if the condition evaluates to false.

True/false values can be stored in variables and manipulated using the and, or and not operators.

In practice, any non-zero numeric value is treated as true but non-numeric values cause a runtime error to be reported.

It is illegal to attempt to set either of these variables.


if..else..elseif..endif

and

or

not


eof

See Also

NOTE: Do not use eof!
 — use someLeft or noneLeft instead!  The eof special variable will be removed from Frogbit altogether in a later version.

eof is set by the system whenever your program uses the read command to read a line from a file-variable.  If after reading the line there is no more to be read then eof is set to true, otherwise it is set to false.  It is illegal to read from a file-variable when it is already exhausted.

eof is usually set to false by the input command but if the file just input was empty then eof is set to true.

The reset command sets eof to false unless the file is empty.

The copy lines and skip lines commands set eof  to true if their input file is exhausted, otherwise they set it to false.  However, this does not tell whether or not the terminating line was found - use the found special variable for that.

It is illegal to attempt to set this variable.


read

copy lines

skip lines

input

reset

found


input (variable)

See Also

The input variable is the default input-variable in the input, read, copy lines and skip lines commands.  This simplifies programs which only use a single input file.


input (command)

read

copy lines

skip lines

output (variable)


output (variable)

See Also

The output variable is the default output-variable in the output, write, copy lines and skip lines commands.  This simplifies programs which only use a single output-file.


output (command)

write

copy lines

skip lines

input (variable)


line

See Also

The line variable is used in commands which read or write single lines from/to file-variables.  It is the default in the read and write commands and is always used by the copy lines and skip lines commands.


read

write

copy lines

skip lines


clipboard

The clipboard variable gives you access to the Windows clipboard.  If you set clipboard it puts text onto the Windows clipboard; if you use the value of clipboard in an expression it gets text out of the Windows clipboard.

Note: although it is legal to use clipboard as an input or output file-variable you will find that using it as an output file is very inefficient and it is better to output to some other variable and then set clipboard to that variable at the end.


afile

See Also

The afile variable is used by the for each command to store the path to the current file.

It is illegal to attempt to set this variable.


for each..next


currentDir

See Also

The current directory is where files are looked for if no explicit directory is given.  It starts off set to the directory of the running Frogbit program but it can be changed using the in command.  The value of the variable is always the current directory.

It is illegal to attempt to set this variable or to use it as a file-variable.


in


chosenFile

See Also

This variable is the default into which the choose input/output file command writes the selected file path if no variable is explicitly given.


choose


chosenItem

See Also

This variable is the default into which the choose list item command writes the selected item if no variable is explicitly given.


choose


nargs

See Also

This variable holds the number of command-line arguments passed to the Frogbit program.


Run/Command Line

arg


nextLine

See Also

This variable returns the next unread line in the file variable most recently used for input.

You should only use nextLine when it is clear from the context which file variable has been most recently used for input; otherwise use the nextLineIn operator instead.  One situation where using the nextLine variable is recommended is in the copy lines and skip lines commands.


nextLineIn

line


The file-variable most recently used for input is the one which was last used (as an input file) in one of the following commands :-

•	read

•	input

•	reset

•	copy lines

•	skip lines


found

See Also

This variable is set by the copy lines and skip lines commands according to whether the terminating line was found or not.

If the copy or skip stops because a while condition evaluates to false or because an until condition evaluates to true then found is set to true.  Otherwise found is set to true.

Note that found is generally set to the same as the result of testing the input-file-variable used with the someLeft operator because if the terminating line is not found the copy or skip carries on until there are no lines left in the file.  However, this is not the case if the very last line in the file satisfies the while or until condition: then someLeft will be false but found will be true.


someLeft

noneLeft

copy lines

skip lines


Recipes: The basics

Some things are common to all simple Frogbit programs.

Loading from and Saving to Files

In most programming languages you can read from a text file (i.e. on disc) a line at a time — or write to a text file a line at a time — but Frogbit uses text files in an unusual fashion.

In Frogbit to read a text file a line at a time you :-

•	input .. the text file’s entire contents into a variable

•	read .. from the variable a line at a time

You don’t have to read it a line at a time though, you can use the variable which contains the file contents just like any other variable — as a single (multi-line) string.

To write to a text file a line at a time you :-

•	write to a variable a line at a time

•	output the variable’s contents to the text file

You can write the contents of any variable (or expression) straight to a file on disc; you don’t have to write to it a line at a time.

Inputting a File into a Variable

The first thing that most simple programs do is to input text from a file — using the input command :-

input "report.txt"

This example uses a fixed filename, alternatively you can have the user select a file when the program is run or you can pass the filename as a command-line argument.

If no explicit directory is given the file is looked for in the current directory.

Unless you need more than one input file you can omit the to parameter when using the input command (as is done above) and it will default to putting the text into the variable called input.  This is convenient because the input variable is the default for the read, copy lines and skip lines commands too.

Outputting a Variable to a File

The last thing that most simple programs do is to output text to a file — using the output command. :-

output "summary.txt"

As with input you can omit the from parameter unless you need to use more than one output-file.  If you do the command defaults to getting the text from variable output.  This variable is the default for the write, copy line and skip lines commands too.

So in what follows we’ll assume that the input file is input and that the output file is output — until we look at examples which need more than one input or output file.

Scanning the Input File

Let’s look at an absurdly simple Frogbit task — reading all the lines in the input file and writing them to the output file unless they’re blank.  Here is one way to do it :-

// examples\recipes\basics\remblank using read and write.fp
do while (someLeft input)
  read
  if (line<>"")
    write
  endif
loop

And here is another way :-

// examples\recipes\basics\remblank using copy lines.fp
copy lines where (line<>"")

Using copy lines is faster and shorter than the first method but it’s not so flexible.  For example, you could enhance the first method to count the number of lines which contain the word “observation” while it copied :-

// examples\recipes\basics\remblank and count.fp
set count equal to 0
do while (someLeft input)
  read
  if (line<>"")
    write
    if (line contains "test")
      set count equal to (count+1)
    endif
  endif
loop

You couldn’t do this with copy lines.


Recipes: Extracting data from a report

There are several aspects to this :-

•	alternately skipping and copying sections of the report

•	extracting data from individual lines

•	routing data to different output files

Alternately skipping and copying sections of the report

This is done using the copy lines and skip lines commands inside a do..loop structure.  Here is a simple example which copies all the text except between lines beginning “Summary” and “Total” :-

// examples\recipes\extracting\chop
do
  copy lines until (line beginsWith "Summary")
  skip lines until (line beginsWith "Total")
loop until (noneLeft input)

Extracting data from individual lines

This is done using the matches operator.  As an example we extend the previous code to extract the total and month given on the last line of each skipped section and report it in a different format :-

// examples\recipes\extracting\chop and total
do
  copy lines until (line beginsWith "Summary")
  skip lines until (line beginsWith "Total")
  leave if (not found)
  if (line matches "Total for ~(town), ~(month) ~(year): ~(total)")
    write ("--> " town ": " total " (" month " " year ")")
  else
    write ("*** unrecognised total line: " line)
  endif
loop

For example, if this line is read :-

Total for Bridgetown, January 1996: 3321

... then this line be will be written :-

--> Bridgetown: 3321 (January 1996)

Routing data to different output files

Sometimes you want to break a report up into several output files.  For example, you might want to extend the above example so that each section is output to a file named after the date in the totals line :-

// examples\recipes\extracting\chop and total and route
do
  copy lines until (line beginsWith "Summary")
  skip lines until (line beginsWith "Total")
  leave if (not found)
  if (line matches "Total for ~(town), ~(month) ~(year): ~(total)")
    write ("--> " town ": " total " (" month " " year ")")
    output (town " " month " " year ".txt")
    set output equal to ""
  else
    write ("*** unrecognised total line: " line)
  endif
loop


Recipes: Scanning Files in a Directory

When you want to process all the files in a directory whose name matches a certain pattern you use the for each command.  Here is an example which extracts the first non-blank line (if any) from each file whose name matches “*.TXT” and writes it to output :-

// examples\recipes\scanning\first.fp
for each file "*.TXT" in "c:\windows"
  input afile
  skip lines until (line<>"")
  write (afile ": " line)
next

The code between for each and next is executed once for each file which matches “*.TXT”.  The variable afile is set to the full path to the file and is used here in the input command to read the contents of the file.

Then the skip lines command is used to skip blank lines and the first non-blank one which is left in variable line is written to output.

Note: you will have to change the for each line if your Windows directory is not “c:\windows”.


Recipes: Letting the User Select Files

Most Frogbit programs take input from — and send output to — disc files.  But which disc files?  There are various techniques you can use, depending on the particular problem.

Fixed Names

This is simple but inflexible.  You just hard-wire the names of the files in your program, for example :-

input "myfile.dat"

Arguments

Using command-line arguments lets you write a program which can operate on different files, depending on the arguments passed to it when it is run.

All Files in a Directory

See Scanning Files in a Directory.

Filenames from a File

You can take your list of files to be processed from a text file :-

input "filelist.txt" to list_file
do
  read from list_file
  input line
  // (process file “input” here)
loop until (noneLeft list_file)

Using a Dialog

You can prompt the user to select a file using the choose command, for example :-

choose input file title "Data File" filters "Text files|*.txt|Data files|*.dat;*.inp"

This prompts the user with a standard Windows open-file dialog box, titled “Data File” and with two extension filters: “Text files” giving “*.txt” and “Data files” giving “*.dat” and “*.inp”.


Using FrogbitRUN

The Frogbit IDE is designed for developing and debugging programs rather than running completed ones.  When you have finished a program and want to use it routinely you may find it convenient to use the FrogbitRUN program to create a shortcut on your desktop (or in your Start/Program menu or some other folder) so that you can run your program just by selecting the shortcut.

FrogbitRUN is not an interactive program like the IDE, you run it with a command-line specifying the name of the Frogbit program to run (plus its command-line parameters) and FrogbitRUN executes the program.  The only interaction you have while the program is running is a large button reading Stop the Program.

Parameters

FrogbitRUN needs at least one parameter: the name of the Frogbit program to be run.  You need to specify the full drive and directory of the file but you can omit the extension and it defaults to “.FB”.  Note that it is the .FB file that you run rather than the .FP file (which contains information for the IDE).

Any parameters following the Frogbit program name are command-line parameters for the Frogbit program itself.

You can arrange to be prompted to enter parameters every time you run the shortcut.  Simply finish the list of parameters with a parameter consisting of a single ? character and you will be prompted to add to or edit the parameter list before the Frogbit program is run.

Creating a Shortcut

This is how you can create a shortcut that you can double-click to run your Frogbit program.  You can create it in any of these places :-

•	on the desktop

•	in an open folder

•	in the right-hand pane of an Explorer window

You have to click on ‘empty space’ — i.e. not on the name or icon of a folder or file.

First of all right-click on the desktop (or wherever); select New from the first menu and then select Shortcut from the next menu; you will see a dialog box like this :-

Enter the path to the FrogbitRUN program, followed by the path to the Frogbit program you want to run, followed by any command-line parameters for your Frogbit program.  It might look like this :-

C:\Frogbit\FrogbitRUN C:\MyFrogbit\Extract.FB jan.txt

... or if you want to be prompted to enter parameters it might look like this :-

C:\Frogbit\FrogbitRUN C:\MyFrogbit\Extract.FB ?

You can select the path to the FrogbitRUN program using the Browse button.

Now click the Next button and you will see a dialog box like this :-

Change the default name from “FrogbitRUN.exe” to something more informative; such as “Extract Jan Figures”.

Finally, click the Finish button.

Once you have a shortcut you can drag it to a different location.  And you can delete a shortcut without affecting any of your other programs or files.


IDE FAQ

Why can’t I edit my program ( I just get a beep)?

The Frogbit IDE has two operating modes: editing-mode and run-mode.  It starts off in editing-mode — the screen background is white and you can edit your program.  When you start your program running using Run/Go, Run/Step or Run/AutoStep it switches to run-mode — the screen background goes cyan and you can no longer edit your program.

If and when your program finishes the IDE will return to editing-mode automatically.  Otherwise you can return it to editing-mode at any time by aborting the program run using Run/Halt.  Note that you have to do this after a runtime error.

How can I re-highlight a line in the editing window?

When you’re stepping through your program the next line to be executed is highlighted.  Similarly, when you compile or run your program and an error is found in the text the line in question is highlighted.

If you click on the editing window you lose the highlight position; to get it back use View/Highlight in the menu.

I’m having trouble editing previous entries in the watches window

One problem with this window is that when you move to a cell in the first column to edit it you find that all the text is selected.  It is easy enough to type in a completely new entry, but sometimes you want to edit what’s there already.

The solution is to either press the F2 function key or to single-click on the text with the left mouse button.

I am aware that the watches window does need some attention in other areas — for instance: cut, copy and paste.


General FAQ

How do I handle comma-delimited records?

Here are two approaches to extracting fields from comma-delimited records.  They both use “Smith,John,108 High Street” as an example record :-

Using dlmBy..at

This operator can be used to extract a single field from a record.  For example, to extract the 2nd field from variable record you would use this expression :-

(record dlmBy "," at 2)

... returning “John”.

Using matches

The matches operator can be used to extract all the fields from a record at once.  For example, to extract all the fields from variable record you would use this expression :-

(record matches "~(lastName),~(firstName),~(address)")

... returning “1” to indicate a successful match but also setting variables lastName=“Smith”, firstName=“John”, address=“108 High Street”.

How do I handle fixed-width columns?

Use the atIndex..len operator.  For example, to extract three successive columns of lengths 6, 10 and 20 from variable record use :-

set c1=(record atIndex 1 len 6)

set c2=(record atIndex 7 len 10)

set c3=(record atIndex 16 len 20)


Legal Stuff

Frogbit V0.97

This software is provided 'AS IS' and the author makes NO WARRANTY or representation, either express or implied, with respect to the software, its quality, accuracy or fitness for a particular purpose.

Axiomatic Software makes no charge for this version of Frogbit and you are free to redistribute the complete unmodified installation program FB-097.EXE.  It is a violation of this agreement to distribute Frogbit or any part of it except as the complete unmodified installation program.

This software is Copyright © 1996, 1997 Axiomatic Software.

"Microsoft" and "Windows" are trademarks of Microsoft Corporation.

Any other trademarks mentioned are acknowledged.


Contacts and Frogbit Online
Contacts, Frogbit Online

Email

We welcome all sorts of feedback and will be happy to help you out with problems you are having using Frogbit.  Just email us at frogbit@axiomati.demon.co.uk or at our Compuserve id of 100273,1543.

If you want regular emails on what’s happening with Frogbit just mention it in your message.

World-wide web

The best way to keep up with what’s happening with Frogbit is through our WWW page :-

http://www.axiomati.demon.co.uk

This is where you’ll find :-

•	new versions of Frogbit

•	the latest version of the FAQ

•	new example code, hints, tips

You can browse straight to the web page from the IDE Help menu if your browser is set up for it.


comment-out

To comment-out a line of a Frogbit program is to precede it by “//”.  This turns the line into a comment so it’s ignored by the compiler.  It’s handy when you might want to put the code back again later — just remove the “//”.


IDE

The Frogbit IDE is an ‘integrated development environment’.  It is used to edit your program and run it in a helpful debugging environment.