 |
Using Sogol |
|
Contents |
Introduction |
|
|
|
|
What is Sogol
|
Sogol is a math assistant and calculator program for Windows. It can help with a wide variety of problems, from calculating networks of formulae, to performing dynamic simulations, to computing solutions to multiple equations in multiple unknowns. It's browser-like interface doubles as a hypertext notepad, which can be used to document the calculations in a web. |
|
Screenshots: |
The Sogol screen has three main panes and a toolbar. The left pane is a selectable list of the cells in the current web.
The right-bottom pane is used for calculation and script input/output and output from a report generator feature.
The right-top pane has four tabbed fields, including: The text field of the selected cell. The value field of the selected cell. The script field of the selected cell. Plot output from the current or most recent run.
In the text and script panes, cell names are highlighted. Clicking a highlighted cell name makes that cell the selected cell. Double-clicking a word that is not a cell name creates a cell of that name, and make it the selected cell. |
|
To what uses may Sogol be put? |
Sogol has many capabilities. Among other things, it can assist the user to: Make webs of arithmetic formula’s and use them to compute anything of interest, such as work estimates, units conversions, stress & strain formulas, critical path in a schedule, or return on investments. Iterate the computation of formula webs to model dynamic systems, solve differential equations, and simulate cellular automata and neural networks. Apply numeric formulae to cognitive maps or causal networks, making them provide quantitative information about the domains modeled. Compute the steady state conditions of fuzzy cognitive maps. Use the script language to perform numerical analysis tasks, such as computing the roots of equations, solving multiple simultaneous equations, integrating a function over a domain of interest, or interpolating between data points with a smooth curve. Try out algorithms before implementing them in other computing environments. Use the scripting language to simulate processes of interest. Plot the results of computations in a
built-in plotting window, or export data in conventional formats
to spreadsheets or graphics packages. In addition, Sogol's browser-like user interface provides a builtin hypertext notepad, which assists the user with tasks such as: Describing the calculations in a web |
|
Sogol Demo Version |
The Sogol demo version is fully functional, except that it does not print, and it occasionally nags the user to register the program.
To find out how to register Sogol, the user may select the Help menu item About Sogol, and click the RegInfo button on the dialog that appears.
The user will be instructed to go to website www.codelode.com to register the program. After the user has paid the registration fee, and supplied the necessary information, he will receive a registration key via email. Information supplied for purposes of registration will not be sold or given away to third parties. See the section called Registration for information on entering the registration key into the program.
|
|
|
|
|
Installing Sogol |
Your Sogol program should have arrived as a self-extracting archive, containing Sogol.exe, SciLexer.dll (the freeware edit control used by Sogol), and a bunch of other files. Installation consists of double-clicking the self-extracting archive, and following instructions. If you did not receive such a self-extracting archive, go to www.codelode.com and download one.
|
|
Using existing webs |
Sogol comes with a collection of sogol application files (extension .sog) as well as a few Textweb files. Textweb is a hypertext notpad with which Sogol is file compatible. If the installation went smoothly, you will be able to launch one of these webs by simply double-clicking it. If the extension was not properly identified to the operating system, you will have to launch Sogol, and then open one of the sample webs.
The home cell of a sogol web is typically is used to document (in the text field) the purpose of the web and how it is used. A good web to try first is piggy, since it has perhaps the simplest computation of the lot.
Choosing Run from the Actions menu, or clicking on the running figure executes the script of the current cell and any scripts it may invoke. Although the home cell is often the cell which is the root of the desired computation, often it is not. If the home cell is not the place to start computing, the documentation in the text field of the home cell should tell you which cells perform what calculations.
Mess around with some of the sample webs and get familiar with linking between cells, creating new cells, running scripts, changing the settings and so on. It won’t take long. You’ll be creating your own useful webs in no time.
|
|
|
|
|
The Settings Dialog
|
Click on the Edit menu, Settings choice. The following dialog will appear:
The individual tabs allow the user to specifiy Sogol behavior and appearance with regard to Links, Reports, Output, Input, Numbers, Execution, and Plotting. In the picture shown, the Links tab is chosen, which allows the user to choose from four link colors, and to activate automatic cell creation on double clicking of words that are not cell names. It also allows the user to specify a dialog box be displayed before creating a new cell based upon a double-click. |
|
Choosing
Output |
Choosing the Output tab brings up the following dialog:
There are three kinds of Sogol output, not counting plotting. These are report output, automatic output, and script output. Report output is produced when the user chooses to call for a report. Automatic output is produced once per iteration (see execution settings) showing the values of cells that have changed. Script output is produced by the 'Out' statement in the Sogol language.
With the Output dialog, the user can direct output to the output window on the screen, to a text file named in the Output Name field, or to the printer, with a page heading supplied in the Output Name Field.
|
|
Choosing Input Source |
The script language has an In( ) statement, which accepts input from a dialog box, a file, or from the text field of a named cell. The Input Source combo box is used to choose between those three options for a particular web. When input from a file is selected, Input Name contains the file name, less extension, which is assumed to be .txt . When input from the text field of a cell is selected, Input Name contains the name of the cell from which input will be taken. When the input comes from a generic dialog box, the Input Name field is ignored. |
|
Specifying Report Output |
Choose the Report tab, and the dialog below appears. This tells Sogol what to do when the user requests a report
Report type allows four choices: Formatted, In Pointers, Out Pointers and Trail.
For each cell name selected the text edit window, or if the Report on All Cells button is pressed, for all cells, the formatted report generator scans the Report Format string supplied, outputting it’s characters one by one until it encounters a substitution code, such as \n, \N, or \T.
When \n is encountered, a carriage return linefeed is output to the output destination in place of the ‘\n’ string. When \N is encountered, the cell name is output instead of the string ‘\N’. When \T is encountered, the contents of the text field of the cell is output instead of the string ‘\T’. When \ is encountered, whatever character follows it the format string, including ‘\’ is output to the output destination.
If Inpointers is selected, then for each cell name selected in the text edit window, or if the Report on All Cells button is pressed, for all cells, the report generator puts out the cell name, followed by a list of cells which point to that cell name.
If Outpointers is selected, then for each cell name selected in the text edit window, or if the Report on All Cells button is pressed, for all cells, the report generator puts out the cell name, followed by a list of cell names which are pointed to from that cell.
If Trail is selected, then the report generator merely outputs all of the cellnames in the stack kept in the combobox.
|
|
Choosing Number Formats |
Value fields of Sogol cells may contain numbers or strings. Numbers are stored internally as floating point, but the manner of their display is controlled by the Number dialog. General numbers are displayed as decimal numbers until their 10's exponent exceeds the number of digits specified, at which point they are displayed in scientific notation. Fixed point numbers are displayed with the number of decimal places specified in number of digits. Exponential numbers are displayed in scientific notation with a precision which depends upon the number digits specified. All trigonometric builtin functions assume that their arguments are in either degrees or radians according to the setting of Trigonometry Units. |
|
Choosing Execution Parameters |
When the user chooses Run from the Actions menu, or clicks on the running figure in the toolbar, the script of the selected cell is executed the number of times specified in Number of Iterations.
If a form of Automatic Output is selected, an output record is produced after each iteration.
If Generic List is the type of automatic output selected, Sogol outputs the names and final values of each cell that changed during the iteration which just finished.
If Formatted List is the type of automatic output selected, then a formatted list of results is output at the end of each iteration. The format of the iteration output list is contained in the List Format entry of the Execution dialog. Format of the Header Line If the first character of the List Format is a tilde ('~'), no header line is generated for the calculation. If it is not a tilde, the header line is generated in accordance with the following rule: A newline is output. Then the contents of the List Format string are copied directly to the output, except that any percent signs in the format string are ignored. Wherever the character pair '\n' appears in the List Format, it is replaced with a newline sequence. Format
of Each Iteration Chunk The contents of the List Format string are scanned, and copied to the output until a percent ('%') sign is encountered. The next word after the percent sign is read to determine if it is a valid cell name. If it is, the current value associated with that cell is substituted for the cell name in the output string. Scanning and outputting of the List Format string is then resumed until the next percent sign or the end of the string is reached. Wherever the character pair '\n' appears in the List Format, it is replaced with a newline sequence. NOTE 1: The selection of cells for formatted output is controlled entirely by the format string, and has nothing to do with the actual cells whose scripts are executed. This is necessary so that you can view only certain cells at each iteration, regardless of how many cells are executed. NOTE2: Automatic Output is intended to support computations involving webs of expressions which refer to each other. With automatic output enabled, one needn't include any out( ) statements in the scripts to get a clear idea what happened at each iteration. When using scripts which manage their own iteration with while or for statements, and their own output with out statements, it is best to set the number of iterations to 1 and to turn automatic output off. |
|
Setup Plotting |
The Plotting dialog allows the user to determine two cells that will plotted against each other each time one or the other of their values changes. It also allows setting the maximum and minimum values and number of intervals for each axis.
The cells associated with the independent and dependent variables, X and Y, are selected from all the cell names in combo boxes.
The plot limits are defined by the fields Xmax,Ymax, and Xmin,Ymin. Only coordinate pairs which lie within those limits show up on the plot.
The number of intervals between Xmin and Xmax, and between Ymin and Ymax, are determined by the fields Xintervals and Yintervals.
The color of the plot is determined by the selection of a color from the Plot Color group of buttons.
|
|
|
|
|
Sample Reports (default formatted report from cave.twb) |
*****AttackTheGnome************************** You thrust your torch into the gnome's face, he dodges; and his broad axe separates your head from your shoulders. Your last impression is of the passageway tumbling crazily in your vision; and the sound of rushing water..... then icy silence.
*****ClimbTheRockChimney************************** You climb for an hour before coming into the sunlight through an opening by a juniper bush on the side of a rocky slope. A rumbling sound intensifies around you, and you leap just in time to avoid the cave-in which closes the chimney from which you just emerged. You can see the lights of your neighboorhood just a short hike down the mountain. Strange adventure.
*****DiveIntoTheTorrent************************** That was a hugely stupid thing to do! The water siezes you and plunges you through a winding cavern, rushing down without air, until you begin to feel strangely separate from yourself, observing as from a distance.
Suddenly, you break the surface. Your lungs gratefully gulp great draughts of air. A second later, the water slows down. Soon you are in a placid lake, surrounded by translucent, glowing crystal walls. You crawl onto a sparkling beach, and lie there exhausted.
Without warning, a booming voice enfolds you in its thunderous sound: "Be who you are." You look around, but nobody else is there.
Seeing no way out of the crystal cavern, you remember that you followed links from the home cell to get here. All you have to do to get home is just keep pressing Alt-left arrow.
*****EnterTrapDoor************************** You are an adventureous soul. You drop lithely into a shallow pit below the trapdoor, which slams shut above your head. Before you is a passageway leading into the dimly lit bowels of the earth. A torch burns in a niche in the rock wall of the passage. You're in luck! The torch can be removed from its niche. You may choose to TakeTorchIntoPassageway, or GoBackToShack.
*****Fossil************************** The only treasure in here is the exposed bed of limestone, rich with the fossilized history of the evolution of life on this planet.
*****GoBackToShack************************** Unfortunately, the trap door above your head will not open, no matter how you pound on it. You may choose to LayDownAndDie or TakeTorchIntoPassageway..
*****GoHomeAndWatchTV************************** A wise, and safe decision. On the way home you find $5 lying on the street. You congratulate yourself on your good fortune, and stop at a convenience store to purchase popcorn. There is a good movie on tonight!
*****home************************** You are standing on a trap door in an abandoned shack in the forest. On the table before you is a map, apparently of subterranean caverns. Much of the map has been destroyed by time, but there is a section of the map that can still be read. On that section is the legend: "Here there be treasure".
If you choose to EnterTrapDoor, you may be able to find the treasure, and become rich. On the other hand, you may get lost, and leave nothing but your bones behind in a dimly lit crevasse far under the ground. If the risk is too great, you may decide to GoHomeAndWatchTV.
Click the link of your choice.
*****LayDownAndDie************************** Quitter!
*****Noway************************** There is no treasure in this cavern, which is not accessible from any other passage in the Cave. How did you get in here?
*****SmileAndBrushPastHim************************** You smile politely and step nimbly around the little fellow, finding yourself suddenly in a cavern full of the sound of rushing water. From a ridge on one side of the room, there is a shaft of light coming down a rock chimney. On the other side, the river disappears into a hole in the wall. There is no air space in the hole, just rushing river.
You can ClimbTheRockChimney or DiveIntoTheTorrent.
*****TakeTorchIntoPassageway************************** As you descend the passageway, you begin to hear trickling sounds, and to see rivulets of sparkling water along the path. Ahead, in the gloom, a pair of eyes appears; and you hear an ominous chuckling.
Suddenly you are confronted with a fabulously ugly little gnome, who is carrying a broad axe, and clearing his nostrils noisily on your feet.
You must decide whether to AttackTheGnome, or SmileAndBrushPastHim.
|
|
Sample Reports (inpointers report from meditation.twb) |
AdviceToBeginningMeditators |
|
Sample Reports (outpointers report from DIBPrinting.twb) |
biBitCount |
|
Sample Reports (trail report from DIBPrinting.twb) |
Trail: |
|
|
|
|
Executing a Script |
If necessary, set execution preferences by accessing the Execute tab of the Settings dialog. Position to a cell which contains a script that you wish to interpret. Choose Run from the Cell menu or press the Run toolbar button (running figure). The script of the cell will be executed, and if an arithmetic expression statement is executed, its result will be placed into the value field of the cell. If the script contains references to other cells followed by exclamation points or argument lists, the script's of those cells too, will be executed. If the Execute Settings dialog calls for automatic results to be output, or if Out() or Report() statements are part of the script, the results of their execution will be directed to the current output stream. |
|
Contents of Script Fields |
Script fields may contain sequences of script language statements, which are evaluated in order, or as directed by if, for, or while statements. Examples of valid script field contents are shown below: if(y<1)
{ An expression is a valid script language statement, so script fields may contain one or more arithmetic expression statements. The cell takes the value of the expression statement most recently evaluated. 123*home/4.1 See the Sogol Script Language section for details on the syntax of the script language. |
|
Expressions and Formulas |
An expression is a prescription for arriving at a new value from a combination of numeric and string values, and the results of built-in function calls. Examples include: 1 A formula is a script language statement which consists of a single expression. When a script containing a formula is executed, the content of its value field is replaced by the value computed for the formula. |
|
Rules for Referencing Other Cells in Expressions |
Sogol allows the script of one cell to contain references to other cells. There are two kinds of references: execution references (cellname followed by exclamation point or argument list), and value references (cellname not followed by exclamation point or argument list). An execution reference to a cell causes that cell's script to be executed, and assumes the value of that cell after the script has been executed. The execution reference is like a function call in most programming languages. Examples of execution references: # without arguments A value reference to a cell does not execute the script of the cell referenced, but it does take on the value of the cell referenced. A value reference is like a variable reference in most programming languages. Example of value reference: #
no
bang or parens in value reference Using Execution References The example below illustrates a simple application of the execution reference: The web Example1 has two cells, a and b. Their values and formulas are shown below: Cellname: a Cellname:b When cell a is executed, the b() in its formula is resolved by computing a value for b, and substituting it into the formula for a. When the computation is done, the value in b is 17, and the value in a is 13. The new values of a and b are independent of their previous values. In the web Example2, the formula in cell a contains an execution reference to the formula in cell b, and the formula in cell b contains an execution reference to the formula in cell a. Cellname: a Cellname: b When the formula for cell a is interpreted, the execution reference to b causes the program to first attempt to evaluate the formula in cell b. The formula in cell b, in turn, requires an interpretation of the formula in cell a. This computation cannot be carried out, as it will repeatedly start new interpretations of each cell until it runs out of memory, and a STACK OVERFLOW ERROR is generated. An execution reference to a cell which does not have a script expression or set the cell's value behaves like a value reference to that cell.
The example below illustrates how a script interpretation proceeds when cell references are not followed by exclamation points or argument lists. The web Example3 also has two cells, a and b, whose values and formulas are shown below: Cellname: a Cellname: b When the scripts of these cells are interpreted a first, then b; the execution proceeds as follows: Cell a is set to the value of cell b, 21, minus 7, giving 14. Cell b is set to the value of cell a, 14, plus 4, giving 18. When the scripts are interpreted b first, then a; the execution takes a different path: Cell b is set to the value of cell a, 14, plus 4, giving 18. Cell a is set to the value of cell b, 18, minus 7, giving 11. Since the cell references in each cell a and b were to the current value of the cell, and didn't request recalculation (no argument list empty or otherwise), there is no problem with stack overflow. It is important when computing values of cells which refer to each other to consider the order in which interpretation takes place. This is always necessary in programming languages, but is less commonly necessary in cellular calculators.
|
|
Number or String? |
During evaluation of expressions, a cell value may be automatically converted from a number to a string or vice versa, depending upon what operation is applied to it. In a numeric operation, such as: maize + beans the operands maize and beans must be numeric, so their values will be forced to numbers if they are not numbers already. In a string operation, such as: maize cat beans the operands maize and beans must be strings, so their values are forced to strings if they are not strings already. In a context where the same operator applies to both numbers and strings, there are special rules to decide which to use. When assigning a value with the set statement: set maize to <expression> maize takes the type (string or number) of the expression. In a comparison: if(expr1=expr2) if both expressions are numeric, a numeric comparison is made; otherwise any numeric operand is converted to a string, and a string comparison is used. There are two convenient methods for converting an expression from one type to another: number cat "" concatenate a null string to a number to force it to become a string. String + 0 add zero to a string to make it a number. To force a string comparison between two expressions, coerce one to a string: expr1 cat "" = expr2 To force a numeric comparison between two expressions, coerce both to numbers: expr1+0 = expr2+0 The numeric value of a string is the value of the longest prefix of the string that looks numeric. Thus when the following strings are converted to numbers: "1E5"+0 "All my relations"+0 "1X15.21"+0 The numeric results are: 100000 0 1 The string value of a number is computed by formatting the number in accordance with the numeric type and number of digits in force at the time of the conversion. See the section entitled "Numbers Preferences". |
|
Sample Calculations |
Circle The area of a circle is easily computed in two cells: cellname formula ----------------------------------------------- r (no formula...put value of radius in value field) AreaCirc pi*r*r The calculation is performed by positioning to the cell r, and entering a value for the radius, and then positioning to the cell AreaCirc, and pressing the Execute button on the toolbar . It is not necessary to include a cell with the value of pi since this value (as well as the value for the base of the natural logarithm e) is built in to the Cellweb program. Payment The web called "Payment" allows you to compute the monthly payment necessary to pay off a loan of a given amount, at a prescribed interest rate, in a specified number of payments. The Payment web uses cells with the following formulas to compute the monthly payment: cellname formula ---------------------------------------- apr (no formula... enter annual periodic interest rate) home pymt! i apr/12 n (no formula... enter number of monthly payments) power pow(1+i!,n) prin (no formula... enter the beginning balance) pymt prin*power!*i/(1-power)
Use the following procedure to obtain a result from the Payment web: 1) Put the annual periodic interest rate into the value field
of the apr cell. Make sure that you use the decimal
fraction (such as 0.075 for 7.5%). Since the home cell has the formula: pymt!, you may also compute a result by positioning to the home cell and clicking the Run toolbar button. Notice in the cell pymt that the first occurance of power, and the reference to i, are execution references. The '!' after the first power reference assures that the formula for power is executed whenever the formula for pymt is executed. There is no '!' after the second reference to power because it is not needed, the value having already been computed. The '!' after i ensures that the periodic interest is computed from the annual periodic interest rate, apr, whenever pymt is computed. Pert One of the sample webs provided on the Cellweb distribution disk is called "Pert". The Pert web describes the tasks involved in building a small house, and organizes those tasks according to which ones may be carried out concurrently. There are three different paths through the web of tasks, from start to completion. The three paths may be browsed in the web by following hypertext links. The are also described in three summary cells called path1, path2, and path3. Those cells contain formulas which compute the total time required to traverse the associated paths. The Pert web uses cells with the following formulas to compute the time taken by the three paths through the construction process: cellname formula
--------------------------------------------------------------------
path1 ClearLand+BuildFoundation+BuildUpperStructure+
PlumbingWork+CompleteInterior
path2 ClearLand+BuildFoundation+BuildUpperStructure+
ElectricalWork+CompleteInterior
path3 ClearLand+BuildFoundation+BuildUpperStructure+
CompleteExterior+LandscapingBy entering the estimated time it takes to complete each of these tasks into each task's cell, the times taken for each path through the process may be computed from the formulas. Pert has another cell and formula: CriticalPath max(path1!,path2!,path3!) When the CriticalPath cell is executed, the time necessary to build the house is placed into its value field. The '!'s after the references to path1, path2, and path3 ensure that new values for these cells are computed every time the cell CriticalPath is executed. If the '!'s were not there, it would be possible to change the values upon which path1, path2, and path3 depend, and to compute CriticalPath without the new values being reflected in the values of path1, path2, and path3. The value of CriticalPath would not then be changed, even though, for instance, the value of ClearLand did change. NOTE: The action of this web or any web would be unchanged if the exclamation points, !, were replaced by the empty parenthesis pair, ( ). Logistic The emergence of chaotic dynamics from simpler behavior may be observed in this example called the logistic map: cellname formula --------------------------------------------------------- r (no formula...set this parameter to alter dynamics) x r*x*(1-x) To explore the behavior of this calculation, set the number of iterations to 20 or so, set different values for r and x (make sure x is between zero and one), go to cell x, and execute it. For a value of the parameter r of 0.4, and an initial x value of 0.7, successive values of x approach zero and stay there. For an r value of 2.4, and initial x value of 0.7, successive values of x approach a constant 0.583 For r=3.0, and an initial x of 0.5, an extended damped oscillation takes place between two values of x. For r=3.5, initial x=0.7; an extended oscillation among four numbers takes place. For r=3.8, initial x=0.7; a chaotic sequence of numbers is the result.
Amort This sample web computes the approximate principal balance and amount paid in interest each month, given an annual periodic interest rate, and the principal balance the previous month. The cells in the web, and the formulas they contain are: cellname formula
-----------------------------------------------------
apr (No formula....constant entered by user)
home month! prin!
itm mi!*prin
(monthly interest rate times last months principal)
mi apr/12 (annual periodic interest rate/12)
month month+1 (number of the month...start at 0)
prin if(prin>pymt) {
prin+itm!-pymt
} elseif(prin>0) {
0
} else {
exit
}
pymt (No formula....constant payment amt entered by user)The reference to mi in the formula for itm, and the reference to itm in the formula for prin are execution references to make sure that the values of mi and itm are computed before they are used in the first iteration of the calculation. The formula for the prin cell illustrates the use of the if structure to control the number of iterations actually computed ( no more than necessary to cause the principal to reach zero). The formula in the home cell illustrates the use of multiple expressions in a single formula. The expressions are evaluated from left to right. Since these are execution references, the cells referred to are recomputed each time home is executed. After each expression is evaluated, the value of home is set to the value of the expression. Thus, when execution is complete, the value of home is found to be the same as the value of prin. To use this web, put the beginning principal into prin, the annual periodic interest rate, as a decimal fraction, into apr, the monthly payment into pymt, and initialize the month to 0. Set the number of iterations (See Execution Preferences) somewhat larger than you expect the number of required months to be, and execute the home cell. The monthly change in principal will be displayed as the calculation progresses. Negative amounts indicate debt accumulating rather than being paid off.
There is a method of iteratively solving second order differential equations, called Runge Kutta, which, to third order accuracy, is described by the following set of equations: yn+1 = yn +(a1+4a2+a3)/6 a1 = h*F(xn,yn) a2 = h*F(xn + h/2,yn + a1/2) a3 = h*F(xn + h,yn + 2a2-a1) If we apply this method to the equation for simple harmonic motion: y'' = -ay We obtain the following formulas, which we can program into a web, in this case, the web Rkutta: cell name formula ------------------------------------------- h (no formula...value is set to stepsize) home yold! ypold! y! yp! a constant parameter chosen by user yold y y yold+(k1!+4*k2!+k3!)/6 ypold yp yp ypold+(k1p!+4*k2p!+k3p!)/6 k1 h*ypold k2 h*(ypold+k1p!/2) k3 h*(ypold+2*k2p!-k1p!) k1p -a*h*yold k2p -a*h*(yold+k1!/2) k3p -a*h*(yold+2*k2!-k1!) Set initial values for y and yp. To see a computed solution to the differential equation, set a to a positive value, and repeatedly execute the home cell. This example illustrates the use of multiple expressions within
the same formula. The home cell contains a sequence of four
execution references to yold, ypold, y, and
yp. This causes the current values of y and yp to be placed
into yold and ypold, and then new values to be computed based upon
those old values. |
|
Built In Functions |
This section lists each available built-in function, and any information necessary for its use. min(expr1,expr2,expr3,...) max(expr1,expr2,expr3,...) mean(expr1,expr2,expr3,...) abs(expr) sign(expr) stp(expr) sig(expr) sin(expr) cos(expr) tan(expr) asin(expr) acos(expr) atan(expr) sqrt(expr) ln(expr) exp(expr) log(expr) pow(expr1,expr2) rand(expr) first(expr1,expr2) last(expr1,expr2) butfirst(expr1,expr2) butlast(expr1,expr2) slen(expr) rref("cellname",expr1,expr2) gaussj("cellname1",expr1,"cellname2",expr2) lookup(expr,xexpr1,yexpr1[,...,xexprN,yexprN]) |
|
User Defined Functions |
Every script in Sogol is a user defined function. It may be executed from another script by referring to the cell which contains it with an execution reference: cellname( arglist ) or cellname! The arglist is a sequence of expressions separated by commas. The exclamation point may be used if there are no arguments to the call. Within a script, arguments passed in from the calling script are referred to by designators consisting of the percent sign, %, followed by the argument number (position in the argument list of the call). Thus, %2 represents the value of the second argument in the call to the script. Thus if the script of cell 'addInverse' is called with arguments '4', and '2': addInverse(4,2) And the script contains a formula which reads: 1/%1 + 1/%2 The result will be 1/4 +1/2 or 0.75, which will be assigned to the value of addInverse and returned to the caller. |
|
|
|
|
Sogol Data Structures |
There are three kinds of data structures in Sogol: cells, system constants, and system variables. Cells System
Constants System
Variables
|
|
Sogol Cell References |
References to cells in the Sogol are of two kinds: value references and execution references. Value references consist simply of the cell name. Execution references consist of the name of the cell followed by an exclamation point, '!', or an argument list (possibly empty) enclosed in parentheses. Value
References Execution
References Subscripted
Cell References A subscripted cell reference consists of a cell name followed by a left bracket, followed by an expression, followed by a right bracket, possibly followed by an exclamation point or argument list. Examples of valid subscripted cell references are shown below: a[1] The meaning of a subscripted cell reference is as follows: Imagine that the cells are arrayed in alphabetical order. If the subscript expression evaluates to the floating point number F, N is the largest integer less than or equal to F, and the cell name is twizzle; then the subscripted reference is presumed to refer to the Nth cell past twizzle in the alphabetical sequence of cells. A reference to a[0] is the same as a reference to a. Subscripts less than zero or to cells beyond the end of the sequence generate a subscript error. |
|
Sogol Comments |
The # character, when it appears in a Sogol script, denotes the beginning of a comment. The comment ends at the next carriage return or line feed. |
|
Sogol Statements |
Each Sogol script consists of zero or more statements. If there are no statements in the script when Run is chosen from the Actions menu, then nothing happens. If the execution of an empty script in cell a takes place as a result of an execution reference from another script ( a! ), the value returned to the other script is the content of the value field of cell a. If there is nothing in the value field either, then the value 0 is returned. If the script of a cell contains legal statements in the script language, whether executed from the menu, or from another script; the statements of the script are interpreted in order until the script ends, or an exit or brk statement is encountered. When the script ends or is exited, control returns to the calling script (the one which used the execution reference), or to the Sogol top level screen. The statements of the Sogol language are described and illustrated below. For more detailled information, see the section entitled Script Language Grammar. Set Statement The set ... to ... statement consists of the word 'set' followed by a cell name, the optional word 'to', and an expession. The action of the interpreter is to set the value of the named cell to the value arrived at by interpreting the expression. The set statement: set home to 13 - 5*a will obtain the value of the cell called a, multiply it by 5, subtract the result from 13, and place the result into the cell called home. A slight variation on the statement: set home to 13-a!*5 will execute the script in the cell called a, (which may change the value of cell a), obtain the (possibly new) value from cell a, multiply it by 5, subtract the result from 13, and place the result into the cell called home. There is a variant of the set statement which may be used to change certain configuration choices for Sogol during script execution. In the variant, a so-called configuration word is substitued for the cellname which follows the word set. Configuration words and the parameter changed are listed below: Configuration word-->Parameter changed rptfmt-->report
format string Examples of the set statement variant include:
if
Statement if(a!=b)
{ NOTE: (a!=b) does not mean a not equal to b. It means execute the script of cell a. If the result is equal to b, then...) NOTE:The contents of the parentheses in an if statement must be an expression, conditional or arithmetic. or if(a<>b) { (This is how you check to see if a is not equal to b.) if(a<10) { While Statement The while( ){ } statement looks like this: while(expr) { If the contents inside the parentheses evaluate to a non-zero value, then the contents inside the curly braces will be repeatedly executed until the expression in parentheses becomes zero.
do { Sogol first executes the statements between the curly braces. Then it checks to see if the expression is non-zero. If so, it executes the statements between the braces again, and then checks to see if the expression is non-zero,... , and so on. This statement differs from the while statement in that the statements between the braces are always executed at least once. For Statement There are two variants of the for statement: for ( cellname=expr to expr
step expr ) { and for(cellname=expr to
expr) { Sogol executes the statements between the curly braces so long as the value of cellname has not gone past the value of the second expression, whether stepping from an initial value above or below the ending value. For instance, the statement: for(x=1 to 3) { executes the out( ) statement three times; whereas the statement: for(x=3
to 3) { executes it once. Also, the statement: for(x=3
to 1 step -1) { causes the word "scud" to be output 3 times; whereas the statement: for(x=
3 to 1) { will never output the word "scud", since the step size is presumed to be +1. In Statement The format of the in() statement is: in("a prompt",x,y,z,...,"\nanother prompt",a,b,....) The in statement scans its argument list from left to right. Each time it encounters a string, it copies it to the current output. Each time it encounters a cell name, the input statement scans the input stream for a value to place into that cell. If there is nothing else in the input stream, it sets the eof system variable to 1. Whenever "\n" appears as a string in an input statement, it is output as a newline.
The format of the out( ) statement is: out( list of expressions separated by commas ) Sample output statements: out("damned
spot!",34,x,"or all the seas with
oysters") or out(x,y,z) Whenever "\n" appears in a string in the output statement it is output as a newline. Report Statement The format of the report( ) statement is: report(x,y,another_cellname,z,w.....) When executed, the report statement sends to the current output a report on each of the cells in its argument list, in the order encountered, using the current report type and format. Exit Statement The exit statement consists simply of the word: exit No matter where the statement is encountered, it causes the immediate terminaiton of script execution, and the issuance of the message: EXIT REQUESTED IN CELL xxxxx Brk Statement The format of the brk( ) statement is: brk( expr ) The brk() statement issues to the output window of the screen the character string: <brk: expr> If script execution was begin with a Run to Brk selection (or Alt-B) accelerator, execution of the script pauses with the call stack in the cell name combo box. While execution is paused the user if free to examine and change the values of any cells in the web, though not any settings or text or script fields. When ready to resume execution, the user may do so by choosing Run from the Actions menu, or Run to Brk. In the former case, the script will then run to completion. In the latter case, it will run until it encounters the next brk( ) statement. Alternatively, the user may choose to select Stop from the Actions menu, in which case, execution will terminate immediately with the message: Run halted IN CELL xxxxx Compound Statement A compound statement consists of a left curly brace followed by zero or more statements followed by a right curly brace: { Expression Statement (Formula) An expression statement is an expression, such as shown on each of lines below, which appears where a statement is expected: 1 NOTE: Whenever the script interpreter encounters an expression when it is looking for a statement, it sets the value of the cell in which it finds the expression to the value returned by the expression. The effect of this feature can catch the uninitiated off guard. If a cell's value field is being used as a variable, it is not a good idea to allow any expression statements in that cell's script field. On the other hand, if a cells script field contains expression statements, one should be very careful about the way one uses that cell's value field. |
|
Sogol Grammar |
The permissable content of a script field is zero or more statements. Lines beginning with a '#' character are taken to be comment lines. Wherever a '#' character appears in a formula, the remainder of that line is taken to be a comment. The grammar recognized by the Sogol Sogol interpreter is shown in Backus Naur Form below (items in [ ]are optional):
<termop> ::= "+" | "-" | "OR" | "CAT" NOTE: CAT is the string concatenation operator |
|
|
|
|
Sogol Menus
|
There are five Sogol menus, called File, Edit, Cell, Actions, and Help. The dialogs and functions invoked from these menus are described below:
The File menu has the usual entries, as well as an entry called Report. The report entry executes the report currently selected in the Settings tab called Report. Its output is directed to the output destination selected in the Settings tab called Output. Edit Menu In addition to the usual Edit menu entries, this one contains the Settings selection, which brings up the settings property sheet, which has seven tabs: Links, Report, Output, Input, Number, Execute, and Plot. Use of these tabbed dialogs is described above. The edit menu also has the Font selection, which allows you to change the Font used in the Text, Value, Script, Output, and List panes. Cell Menu The Cell menu has selections to create a ‘New’ cell or ‘Clone’ a new cell from an existing one, It allows you to ‘Delete’ the current cell, view the cell ‘Prev’ ious to the current cell or ‘Next’ after the current cell in alphabetical sequence. You can also go ‘Back’ to a previously visited cell, or ‘Forward’ to a cell from which you have returned. Actions Menu The Actions menu has selections to 'Run' the script of the selected cell and any scripts which it might invoke, 'Run to Brk' which means to start running the script of the selected cell and run until the next Brk() statement, and 'Stop' running. Help Menu The Help menu provides a short selection of help topics, which when selected, are output to the currently selected Output. It also has an About Sogol selection which gives Sogol copyright and version information, as well as giving information on how to register the program, and providing a registration dialog. The registration dialog and information only apper if the program has not yet been registered. |
|
|
|
|
Sogol Error Conditions |
Script Errors When a script is executed, there are several error messages that can result. These messages are listed below: Bad Identifier in Cell
xxxxx Illegal Character in
Cell xxxxx Stack Overflow in Cell
xxxxx Missing Paren in Cell
xxxx Missing '{' in Cell
xxxxx Missing '}' in Cell
xxxxx Subscript Missing ']'
in Cell xxxxx Subscript out of range
in Cell xxxxx Invalid Expression in
Cell xxxxx Expected Format String
(in Quotes) in Cell xxxx Invalid Report Type in
Cell xxxxx Illegal Statement in
Cell xxxxx. Bad Set Stmt in Cell
xxxxx Object of Set must be
reserved word in Cell xxxxxx Number format should be
fixed, exp, or general in Cell xxxxx. Bad number of decimal
places in Cell xxxxx. Trig units type should
be degrees or radians in Cell xxxxx Builtin Function Call
Error in Cell xxxxx Builtin Function Arg
Error in Cell xxxxx Argument List Error in
Cell xxxxx Expected Argument
Number in Cell xxxxx Argument Number Invalid
in Cell xxxxx Poorly formatted cell
list in Cell xxxxx Bad Do stmt syntax in
Cell xxxxx Bad For statement in
Cell xxxxx. Expected '=' in Cell
xxxxxx Expected 'to' in Cell
xxxxxxx Syntax Error in Cell
xxxxx Missing ',' or ')' in
out stmt in Cell xxxxx Expected '(' in Cell
xxxxx Expected ')' in Cell
xxxxx Attempted to read past
end of file in Cell xxxxxx Bad in statement in
Cell xxxxx. Script error in Cell
xxxxx. Internal Software Error
in Cell xxxxx Misuse of Reserved Word
in Cell xxxxx Unexpected end of
script in cell xxxxx Bad xcell spec in plot
dialog Bad ycell spec in plot
dialog Invalid Plot Limits |
|
Sogol Program Limits |
The following limits apply to version 1.2 of Sogol:
|
|
|
Limited Warranty, License, Registration, Distribution, and Support |
|
Limited Warranty
|
ACKNOWLEDGEMENT BY USING THE DEMO OR REGISTERED VERSION OF SOGOL, YOU ACKNOWLEDGE THAT YOU HAVE READ THIS LIMITED WARRANTY, UNDERSTAND IT, AND AGREE TO BE BOUND BY ITS TERMS AND CONDITIONS. YOU ALSO AGREE THAT THE LIMITED WARRANTY IS THE COMPLETE AND EXCLUSIVE STATEMENT OF AGREEMENT BETWEEN THE PARTIES AND SUPERSEDES ALL PROPOSALS OR PRIOR AGREEMENTS, ORAL OR WRITTEN, AND ANY OTHER COMMUNICATIONS BETWEEN THE PARTIES RELATING TO THE SUBJECT MATTER OF THE LIMITED WARRANTY. |
|
License |
After you have registered Sogol, you may use the program for as long as you like, and make as many backup copies as necessary on the computer for which it is registered. If you change operating systems, mother boards, or root disk drives after registering, that will likely necessitate re-registering the program. As long as there is a record of your previous registration, you can obtain a new registration key simply by requesting one from registration@codelode.com. Each registered user will be limited to no more than three free reregistrations during the course of a single year. You may use Sogol without registering it, provided that you do not attempt to enable printing, which has been disabled as an incentive to register the program, and you do not attempt to disable Nagging, which as been provided as an incentive to register the program. Any attempt to enable printing or disable nagging in the unregistered program voids your right to use the program or even to keep it on your computer. |
|
Registration |
Registration takes place in three parts:
Part 1) Copy the registration code from the dialog reached from the aboutSogol entry on the Help menu. If there is no registration code in that dialog, then Sogol has already been registered. Part 2) Go
to www.codelode.com, and
go to the page that allows registration of Sogol. Enter
your registration code, and other information requested, and
pay the registration fee. Part 3) Select the aboutSogol entry in the Help menu while Sogol is running on your computer. Click on the "Register" button. You will be presented a dialog which requests one part of your registration keys. If you enter the information correctly, you should get a message “Registration Succeeded” in the status line at the bottom of the Sogol window. |
|
Distribution |
Sogol may
be freely distributed provided the following conditions are
met: 2) The file distributed must be the Sogol self-extracting, self-installing archive. That's the one that can be downloaded from www.codelode.com. 3) Disk Vendors, Shareware Distributors and BBS(s) may charge a nominal fee for distribution of Sogol. The recipient of Sogol must be informed, in advance, that the fee paid to acquire Sogol does not relieve the recipient from the necessity of registering his copy to disable Nags and enable printing. |
|
Support |
Support for registered Sogol users, and for those attempting to register Sogol is available via email at the address sogol@codelode.com. Include the word Sogol in the subject line. |
