Black Box 4

home *** CD-ROM | disk | FTP | other *** search

/ Black Box 4 / BlackBox.cdr / editors / hypsh40c.arj / HYPDOC.LZH / CHAP4.TXT < prev next >

Wrap

Text File | 1991-04-27 | 147KB | 3,961 lines

HyperShell Users Guide The HyperShell language The HyperShell language 4. HyperShell language HyperShell language uses a terse form of specification which gives the impression that it is more complicated than it really is. To achieve simple results, simple commands are used. As more power is required, additional commands and command structures can be learnt. There is very little initial learning curve. This chapter is intended as a tutorial to lead you through the fundamentals of HyperShell file structure and programming. Whilst you are reading this, you should experiment with producing your own file. 4.1 The basic hyperfile A basic hyperfile consists of a simple text file split into frames by lines starting with:- .FRAME frame name The text after this line is displayed when the frame is current. If the text takes more than one screenfull, it is displayed as `pages', and HyperShell allows the user to page forward and backward through the frame text. If the text is not split at a suitable point, a screen break can be inserted at the end of the last line to appear on the first page. This takes the form:- ~G The basic reference found in frame texts is the frame reference. This is of the form:- ~Fframe name~E. This, when selected, causes the frame named to replace the currently displayed frame. - 29 - The HyperShell language HyperShell Users Guide +--------------------------------------+ |.FRAME frame one | | A reference to ~Fframe two~E and | | one to ~Fframe three~E in this | | frame. | |.FRAME frame two | | This just contains a reference to | | ~Fframe three~E in it. | |.FRAME frame three | | This contains a reference to | | both ~Fframe one~E and also to | | ~Fframe two~E~G | | This text appears on a second page | |.END | +--------------------------------------+ A substantial hyperfile can be built from the structures described so far. Additional ease of use and the presentation and appearance of the application are among the benefits of utilising further structures and facilities. Additional functionality for diverse applications is also available. 4.1.1 Actions The `action' is the HyperShell equivalent of a `command' in a normal programming language. An action is a command string which causes an action to be taken. The action to be taken is specified by the first character (or the first two characters) of the action string. The parameters or operands of an action are supplied by the remainder of the action string. This part of the string can be supplied literally (ie. as a text string), or can be supplied as the result of a `function', which is called an `action modifier' in HyperShell parlance. An action string cannot contain a space between the action code and the parameter. Actions can be used in a number of places:- 1. In a reference in the text. 2. As a menu action. 3. In a script. The basic HyperShell `action' to achieve a jump to a new frame takes the form:- Fframe name It can be seen that this is very similar to the frame reference structure which achieves the same result. If the reference text does not contain the precise name of the frame, we can code this action explicitly in the reference. eg. :- ~Ffelines~PFthe cat~E Here, the word `felines' appears highlighted in the text, but the frame `the cat' is displayed when it is selected. - 30 - HyperShell Users Guide The HyperShell language 4.1.2 Global items Global items are general to the hyperfile, and they are placed at the start of the hyperfile, before the first frame. The most common global item is the NOTE. A number of notes can appear in the hyperfile. Each one consists of a line starting:- .NOTE note name This is followed by the text for the note. The displayed note text cannot be larger than 22 lines of 77 characters. Note text can contain references to other notes, to frames, or to other types of action. A note is referenced in frame or note text by the following form:- ~Nnote name~E You will notice that this is similar to the frame reference. As in the frame reference, an explicit reference can be added using the ~P flag. This need not be a note action, although it is obviously less confusing to the user if it is. It could, however, run a script which eventually displays a note. The action to display a global note is simply:- Nnote name 4.1.3 Local items Local items are notes, menus and scripts which can only be accessed from a specific frame. As such, they are coded after the frame in the hyperfile, and before the next frame. The local note is coded in the same way as the global note. The local note is referenced in the frame using the following form:- ~nnote name~E Note that the flag is a lowercase `n'. Local versions of menus and scripts also use the lowercase letter. The action to display a local note is as expected:- nnote name - 31 - The HyperShell language HyperShell Users Guide +--------------------------------------+ |.NOTE cat | global | (Moggus lazius) Small feline | | quadruped. Has a liking for fish, | | warmth, and sleep. | |.NOTE dog | global | (Gnashus noisius) Medium size | | quadruped. Likes barking, fetching | | sticks and eating leftovers. | |.FRAME Pets | frame | Apart from the usual domestic | | pets, the ~Ncat~E and the ~Ndog~E, | | the next most popular is the | | ~nhamster~E, which needs the | | minimum of maintenance, and is a | | lovable creature, apart from when | | it bites. | |.NOTE hamster | local | (Mus stupidus) | | Tiny rodent quadruped. | | Likes running in a wheel all | | night and eating carrots. | |.END | +--------------------------------------+ 4.1.4 The frame display format The straightforward hyperfile design described above, along with the HyperShell reader, provides a full traditional hypertext system. Large hyperfiles using just these simple rules can be constructed. Normally, however, it is desirable to enhance the appearance of the hyperfile, and to provide features to assist with the operation of the system. The appearance of the information is not limited to the frame text. Just as a book has running headings and footings, so the HyperShell screen can have header and footer information which appears on every screen. - 32 - HyperShell Users Guide The HyperShell language Frame display format +--------------------------------------------+ | --- HEADER TEXT -------------------------- | | ------------------------------------------ | | | | | | FRAME TEXT | | | | | | | | | | | | --- FOOTER TEXT -------------------------- | | ------------------------------------------ | | === MESSAGE AND PROMPT LINE ============== | +--------------------------------------------+ 4.1.5 The Header The HEADER item, provided at the start of the global items, provides the text which will appear at the top of every screen. A line of the form:- .HEADER is followed by one or more lines containing the text which will appear at the top. If a HEADER is not supplied, a default header showing the frame name and the title is used. The header text, as well as frame text and note text, can contain `variable tokens' which are replaced by their values when the text is displayed. These take the form:- $x where x is the variable name. Standard `system' variables exist which provide specific variable items. Two of these are the frame name held in variable 1 and the frame title held in variable 2. Our header might therefore look like:- +--------------------------------------------+ |.HEADER | | Frame: $1 | | Title: $2 | +--------------------------------------------+ This simply displays the two lines at the top of each frame, with $1 replaced by the frame name and $2 replaced by the frame title. A `null' header consists of a .HEADER line followed by another line starting with a `.'. This may be used if each frame is to have a different format, and does not need the default title. The header display can be suppressed for specific frames by starting the frame title with a `)' character. - 33 - The HyperShell language HyperShell Users Guide 4.1.6 The Footer The FOOTER is coded in a similar manner to the HEADER, starting with a line as follows:- .FOOTER This is followed by one or more lines, which will appear after the frame text at the bottom of each screen when the frame text is being displayed. It is displayed immediately after the frame text, so we generally force it to appear on a specific line using a `formatting flag' in the text. A flag of the form:- ~L22 . . . . Footer Text . . . . will cause the text on the line to appear on line 22 of the frame. In a similar fashion, it is possible to use a formatting flag to place text at a column position, using the ~C flag. +--------------------------------------------------+ |.FOOTER | |~L22~C15~APress space bar for next frame~PF+~K ~E | +--------------------------------------------------+ This displays a selectable reference on line 22, column 15 which can be selected using the mouse cursor or by pressing the space bar. The space character is mapped to the reference, and the parameter section provides the `F+' action, which causes the next frame to be displayed. It is also possible to step through so that no backtrack information is retained. This is done using the lowercase form of the reference (f+). The footer can contain the same kind of information that the header contains, and is often used to display the function key mappings. 4.1.7 Popup menus The popup menu is a useful addition. It allows a concise list of choices to be readily presented for selection. The action resulting from making a selection can be any HyperShell action. For instance, a list of related frames can be offered from a frame, or a menu of help notes can be offered when a function key is pressed. The footer could contain a reference to a `See Also' menu, which contains a list of related frames. - 34 - HyperShell Users Guide The HyperShell language +-------------------------------------------------+ |.FOOTER | |~L22 ~mSee Also~E | | - - Other items and frames - - | |.FRAME Hamsters | | - - frame text - - | |.MENU See Also | |Mice | |Gerbils | |Rats | |Guinea Pigs | |Wombats | +-------------------------------------------------+ Of course, not all frames will have a `See Also' menu. When a local item is not available, HyperShell first looks for a global item of the same name. This allows us to have a global `catch all' menu in this case. +------------------------------------------+ |.MENU See Also | |Introduction | |Pets | |Rodents | +------------------------------------------+ 4.1.8 Conditional text Perhaps there is no sensible global item which can be used, and we really only want those frames with a local item to reference it. There is a way of achieving this using `conditional text' in the footer, which can be turned on or off as required for each frame. If the footer looks like:- +-----------------------------------------+ |.FOOTER | |~h6~L22 ~mSee Also~E | +-----------------------------------------+ Then the menu reference will only be displayed if frame-local flag 6 is set. This flag can be set within the frame text for a frame using the flag:- ~J6 where 6 represents the local condition name in this case. This flag should appear near the start of the frame text for each frame which has the local menu. - 35 - The HyperShell language HyperShell Users Guide 4.1.9 Help menu A simple help facility is probably the first feature you will want to add to your system. The `?' key is by default mapped to a global menu called `help', which must only contain global note actions. This may be used for a simple help system. Note that this form of help is available from the paged display screen as well. The help system may be used to describe the operation of HyperShell and any specific operational aspects of the hyperfile, or can be used in support of the main hyperfile material. The hyperfile could have a simple system describing how to use simple navigation in HyperShell. To add this to your hyperfile, insert a global menu called `help' as follows:- +--------------------------------------+ |.MENU Help | |Selecting |NSelecting | |Control keys |NControl keys | +--------------------------------------+ and some global notes as follows:- +--------------------------------------+ |.NOTE Selecting | |You can follow references to | |move between frames and to | |display popup notes and menus. | |To select a reference position | |the mouse cursor using the mouse, | |cursor keys or TAB and SHIFT/TAB, | |then select by pressing ENTER, | |or the LEFT mouse button. | +--------------------------------------+ +--------------------------------------+ |.NOTE Control keys | |You can use the function keys to | |control the system. The function | |keys are setup as follows:- | | | |F1 - Go to introductory frame | |F2 - Display contents of file | |F3 - Move back to previous reference | |F4 - Move back a number of steps | |F5 - Display list of noted frame | |F6 - Search file for text string | |F7 - Display contents of text file | |F8 - Perform requested action | |F9 - Temporary exit to DOS | |F10 - Quit to DOS | +--------------------------------------+ This provides a fairly simple help system. - 36 - HyperShell Users Guide The HyperShell language 4.1.10 The SETUP script To provide further features in a help system, the F1 key can be mapped to provide the help menu. More complex interaction with the help system is then possible, and the help menu is not limited to simple note references. To do this, you will need to create a SETUP script. The SETUP script is run whenever the hyperfile is `entered' which is usually on start- up when running HyperShell against the file. It will also be executed if you select a reference to this hyperfile from another hyperfile. It can therefore be used to set up any key mappings, colour schemes, options etc. required by a hyperfile. The SETUP script is simply a global script with the name `SETUP'. To set up the F1 key on the control menu, this would be as follows:- +---------------------------------------+ |.SCRIPT SETUP | |KF1MHelp | |KM1Help | +---------------------------------------+ The first line maps the F1 key to the action `MHelp', which invokes the global menu called `Help' which we created above. The second line changes the text of the control menu for the F1 action to be `Help', rather than the default of `Home Frame'. Note that frame, note, menu and script names are not sensitive to whether the name is in uppercase or lowercase or mixed case, and references can use cases different to the item names. 4.1.11 The NDEX When a hyperfile grows beyond a certain size (about 30k to 50k), it is preferable to use the automatic index facilities. An index file is used to save HyperShell from having to read all the way through the hyperfile to build its internal index. Opening and reading the index file has its own overheads, however, so the index should not be specified for small hyperfiles. The index file is maintained automatically. If you modify the hyperfile, HyperShell will rebuild the index for you. The index is specified using the .INDEX directive. The .INDEX line should be present anywhere before the first frame specification. This specifies that an index file is to be created and maintained for the hyperfile. - 37 - The HyperShell language HyperShell Users Guide 4.1.12 Supporting text files Normal text files, and files with just reference flags in them, can be used in support of the hyperfile in two ways. The F7 key allows a filename to be entered, and displays the text file allowing the user to page backward and forward and do text searches. The F7 key is mapped to action code `T'. The `T' action can also be called from a reference in the text. This reference takes the form:- ~Ahighlighted text~PTfilename.ext~E The text `highlighted text' will appear as a highlighted reference in a frame or note display, and when selected will cause the file `filename.ext' to be displayed. This file may contain embedded references to the frames in the hyperfile. One way to achieve this is to do it automatically when displaying the file, rather than having to actually modify the file. This is known as automatic referencing (or `autoreferencing'). To enable this, the line:- O41 should be added to the SETUP script (this starts with the letter O, not the figure 0). When this is done, an occurrence in the text file of any of the frame names would be highlighted when the file was displayed, and could be selected, whereupon the relevant frame would be displayed. After the frame is read, and possibly after the user has moved to other frames, the file display can be continued by simply pressing the F7 key. This will call the action `T' without a file name parameter, which causes HyperShell to resume viewing the text file at the point it was when the frame name was selected. Another way that text files may be used in support of a hyperfile is the `file note'. A reference of the form:- ~tfilename~E refers to a file called `filename.nte' which is displayed as a popup note when the reference is selected. Note that the extension `.NTE' is added only if one is not supplied in the reference, so for instance if we had a file called `feeding.txt' we could have a reference of the form:- ~tnourishment~Ptfeeding.txt~E Note that this uses the action code `t', which has the same effect as the `~t' reference flag. 4.1.13 The menu bar If the top line of a frame display (usually part of the Header) contains menu references, these can be made to immediately be selected if the mouse cursor moves over them. This is controlled by setting flag 4 in option 1 as follows:- - 38 - HyperShell Users Guide The HyperShell language O14 Note that option 1 has a number of flags which can be set, as follows:- Option 1 - flag mask values +---------------------------------------------+ | 1 | Show symbols to indicate actions | | 2 | Use first letter, not function keys | | 4 | Menu refs on top line are immediate | +---------------------------------------------+ These flags have mask values of 1, 2 and 4, and you should add together the flag values to form the option value. For instance, if we wanted to display menu symbols as well as have immediate menus on the top line, but we wanted function key selections on menus rather than first letter selection, we would add the flag values 1 and 4 together to form the value 5, then set option 1 to 5:- O15 Many systems, including graphic user interface packages, have `pulldown menus' selectable from a menu bar at the top of the window or screen. A menu bar can be easily created in HyperShell by setting up a string of menu references on the top line, and optionally making them `immediate' using the above option setting. The natural place to set this up is in the Header item, although a situation could exist where no header was specified, and each frame had its own custom menu bar. A typical Header might look like:- +--------------------------------------------------+ |.HEADER | | ~MFile~Kf~E ~MEdit~Ke~E ~MHelp~Kh~E | +--------------------------------------------------+ This gives access to three global menus for file operations, edit operations and for help. These menus are mapped to the keys `f', `e' and `h'. This is not essential, but gives the user an extra method of selecting the options. Note that if the key mappings are used, these keys cannot be mapped in the frame text. If the key mappings are in effect, it would be nice to indicate that they are available. This can be done by highlighting the initial letter differently to the rest of the word. We can embed formatting flags to achieve this:- +--------------------------------------------------+ |.HEADER | | ~M~TwF~TKile~Kf~E ~M~TwE~TK~dit~Ke~E . etc . | +--------------------------------------------------+ Note that the formatting flags are not used in the construction of the menu name from the reference. - 39 - The HyperShell language HyperShell Users Guide 4.1.14 Input fields One particularly useful form of reference of general use is the input field. This takes the form of a highlighted reference until it is selected. When this is done, it becomes a string input area which can be used for input and editing of data. The input field is set up using flags in the following general form:- ~Iinput area~Paction template~E The input area is usually filled with spaces, or with the contents of a variable. To allow sufficient room to enter a long enough string, a width specified is usually added. The action template is an action or multiple action containing up to three `%s' tokens. When the input is completed by pressing the RETURN key, the value on display is substituted in the place of each token, then the actions are performed. The first action is usually a variable assignment. Other actions, such as a call to a validation script, are usually coded afterwards. An example of an input field would be specified as follows:- +---------------------------------------------+ | . . . | | ~I$N~W20~PVN%s;sCheck N~E | | . . . | +---------------------------------------------+ This displays a field 20 characters wide containing the current value of variable N. When the field is selected, the value may be edited. When the RETURN key is pressed, the value is assigned to variable N and the local script called `Check N' is called to validate the value entered. Notes can use an input field to act as a dialogue box, and frames can use a number of input fields to act as a data entry form. 4.2 Programming This section introduces the fundamental concepts necessary to write complex actions and scripts using HyperShell. As many people are familiar with the BASIC interpretive language, the corresponding constructs in BASIC are also included in some cases as an aid to understanding. Because of the multiplicity of variations of the actions and codes described, it is not practical or necessary to cover every variation. The fundamentals are described here, and the reference guides should be consulted for information on the other variations of facility provided. - 40 - HyperShell Users Guide The HyperShell language 4.2.1 Action modifiers As we saw above, actions are the HyperShell equivalent of commands in other programming languages. Action modifiers are the equivalent of functions, and provide the parameter value for an action. One type of action modifier is the dynamic menu which is a menu or other selection item. This can be a normal menu or can be one built dynamically at the time you run it. For example, to set the variable to a value chosen from a menu, the action would be:- Va@Mnames This would popup the menu called `names' to allow one of a set of names to be selected by the user. The selected name would replace the modifier string in the action before it was executed. Dynamic menus start with the `@' sign, and have a single character identifying what kind of menu they are, sometimes followed by a parameter string. Dynamic menus can have other action modifiers `cascaded' to give complex interaction functionality. For example, to type a file selected from a menu formed from a directory listing of files with a wildcard specification input from the user, the action would be:- T@d?Wildcard specification This would prompt the user for a wildcard specification, which would be used to select files from the current directory to form a menu from which the user could select a file to type. The `?' sign introduces another kind of action modifier called a prompt. This has prompt string parameter which is displayed as a prompt. The string the user types in response to the prompt will be returned and will replace the prompt action modifier in the action string. If the result of an action modifier is not usable in its provided state, it can be further formatted using a format string:- D@d*.DAT|COPY %s A:%s This would present a menu of all files with the extension .DAT in the current directory, and would then copy the selected file to the A: drive. The resulting action string would take the form:- DCOPY FRED.DAT A:FRED.DAT The `d' dynamic menu is used to display a popup directory listing of files matching a wildcard specification. It returns the name of the selected file. - 41 - The HyperShell language HyperShell Users Guide The `|' symbol separates the action string from the format string. The format string can contain one, two or three `%s' tokens, which are replaced by the action modifier value before the value is replaced in the action string. 4.2.2 Multiple actions We have already seen how actions can be put together in a string. Here are some rules about multiple actions:- 1. The condition of a conditional action affects remaining actions. 2. A conditional jump does not clear remaining actions. 3. The remaining actions in a multiple action are cleared if an error occurs in an action, or an input is cancelled. 4. If a further multiple action is encountered, for instance as the result of an action modifier or menu selection, the remaining actions are cleared in the original. 4.2.3 Variables Most programming languages and programmable systems support the concept of variables. A variable is a container for variable information. Variables can be thought of as boxes with names on them. You can store strings of characters and numbers in variables. HyperShell has a number of different types of variable. The common variables have single letter names, there being 52 of these using both uppercase and lowercase letters. Variables do not need to be declared, and come into existence by assignment. Single letter variables are assigned using the `V' action, and take the value of the remaining text in the action string. e.g. Vafred (BASIC LET a = "fred") assigns the value `fred' to the variable `a'. The variable can have another value subsequently assigned to it, or it can be cleared by use of a null string (a string of zero length):- Va 4.2.4 Named Variables The set of common variables may be used for most purposes in HyperShell. There are cases where more than the 52 common variables are required, and HyperShell allows an application to specify any number of another form of variable, called a named variable. These have any name which contains valid characters, and the name can contain spaces. Examples of valid names are:- price size of field RS232 47>aj 9-c - 42 - HyperShell Users Guide The HyperShell language Hamster food Named variables are assigned using the `l' action or the ZV action. Using the `l' action, the named variable can only be assigned values from single letter variables. e.g. laname (BASIC LET name = a) The ZV action allows a literal string to be directly assigned to the variable:- ZVname=value Note that the name in either case can be provided from an action modifier, or from a variable token expansion. e.g. la$b This loads the contents of `a' into the variable whose name is the contents of variable `b'. There is no equivalent of this in BASIC, or any of the other common interpretive languages for that matter. 4.2.5 Variable expansion The variable may be used in a number of ways. The most common is as an expansion token in the frame or note text, or in an action string as above. The format of the token is:- $x where `x' is the variable name. This token is replaced by the value of the named variable, before being used for display or action purposes. The variable can in fact be expanded anywhere in an action string after the first letter. For example, to load the variable whose name is a concatenation of the contents of the variables `c' and `d' from the single letter variable whose name is contained in variable `x', we would write:- l$x$c$d The named variable expansion token takes the form:- $(name) Where `name' is the name of the named variable. This itself can be supplied by a single letter variable. e.g. $($b) Thus to do the opposite of `la$b' we would write:- Va$($b) - 43 - The HyperShell language HyperShell Users Guide Variable token substitution is done in frame and note text before displaying the text (so variables can contain reference flags). Variable token substitution is done in action strings AFTER any action modifiers have been actioned and before the action is executed. Thus an action string of the form:- Vb?value of b could have a value of `$c' typed in by the user, which would be expanded to the contents of variable `c' before the assignment was made. A variable token expansion can be `deferred' one step by putting two $ signs. This will be converted to one $ on the first expansion and will be expanded on the second. Thus a variable token in an action string in a reference on a frame display should have two $ signs, as the expansion on display would otherwise pre-empt the intended expansion when the reference was actioned. 4.2.6 Other uses of variables Single letter variables can be used directly in an integer expression action modifier. Thus an action of the form:- Va=b+c (BASIC LET a = b + c) will do as you might expect and add variables `b' and `c' together, placing the result in `a'. Variables can also be used in this manner in tests, thus we can have:- va=b+c+d;je20 (BASIC IF a = b + c + d GOTO 20) 4.2.7 Condition codes When a variable comparison is performed, a number of condition codes are set, and can be tested. If the variable and test string are of numeric content, the comparison is a numeric comparison, otherwise it is a string comparison and works as a lexicographic or ASCII collating sequence string compare. This example compares variable `a' against 23 and jumps to LESS if it is less than 23. va23;jlLESS This example compares variable `n' against `fred' and jumps to FRED if it is equal. vnfred;jeFRED - 44 - HyperShell Users Guide The HyperShell language Also, a substring and superstring compare is done, so that you can test whether the variable is contained within the string, or contains the string. This sees if variable `e' is one of `one','two','three' and jumps to Lone, Ltwo or Lthree if so:- veone two three;jw$e It is sometimes useful to test whether the variable is defined at all. This sees if variable `j' is defined and jumps to DEFINED if so:- vj;jdDEFINED The conditional jump action `j' is described later. 4.2.8 System variables A number of system variables are available, which have numeric and other character names. Most of these cannot have values explicitly assigned to them, but can be expanded in exactly the same way as single letter variables. For example, to display the current date, we code the following token in the text to be displayed:- $4 4.2.9 Pseudo variables Two pseudo variables are provided to assist with the specification of certain actions. These have a constant value (and are therefore not VARIABLE). These are as follows:- $, This is replaced by the semicolon `;' $! This is replaced by the format separator `|' 4.2.10 String splitting A number of powerful string processing capabilities exist in HyperShell. These can be used to manipulate data which has been entered by a user, or input from a file. It is often necessary to break a string into, for instance, a number of fields. Quite often, data is provided in the form of fields separated by a well known character. Thus a string could have the form "aaaa:bbbbbb:ccc:dd". This can be split into a number of variables with an action of the form:- es:abcd Where `s' is the variable containing the string, and a,b,c and d are the variables to receive the fields. In the example above, variable `a' would receive `aaaa', variable `b' would receive `bbbbbb' etc. - 45 - The HyperShell language HyperShell Users Guide 4.2.11 Arrays Arrays are sets of variables which can be identified using a variable name and one or more `subscripts' or array indexes. Whilst arrays, as they are known in other programming languages, are not supported in HyperShell as such, some constructs are possible to provide some of the functionality for which arrays are used. Constant arrays can be implemented using a menu, referenced using a dynamic menu action modifier in the form:- Vn@Mnames($v) This uses the value of variable `v' as an index into the set of strings specified in the menu called `names', returning the indexed entry and assigning it to variable `n'. Named variables can have their name supplied using variable tokens or combinations of constant strings and variable tokens. So, if we wanted to set up the equivalent of an array called month with 12 elements containing the names of the calendar months, we could set up variables as follows:- ZVmonth1=January ZVmonth2=February ZV -etc- To obtain the equivalent of month[a], we could code the token:- $(month$a) We could have done the same when we set up the array, so to rename the month with the subscript supplied by variable `n' to `New month', we code:- ZVmonth$n=New month The variable used as the `subscript' could have had its value set in a loop structure (see later), or by some other event. This facility implements what is known as associative arrays i.e. arrays subscripted by character strings. So, for instance, we could set up an array of fruit colours as follows:- ZVcolour_banana=yellow ZVcolour_apple=green ZVcolour_plum=purple ZVcolour_orange=orange ZVcolour_strawberry=red Then to display the colour of a fruit in the text, given the type of fruit in variable `f', we code:- - 46 - HyperShell Users Guide The HyperShell language $(colour_$f) Note that the underscore is not strictly necessary, but is included in the example to give the variable names a better form. Constant associative arrays can also be set up using menus with entries containing the key string and the associated string, and indexed using the form:- Vs@Msurname[$n] This takes the contents of variable `n' as a key to look up an entry in the menu `surname', returning the action string from the located entry and assigning it to the string `s'. The menu `surname' could have the following form:- +--------------------+ |.MENU surname | |fred|jones | |jim|smith | |nick|taylor | +--------------------+ 4.2.12 Application control flags We saw above how comparing a variable set condition codes to indicate the result of the comparison. These condition codes are available until the next comparison is made, unlike most programming languages which bind the condition result to the comparison in a conditional branch. Other languages have what are known as BOOLEAN variables. These can be assigned as the result of a comparison and have a value of either TRUE or FALSE. They can be readily tested, as they form a complete condition in themselves. HyperShell, as well as retaining the condition codes from a comparison, has a set of boolean variables called application control flags. These can be used directly as condition codes in all forms of conditional operation. The application control flags have names of A to Z, and can be used to hold single character values. If the value is null, the flag is regarded as FALSE. If the value is other than null, the flag is regarded as TRUE. To assign a value to an application control flag, the O*X action is used, where X is a letter A to Z. The assignment takes the form:- O*A1 - to set flag `A' to `1' -condition TRUE or O*A - to clear flag `A' - condition FALSE This can then be used in a conditional action, or anywhere else a condition can be used. For example:- aAPFlag A is set - Pops up a message if the flag is set - 47 - The HyperShell language HyperShell Users Guide The value can of an application control flag can be obtained using the &O function as follows:- Vx&OA - Set variable `x' to character value of A 4.2.13 Uses of condition codes The comparison conditions and the application control flags have been described above. Also the section on Footers introduced the frame- local flags which are local to a particular frame. There are other condition codes of a global nature which may be used to determine various things, such as whether an error has occurred during an action modifier, or whether a selection has been made from a menu. Also there are some conditions which are local to frames such as whether the frame matched the last search operation or whether the frame has been visited before. Conditions can be used in a number of different places. Conditional text We have seen local flags used for conditional display of text in the Footer. The comparison conditions, the application control flags and the other conditions can all be used for the display of conditional text. The `~jc' flag can also be used for conditional text, and works in the reverse sense to `~hc', only displaying the text if the condition is FALSE. The local flags, and the global flags, can be used for expansion references in the text. An expansion reference can be set up as the following example:- ~APress to expand / remove additional information~PZL3~E ~h3This is additional information ~h3which is displayed when the above ~h3reference is selected. ~j3This is an alternative piece of text otherwise shown Note that the conditional text lines would be displayed after the reference normally, but this is not strictly necessary and they may appear anywhere in the frame display, including pages not currently on display. The conditional text concept may also be used for expertise levels in help systems, by use of the global application conditions (A to Z). The application flag can be set at any point, and will then influence all text conditional on it. Thus, text for the beginner may be shown if the application flag B is set, as follows:- ~hBThe space bar is the long key at the front ~hBof the keyboard used for entering spaces. - 48 - HyperShell Users Guide The HyperShell language Note that ~Z flags are required after conditional text if the conditional text flag is not at the start of the line, and is sandwiched between unconditional text. ~AToggle flag~PZL7~E ~h7Flag 7 On~Z ~j7Local flag 7 Off~Z The frame is refreshed after a `ZL' action, so that any conditional text is shown / hidden. The refresh may be suppressed by adding an extra character to the action:- ZL4# Conditional actions and branches We have seen the conditional jump action `j' used in examples. We have also seen the conditional action `a' used. The reverse conditional action code `z' is similar to `a' only works in reverse. All these can be used with any of the condition codes. jzFILE ERROR jumps to label FILE ERROR if file error Vn@MNames zbq Quits script if no selection made from menu Conditional menu options A third place we can use conditions is in menus. If we only want to display options under certain conditions, we can use the following notation in a menu:- ?coption or \coption Where `c' is the condition code, and option is the menu option with or without a separate action. The `?' code indicates that the option should be included only if the condition is TRUE. The `\' option indicates that the option should only be included if the condition is FALSE. +-----------------------------+ |.MENU Information | |?BHelp |NBeginners help | |\BHelp |NExperts help | |. | +-----------------------------+ This menu displays a different help note depending on whether the application flag B is set or not. - 49 - The HyperShell language HyperShell Users Guide 4.2.14 Scripts The HyperShell program is an interpreter, similar in many ways to a high level language interpreter such as BASIC. Because it was designed for the presentation of information, it does not contain conventional language statements, floating point arithmetic, arrays or structured data items. Nevertheless, a lot of conventional programming constructs can be achieved using the SCRIPT facility, and the large set of actions and action modifiers available. First, a word about how scripts are defined and called. Defining a script is similar to defining a note or a menu, and scripts can also be global or local to frames. A script starts with the line:- .SCRIPT script name Script names can be like note and menu names. As the script name will not be seen by the user (unless it is a direct script reference in the text), it can have any suitable name. A script might look like the following:- +-------------------------------------+ |.SCRIPT display notes | |-- Display notes about pets | |Ncat | |Ndog;NHamster | |-- Display Help menu | |MHelp | |-- Display pets frame | |FPets | +-------------------------------------+ A script simply consists of a sequence of actions or multiple actions, possibly interspersed with comments. A comment is a line starting with the hyphen character (ie. minus sign `-'). Script lines can be `indented' for clarity using spaces and TABs at the start of the line. A multiple action is a sequence of actions separated by semi-colon characters (ie. `;'). Multiple actions are a convenient way of coding a sequence of actions which may or may not depend on each other. If an action fails, the remaining actions in a multiple action are not performed. The script can be driven from a script reference in the text, in the following form:- ~Sscript name~E or ~sscript name~E (for a local script) The script can also be invoked by an action of the form:- Sscript name The processing of a script is terminated when:- - 50 - HyperShell Users Guide The HyperShell language 1. It reaches the end, or a `q' action 2. A further script is called 3. ESC is pressed to cancel a menu or other display 4. A new frame is displayed (unless using the `f' action) Another kind of script is the script file. This is an external file which is interpreted as a script. It is called as follows:- cscriptfile where `scriptfile' specifies the name of the script and may have its extension omitted, in which case .HSF is assumed. 4.2.15 Control structures The script facilities in HyperShell permit a form of programming to be achieved. A simple sequence of actions may be performed in a script, and control flow actions are provided to allow loops, conditional branching and computed branching to occur. A trace facility is provided to assist with the debugging of scripts. HyperShell does not yet have any specific loop control instructions, but loops are easy to program using the Jump action. Thus, a BASIC loop of the form:- FOR A = 1 TO 20 . . . NEXT A is handled as follows:- +-----------------------------+ |VA1 | Set A to 1 |Lloop | Label loop | . . . | instructions |VA=A+1;vA21;jlloop | Increment and loop +-----------------------------+ The `L' action must appear as the first action on a line. The `j' action is a conditional jump action, which branches to the named label if the condition ('l' in this case) is true. As the expression evaluation modifier sets the condition code, a decreasing loop is easier to use when the variable is not used in the loop body. +-----------------------------+ |VA20 | Set top of loop |Lloop | Label | . . . | instructions |VA=A-1;jnloop | Decrement and loop +-----------------------------+ - 51 - The HyperShell language HyperShell Users Guide IMPORTANT: There is an unexpected side effect of HyperShell compound statements. If further actions follow a Jump instruction in a compound statement, the further actions are executed regardless of whether the jump is actioned. Computed GOTO statements in BASIC of the form:- ON a GOTO 110,120,130,140 can be coded in HyperShell with a simple Jump specifying the value of a variable. J$a The variable, `a' in this case, need not contain a numeric value, as a label can be any alphabetic string. E.g. to branch depending on the value returned from a confirmation prompt:- +---------------------------+ |J$c | Jump to value of c |. . . | |LYes | If c is `Yes' |... actions if Yes ... | |Jend | |LNo | If c is `No' |... actions if No ... | |Lend | Common end point +---------------------------+ Of course, the Jump action can have its parameter supplied from one of a number of action modifiers, so a number of potential labels could be presented as a menu:- J@Mchoices NOTE: It is not possible to supply the name of a label in a variable token in an `L' action. 4.2.16 Subroutines Subroutines are sequences of code which are common to more than one piece of processing, and therefore should not be repeated. To place the common processing in one section of code usable from different areas offers a number of advantages. Firstly the code only has to be written once. Secondly the code does not have to physically exist more than once, saving space. Thirdly, there is only one bit of code to maintain (ie. to get the bugs out of and to change if circumstances change). BASIC uses the GOSUB verb to branch to a `subroutine' line number, and a RETURN verb to return to the line after the GOSUB. HyperShell has a similar mechanism. A jump to subroutine action is provided, which is coded in a script as in the following example:- - 52 - HyperShell Users Guide The HyperShell language +-------------------------------+ | . . . | |ZJsubrtn | Jump to subroutine--+ | . . . | come back to here | <+ | . . . | | | |q | don't fall into it! | | |Lsubrtn | Subroutine <--+ | | . . . | | |ZE | return from subroutine-+ +-------------------------------+ The `ZJ' action causes a branch in a script to the named label. The `ZE' action subsequently causes a return to the line after the `ZJ' action. Whilst this structure is useable in a large script, you may have some processing which you wish to use in a number of scripts. The script concatenation operator can be used to add a script containing the subroutine (or subroutines) to the end. +----------------------------------+ |.SCRIPT main script | | . . . | |ZJsubrtn1 | | . . . | |ZJsubrtn2 | | . . . | |q | |-- Append subroutine script | |+Subroutines | +----------------------------------+ +----------------------------------+ |.SCRIPT Subroutines | |q | to stop accidents |-- First subroutine | |Lsubrtn1 | | . . . | |ZE | |-- Second subroutine | |Lsubrtn2 | | . . . | |ZE | +----------------------------------+ The subroutines script can then be added to a number of scripts. The total number of lines, excluding comment lines, in a script plus concatenated scripts is 200. - 53 - The HyperShell language HyperShell Users Guide 4.2.17 Parameters on scripts and notes Normal programming languages provide procedures and functions which can accept parameters (or `arguments'). HyperShell allows parameters to be passed to a script in the following fashion. If a script is called as follows:- Sscript name(param1,param2,param3) then the total string within parentheses is assigned to system variable `\'. This might not at first seem all that useful, but the variable split action `e' can be used to split the parameter into a number of variables at the start of the script:- +--------------------------------+ |.SCRIPT Add three numbers | |-- split into a,b and c | |e\,abc | |-- display sum on bottom line | |p=a+b+c | |-- return | |q | +--------------------------------+ Also, a variable name can be passed in to receive a result (or a few names can be passed in to receive a number of results:- +-------------------------------------------+ |.SCRIPT Sum and Difference | |-- split into a,b,c and d | |e\,abcd | |-- put sum in variable named by c | |V$c=a+b | |-- put difference into variable named by d | |V$d=a-b | |-- return | |q | +-------------------------------------------+ A parameter can also be passed to a note in a similar fashion:- NNote name(Parameter) So if we have a note defined as:- +-----------------------------------------+ |.NOTE Confirm | | $\ - Please confirm | | | | ~A YES ~PY~Ky~E ~A NO ~PN~Kn~E | | | +-----------------------------------------+ - 54 - HyperShell Users Guide The HyperShell language We can use this to ask for confirmation on anything, for instance in a script:- +--------------------------------------+ | . . . | |-- Ask for confirmation | |Vc@NConfirm(Delete File) | |-- If yes not selected, quit script | |vcY;anq | |-- Delete the file | |d DEL DATA.DAT | | . . . | +--------------------------------------+ The `@N' dynamic menu is another use for a note. The note is displayed, and if any reference is selected in the note, its value is returned. 4.2.18 Access to the environment MSDOS provides a set of strings called `environment variables'. These are set using the MSDOS `SET' command, and include such things as the PATH variable, which specifies where programs can be found. HyperShell can access the environment variables using an action modifier as follows:- Vp%PATH This sets variable `p' to the value of the PATH environment variable. Environment variables can therefore be used to hold information which you can access from within HyperShell. HyperShell can also set environment variables, but as the environment which HyperShell accesses is just a copy of the MSDOS environment, variables are not available after HyperShell exits. However, if HyperShell runs other programs, information can be passed to these through the environment, as this is copied for the programs run by HyperShell. The action `ZS' is used for this purpose:- ZSNAME=FRED NOTE: Environment variable values must adhere to the rules set by MSDOS. 4.2.19 Simple interaction The BASIC interaction commands are very useful for communicating with the user. HyperShell has some equivalents to the simple interaction commands as follows:- Vn?Enter your name (BASIC INPUT "Enter your name";n$) - 55 - The HyperShell language HyperShell Users Guide pHello (BASIC PRINT "Hello") pYour name is $n (BASIC PRINT "Your name is ";n$) Do not confuse the use of the dollars in the last example. BASIC uses dollar signs for an altogether different purpose to HyperShell. HyperShell provides some extensions to this interaction. If one of a number of fixed strings is to be entered, the set of strings can be presented as a menu. If a more elaborate prompting method is required, a note containing and input field can be popped up as a dialogue box. The menu or note are then used to supply the value to the variable:- Vt@MCar type Vc@NConfirm Where a single character input is required, the Key function can be used. This is coded as e.g. Vx&KPress a key And is the equivalent of the BASIC:- 30 PRINT "Press a key" 40 X$ = "" 50 X$ = INKEY$(): IF X$ = "" GOTO 50 Prompted input can provide a value for editing, rather than demanding a complete new input each time. This is specified by appending a `/' character and the default value. This is usually a default value or the previous value of a variable:- Vd?Enter Transaction Date/$4 Note that variable 4 will be expanded before being presented for editing. Vn?Enter you name/$n The previous value of variable `n' will be offered for editing. The `P' action pops up a flashing `message' at the current mouse cursor position, and awaits a key or mouse button depression before `popping down'. eg. PHello there! If a null string is passed as a parameter, an asterisk will flash in the bottom right hand corner of the screen. This can be used as a pause to await a key depression from the user before continuing with a series of actions. - 56 - HyperShell Users Guide The HyperShell language 4.2.20 String Functions A number of string functions are available as `action modifiers'. Strictly, all action modifiers are functions of some sort, but the string functions are classified as `functions' to separate them from the dynamic menus and other string providers. The string functions provide a set of facilities analogous to the BASIC functions, although even those returning a numeric result are classified as string functions in this case, both because they operate on strings, and because they return the result as an ASCII string regardless. The functions take the form:- &FPstring Where `F' is the function code, `P' is an optional parameter and `string' is the string to apply the function against. Some common string functions with an equivalent BASIC function are as follows:- &L - Length of argument (BASIC LEN) &A - ASCII value of first char of argument (BASIC ASC) &C - character with ASCII value argument (BASIC CHR$) &Sn - substring starting at nth character (BASIC MID$) &Ic - index of character `c', or 0 if none (BASIC INSTR) &K - single character input (Basic INKEY$) Also similar functions are provided as follows:- &Nn - nth character in argument &Uc - substring up to, but not including character `c' &Fc - substring from character `c' inclusive A number of other functions exist and are documented in the reference guide. 4.2.21 Scale number HyperShell deals in integers, or `whole' numbers. This means that calculations for money, for example, have to be carried out in smaller units (pence in the case of money), and the result `scaled' for display. The `&B' function is used for this purpose. It takes the next character as the number of decimal places to display. eg. to display the value of variable `m' with two decimal places:- &B2$m So:- &B212345 - returns 123.45 &B312 - returns 0.012 - 57 - The HyperShell language HyperShell Users Guide 4.2.22 File input / output Most languages provide some form of file input and output. HyperShell provides a fairly straightforward means of reading or writing to a file. It is not intended as a fully fledged language, so only permits one input and one output file at a time. It is possible to have one file open for input and to keep this open whilst another file is opened for input, read and closed, however. To open a file for reading or writing, the action:- rfilename / wfilename is issued (r for read, w for write). To read a record, two mechanisms are provided. The formatted read allows a set of variables to be loaded from `fields' in a text record. The `R' action is used for this:- R:abcdef Reads the next input record and splits it into variables a,b,c,d,e and f on a separator `:'. The other means of reading an input record is provided by the iterator action modifier - `!'. This can be used in a number of ways. The simplest construct is `!' by itself, which returns the next input record. Other constructs provide lookup capabilities. The form:- !Fkey reads the next record starting with the string `key'. If it is necessary to read the first record in the file starting with the `key', the format:- !Lkey is used instead. Thus this method can be used to provide a lookup facility. This lookup is performed sequentially, however, so cannot be practically used if the file concerned is huge. A special format is provided which can search very large file provided they are sorted into ascending order:- !Bkey This does a very fast search on the file using a `binary chop' search algorithm. File output is done using the `W' action. This simply takes its argument as the record to be written. The record can be formed from any of the standard action modifiers, or from variable tokens:- W$a:$b:$c:$d:$e:$f - 58 - HyperShell Users Guide The HyperShell language which would write a record made up of the variables a to f separated by `:' characters. 4.2.23 Printed output It is useful to be able to output information to the printer. The `o' action is provided for this purpose. It does, however, provide a `device independent' route for output information, controlled by option 5. Option 5 should be set to 1 for output to go to the printer. O51 The `o' action works in a similar fashion to the `W' action:- oThis line goes to the printer The set of values for option 5 are as follows:- Output routes +-------------------------------------------+ | O50 | Display output on bottom line | | O51 | Print output on printer | | O52 | Direct output to `standard output' | | O53 | Direct output to AUX device | | O54 | Write output to current output file | +-------------------------------------------+ Having the output controllable in this fashion allows the same set of code to output the same information to one of a number of routes. For example reports can be directed at a file or straight to the printer. Standard output is the standard output stream used by MSDOS for display on the screen or redirection to one of a number of routes using the `>' or `|' command line options. The current output file is that, if any, opened using a `wfilename' action. 4.2.24 Backtracking Wandering through a maze of hypertext information can easily make the user feel `lost in hyperspace'. HyperShell helps out in a number of ways with enabling the user to get back to where they wanted to be. The backtrack list is maintained (unless the author has prevented this) as the user wanders from frame to frame. The F3 key is mapped to the simple single step backtrack, and successive depression of this leads the user back to the main track. The F4 key is mapped to the multiple backtrack list, which enables the user to jump directly back to one of the frames he has visited. The F3 key is mapped to the simple backtrack action:- B - 59 - The HyperShell language HyperShell Users Guide The F4 key is mapped to a dynamic menu which returns the backtrack level, and uses this to unwind to that level. The action is therefore:- b@B Another kind of backtrack selection is possible. The `@b' dynamic menu does not return a backtrack level, but instead returns a frame display action, as in the contents and search lists. This can be used in the following form:- A@b which has the effect of `revisiting' the frame, without unwinding the backtrack list. 4.2.25 Expression evaluation As explained above, we can code simple expressions to work with numeric variables. So, for instance, we code the following to add variables b and c giving variable a:- Va=b+c The expression evaluation operator is capable of much more than this, and can handle boolean and bit arithmetic operations as well as other complex structures. eg. Bit operations +-----------------------------------------------+ |expr!expr | arithmetic or | 2!3 | returns 3| |expr&expr | arithmetic and | 2&3 | returns 2| |expr^expr | exclusive or | 2^3 | returns 1| |@expr | 1's complement | | | +-----------------------------------------------+ Boolean operations +-----------------------------------------------------+ |expr>expr | greater |These return | 2>3 | returns 0 | |expr<expr | less | 0 if false | 2<3 | returns 1 | |expr=expr | equal | 1 if true | 2=3 | returns 0 | |~expr | not expr | | | | +-----------------------------------------------------+ also:- #c condition code truth #s returns 1 if error "vxxxx"c combined variable comparison and condition truth "nfred"e!"njim"e returns 1 if n = fred or jim Also the following triadic conditional operator is provided:- expr?true expr:false expr eg. - 60 - HyperShell Users Guide The HyperShell language a<3?45:78 This returns 45 if variable a less than 3 else it returns 78. The `truth' can be tested using the `n' condition code which is set to reflect a non-zero result:- Y=(a<3)!(a>23);jnOUTSIDE RANGE The `ZI' action (pronounced `IF') is especially designed for use with boolean expressions and compound conditions. This is used at the start of a multiple action, where the rest of the multiple action is executed if the condition is true. ZIx>100;Px is over one hundred ZI"ntaylor"c;Phis name contains `taylor' 4.2.26 Mouse cursor positioning As popup menus, notes and messages are positioned relative to the mouse cursor, it is useful to be able to position the mouse cursor so that the popup appears where you want it. This is done using the `ZX' and `ZY' actions, which set the column and line position of the mouse cursor. eg. set cursor at column 3 of line 15:- ZX3;ZY15 4.2.27 Searching Hypertext documents, whether they be reference manuals or information bases, need a search capability to allow information about a particular topic to be located, if this is not readily available through the normal navigational channels. HyperShell provides a number of different dynamic menus to provide a search capability against the text. The two basic types are a search against the frame names and titles, and a search against the names, titles and text of frames. The search menus return a frame reference if one is selected from the menu. A@S?search string prompts for a string and searches for it in the frame names and titles of the current hyperfile. All matching frames are listed, allowing one to be selected. If one is selected, the frame display action is returned and the `A' action performs this to display the frame. You may recognise this as the default action mapped to function key F6. The `@X' menu does a search of the frame text as well. - 61 - The HyperShell language HyperShell Users Guide Selecting from the menu of matching frames during the search might be what we wish to do if we spot the frame we were after. If it is not the frame we were after we might have to run the search again. One way of avoiding this is to allow the search to complete, then present a list of matching frames. This is achieved in a two stage process. To do the initial search, we code the following multiple action:- O*65;A@S?Search string This will do the same search as previously, but will not stop to allow a frame to be selected. In fact, as the dynamic menu cannot return anything, the `A' action code is redundant. Well. How do we display the list of matching frames? This is done using a variant of the contents list. The contents list, mapped by default to F2, provides a listing of frames in the hyperfile. It is another dynamic menu returning the selected frame reference, and a contents list usually takes the form:- A@C This contents list displays all frames, but it flags those which matched the last search with a small arrow to the left of the frame name. We might not want to look through pages of frames for flags, however. To display a contents list of just those frames which matched the search, the following variant is used:- A@C1 These contents lists can be repeated to display the matching frames for selection, whilst the frames are selected one at a time. Another way we can go through the matching frames is to select the first matching frame initially. To step to the next matching frame, the action `F+1' can then be used. Of course, we can't expect the user to type in all these actions himself. We could provide a menu which offered all these stages:- +-------------------------------------------+ |.MENU Search Control | |Search for string |O*65;A@SSearch string | |List matching frames|A@C1 | |Next matching frame |F+1 | +-------------------------------------------+ Then we could map this menu to the F6 key as follows:- KF6MSearch Control This uses the key mapping action described previously to map the Search Control menu to the F6 key. - 62 - HyperShell Users Guide The HyperShell language 4.2.28 The Notepad The notepad is a list of reference strings used as `bookmarks'. The usual way of adding references to the notepad is the INS key, with the DEL key removing them again. The notepad may also have data added and removed by the `H' and `h' actions. The items on the notepad are normally assumed to be action specifications, although it is possible to store other data on the list for selection for other purposes. The INS key, and `H' action, by default requests a comment string which is associated with the reference when it is listed. This can be suppressed using the option flag setting:- O*80 The notepad display dynamic menu `@R' displays a paged list of the contents of the notepad. It returns the action associated with the selected notepad item, and is usually used with the `A' action, as in the F5 default mapping:- A@R It is also possible to read the notepad like a file. The `!R' iterator is used to return successive items from the notepad. The `!C' iterator returns the associated comment. The `!R' iterator can also have a key appended, which causes the references to be scanned for one starting with the key string. For example, to return the next note reference:- !RN Any search or step is taken from after the last reference obtained. The scan pointer is reset whenever a reference is added or removed from the list, and can be rewound with a dummy `remove' action:- h The EOF status is set when the end of the references is reached. 4.3 Application structures This section describes the use of HyperShell in various application areas. The structures described may relate to specific areas, or may be of general use. It is worthwhile becoming familiar with the capabilities whatever application you will be developing. - 63 - The HyperShell language HyperShell Users Guide 4.3.1 Frames as menus The term `menu' is used somewhat freely in the computing sector to mean petty well any representation of a choice of selections. The original menu systems provided a screen display with a set of numbered options. Pressing the number key selected the option and caused the display of a further menu in a hierarchy, or in the running of a program function. HyperShell menus are of the more recent `popup' variety, but HyperShell frames are ideally suited for use as this other form of menu. Thus HyperShell can also be used as a versatile menu system, with capabilities well beyond those of other menu systems on the market, such as displaying graphic images, incorporating application related help, and providing form-fill capabilities for inputting program parameters. A simple menu system can be built using a frame for each menu. The higher levels of menu consist of frames containing choices leading to frame references to the lower levels. At the bottom level, selection of a reference will cause the invocation of a program command line. A simple one frame menu can be used to drive a small number of programs. entering an empty HEADER item and the text from the FRAME as below:- +----------------------------------------+ |.HEADER | Null header |.SCRIPT SETUP | |O62 | Enable swapping |.FRAME menu1 | | | | --- My Menu --- | | | |~A1. Accounts~PDaccounts~K1~E | DOS program | | |~A2. Invoices~PDinvoices~K2~E | DOS program | | |~A3. Payroll~PDpayroll~K3~E | DOS program | | |~A4. Spreadsheet~PE123~K4~E | Chained program | | |~A5. Exit~PQ~K5~E | |. | +----------------------------------------+ This menu allows the options to be selected as normal, or by use of the numeric keys 1 to 5. Note that the spreadsheet option causes the program to be chained rather than executed as a sub-process, to allow the spreadsheet to have all the memory to itself. The null header is used in hyperfiles to suppress the default header display. Of course, a multiple menu system can be constructed using a frame for each menu, with selections simple moving to other frames, or invoking programs at the lowest point. - 64 - HyperShell Users Guide The HyperShell language The E action can be used, and the menu hyperfile can be re-entered at the same point, by using the -r flag to save a restart file, and by coding the HyperShell invocation in a loop in a batch file:- +---------------------------+ |:LOOP | |hs -r menu | |if errorlevel 1 goto QUIT | |goto LOOP | |:QUIT | +---------------------------+ The menu hyperfile can then quit by using the `Q1' action string. 4.3.2 Program execution Actions are provided to allow other software to be run from a menu application in a number of ways. The DOS command action is available for the majority of tasks, and the chain execution action is available if HyperShell cannot remain resident with heavyweight software or with software requiring lots of data storage. The DOS command action runs a program via the DOS command processor (COMMAND.COM), so can run batch files and built-in commands and can have file indirection parameters added. This action takes the form:- Dprogram parameter parameter parameter . . . The option 6 setting is only applicable to the HS.EXE program, and causes the program to be swapped to disk when it runs another program using the DOS command action. It leaves only 1.5k resident in memory when this happens, rather than the 128k it would otherwise occupy. DOS command action With swapping +-------------------------+ +------------------------+ | APPLICATION | | | | PROGRAM | | APPLICATION | | | | PROGRAM | |-------------------------| | | | COMMAND.COM | | | |-------------------------| |------------------------| | | | COMMAND.COM | | HYPERSHELL (128k) | |------------------------| | | | HYPERSHELL (1.5k) | +-------------------------+ +------------------------+ The chain execution action allows a program to completely overwrite HyperShell in memory, and is specified as follows:- Eprogram parameter parameter . . . - 65 - The HyperShell language HyperShell Users Guide The subprogram execution action is a special purpose variant of the DOS command action, where the program is executed directly and the command processor is not used. This is faster, and provides access to the exit code of the program which is invoked. This action takes the form:- Xprogram parameter parameter . . . When HyperShell is invoked from other programs or batch files, it can set an exit status which may be used by the other program. This is done simply by appending the numeric exit status to the `Q' action used to exit HyperShell. So, to exit with status 120:- Q120 4.3.3 Form Fill HyperShell frames can also be used as data entry forms or database browsing forms. This is brought about by one powerful type of reference - the input field. An input field is like any other reference, until you select it. It then becomes an input area into which you can type a string. It is generally the case that the input string is used to set a variable, and that the variable is displayed in the field until it is selected. The width of the field is generally specified in the field specification, as it is this which determines the maximum size of the field. A typical input field would look like:- ~I$v~W10~PVv%s~E This specifies an input field of length 10, in which the variable `v' is displayed. After entering a string, it is assigned to the variable. Where a number of fields are supplied in a frame to form a form-fill screen, they can be `chained' to the next input by use of the `I' action. This causes the next input field to be selected. e.g. ~I$v~W10~PVv%s;I~E does the same as the above field, and then selects the next input field. The user sees this as a typical form-fill interaction, and can press ESCAPE to cancel the sequence of inputs. The `immediate reference' flag can be used with form frames to select the first input field, or to execute a script to open files etc. prior to any processing. 4.3.4 Data bases The file input and output facilities can be used, along with the form fill, to implement a simple `database'. These are really `flat files' but everyone else calls these databases, so we will as well! - 66 - HyperShell Users Guide The HyperShell language The format of data files described here can be imported and exported by many database systems. They can also be processed by certain utilities originating on UNIX systems, such as AWK, JOIN, SORT etc. To work through an example we will firstly provide a reference to allow a file to be opened for writing. ~AOpen file for writing~Pwdata.txt+~E The `+' at the end of the filename indicates that the file should be extended if it already exists. Thus we can add records to an existing file. The last input field on a form could write the data out after input:- ~I$f~W10~PVf%s;W$$a:$$b:$$c:$$d:$$e:$$f~E This would write out a line containing variables `a' to `f' separated by `:' characters. As an alternative, a separate action reference can be used for writing a record, so that changes can be made to the input fields before writing:- ~AWrite record~PW$$a:$$b:$$c:$$d:$$e:$$f~E Note that the double dollars are needed to stop the variable expansion taking place when the frame is displayed. To close the file, another action reference of the form:- ~AClose file~Pw~E can be supplied. How about using a form to browse through a database. To open a file for reading, we have an action:- ~AOpen for reading~Prdata.txt~E If the database consists of text records with fields separated by a special character (like `:' above), we can read a record into a number of variables with one action string:- ~ARead file~PR:abcdef;y~E This reads the next record and refreshes the screen, allowing any variable expansion tokens for the variables input to be expanded. These could be in input field specifications, or elsewhere in the frame text. If we want to perform a lookup in a text file, the `R' action cannot be used. In this case we could use an input field to input the first variable as a key, and lookup the record. ~I$a~W20~PVr!L%s;er:abcdef;y~E - 67 - The HyperShell language HyperShell Users Guide This rather complex action uses the input string as a key to look up a record starting with the key field, reading the record into variable `r'. It then expands `r' into a,b,c,d,e and f before refreshing the screen to display the values. Note that a slightly more complicated action is required in practise, as it has to handle the case where the record is not found - the above example would set all variables to a null string (which may be acceptable in some cases). Another thing we can do with our `database' is to produce a simple formatted list. This is made possible by the `@G' dynamic menu. This takes the form:- @Gfilename.ext What this returns depends on the format string we set up. To use this, we first have to set up some general strings using the `KG' action. For our example above, these will be as follows:- KG5:abcdef KG7[%c] ~A$a~P$a~K%c~E~C20$b $c $d $e $f When the dynamic menu is run, each line in the file is split using the G5 mapping as a string split specification as above. The format string specified in G7 is then displayed for the line, the variable tokens being expanded to form the tabulated list. Two `%c' tokens can be inserted in the format line, which are replaced by the lowercase alphabetic letters when the list is produced. The action reference can be selected, and causes the dynamic menu to return the value of the first field, as loaded into variable `a'. So what is G6 used for, you ask? The G6 mapping is used to provide a selection expression, which is used to select records to be displayed. By default it is set to `1' indicating that everything should be displayed. The expression can take the form of the expression used for the `=' action modifier and the `ZI' action. If the expression evaluates to a non-zero value, the record is displayed, otherwise it is ignored. If, for example, the third field (loaded into variable c) was an AGE field, we could select those people between the ages of 20 and 60 using the following mapping:- KG6(c > 19) & (c < 61) Of course, we could allow the user to enter a selection expression. We then have a query language??? 4.3.5 Directory browsers HyperShell provides a number of directory menus which allow file names to be selected for processing. The simplest form of directory display is a popup dynamic menu of the form:- - 68 - HyperShell Users Guide The HyperShell language @Dwildcardspec The `@d' works as for the `@D' menu, only the file extension is included in the menu, and is returned on selection. The `@E' works as for the `@D' menu, only the menu presented only includes subdirectories. The menu return can be used in any action, or dynamic menu, requiring a file specification as a parameter. T@d*.TXT This gives a menu of files with extension .TXT and then displays the file selected. C@E*.* This makes the selected directory current There are also a number of detailed directory listings provided as paged displays. The extended directory display `@L' presents a paged list showing details of the files matching a wildcard specification. It returns the selected filename, as for the `@D' popup menu. The filename and the extension are loaded into variables `$<' and `$>', and the extension can be used in a script to select processing which is appropriate for the file type. This is the equivalent of the `object oriented' directory listings of graphical user interfaces such as GEM and Windows. In fact, a choice of processing via a popup menu can be provided for each file type, unlike the GUIs, which are forced to perform only one action with a file selected in this fashion. Another detailed directory display is available which has actions already added ready for processing. The `@l' menu provides its own action strings for typing a text file or changing to a directory, and is used with the `A' action. This is driven by the file extension. 4.3.6 Graphic screen display Many hypertext applications can provide sufficient information using textual descriptions, but the use of diagrams and pictures can help enormously in some applications, and are essential in others. HyperShell is normally text based, but supports graphic screen displays with optional selection zones on them. Graphic screens have to be prepared using screen capture, graphic paint packages and graphic conversion programs. Once a graphic screen in the correct format is available, the zones can be mapped, and the screen integrated with the hyperfile. Graphic screens are held separately to the hyperfile, and are displayed using the `G' or `g' actions. These display a graphic or text screen from a file in BLOAD (Microsoft BASIC) or .PCX (Microsoft Paintbrush) format. - 69 - The HyperShell language HyperShell Users Guide After display the mouse may be used to select a zone on the screen, or a key may be pressed to choose an option if no mouse is available. The character and zone mappings are defined in a special form of MENU, and selected using a zone selection menu. The `g' action does not reset the screen mode after display, so that graphic screens can be displayed one after the other with no lack of continuity. The `g' action with no parameter resets the display mode to the default text mode, which would otherwise take place the next time the frame display is refreshed. The zone selection menu is specified using a special form of menu call, as follows:- Mmenuname[@] The menu options for a zone selection menu are set up using the graphics preparation facilities described later. An alternative method is to use a script which handles the coordinates of the selection itself. The `&X' and `&Y' functions return the column number and line number of the mouse cursor when a button was pressed during the last graphic display. The `&Z' function returns the key pressed. If these coordinates are to be set for other than a graphic display, the `ZG' action can be used, which causes the mouse coordinates to be set. The `Zg' action is also available for a slightly different purpose. This will cause the mouse to be used for selection from the screen currently on display. If a parameter is supplied (eg. Zg#), the screen is assumed to have a high vertical resolution (greater than 200) when calculating the mouse coordinates. This can be used where some external program is used to display the graphic screen, or possibly when a further selection is needed from a screen displayed using the `g' action. 4.4 Advanced features Certain applications demand more control over the display and operation of the hyperfile. A number of advanced control facilities are provided, which are not expected or required to be used for the majority of purposes. These assume a certain level of programming familiarity, and can readily cause problems for those who try them without fully understanding their function. As always, a certain amount of trial and error is necessary to get the most out of these. It is recommended that you do not try these until you are reasonably conversant with the features described above. - 70 - HyperShell Users Guide The HyperShell language 4.4.1 Display control Direct Positioning During text display in a frame or note (or direct output - see below), the text writing position can be absolutely positioned using the direct positioning flags. These are similar to the line and column positioning flags, but have more power in that they will change the position regardless of the current position. This power is at the same time useful and dangerous, as text can easily be overwritten and the text garbled. The two commands are the equivalents of ~L and ~C, and are as follows:- ~Ynn set position to line nn and ~Xnn set position to column nn The ~X flag has the added function of setting the `start' of a width specified by the ~W formatting flag. Indents In a large hyperfile, it can get tedious adding a left margin to every frame. One way of saving some work is to use the indent formatting flag to set a standard left margin which will be used to offset the text on display in a frame. The flag takes the form:- ~in where `n' is the indent between 0 (for no indent) and 9, for 9 spaces indent. This is coded on the line after which you wish the indenting to appear. On common location for this is at the end of the HEADER item, to set it for the frame text display (and possibly again at the start of the FOOTER to reset it to 0). When an indent is in effect, a line can be temporarily reset to flush left using the direct column positioning flag:- ~X0 The indent has its disadvantages. The integrated environment editor does not show the indent, and so any tabs and direct column settings in the line may cause the edit display to not reflect the appearance of the eventual frame display. - 71 - The HyperShell language HyperShell Users Guide Boxes Having boxes around text can help to enhance the appearance, and to subdivide the display. Boxes can be drawn within frame and note text using the graphics characters of course, and this is preferable when the box is specific to a frame or note, or within the header or footer. Many text editors provide box drawing capability, and these can be used to produce the boxes or tables, which are then imported to HyperShell. Where a box is required around every frame, or where a box is required around `expansion references' there is a dynamic box drawing capability provided by HyperShell. With this, the top left corner of a box is marked, then at the bottom right corner another flag is coded which causes a box to be drawn. Thus the following flags have the illustrated effect:- ~a +-----------------------+ | | | | | | | | | | ~b1 +-----------------------+ For a frame display, these can be used with actual margins or specified indent to frame the text. The HS hyperfile uses this, and should be referred to as an example. Other codes can be used with the box flag to cause a text window to be defined within the box, or without a surrounding box. Text can then be written into the box, and can scroll without affecting the surrounding display. If a sub-window is set up, text may be output to it using the direct output facilities (see below). It can also cause unwanted (and often amusing) effects, due to other output trying to appear in the small window. To avoid this, the `Zr' action is provided to reinstate the full screen window. Direct output Once the frame has been displayed, there seems little that can be done to change what is on display, and it seems awkward to have to redraw the whole frame to change one value on display. The direct output action has been provided to overcome this apparent restriction. It allows an action, usually in a script, to write straight to the screen. This action takes the form:- istring where `string' is the string to be displayed. The string can contain any formatting flags, as used in the frame display, such as colour scheme settings, direct positioning and even references. The direct positioning flags are nearly always used in this action, unless it follows after another such action. - 72 - HyperShell Users Guide The HyperShell language When displaying references in this manner, you should be aware of the following:- 1. If you overwrite another reference, the original reference will be selected first always. Every reference drawn adds to the list and you may hit the limit if you repeatedly output references. 2. If the reference is drawn `among' other references, the TAB/SHIFT TAB stepping will not work as expected when it comes to these references. The box display, and the sub-window variants, may also be used after the frame has been drawn, to cause a window to overlay part of the frame display. This can be used for displaying extra information, or for a number of purposes, including effects (such as wipes or explodes). In this case, two sets of direct positioning flags are used in the action, with the box start after the first and the box end after the second. Direct input Of course, once you have the capability of outputting anything anywhere, you will want to input from an arbitrary point as well. The `&i' function is provided for the more adventurous of you, and has the following format:- &i{default} where default is an optional default value which is displayed for editing. This function allows a string to be input at the current `output' position, as set by the direct output action. The string entered is returned as the result of the function. Screen saving and showing After the direct output facilities are used to draw a number of boxes containing information on the screen, it is sometimes desirable to clear the information from the screen. This can be done by refreshing the screen with a `y' action, of course, but another method exists. This uses the screen save area which the `-s' command line flag otherwise uses, to capture the full screen display, and subsequently re-display it. This is done using the two actions:- ZT Take copy of screen Zt Display copy taken with ZT The copy is taken before the direct output of sub-windows and boxes, and shown when the information is no longer required. The re-display is almost instantaneous, and it appears as though the boxes have been `popped down'. - 73 - The HyperShell language HyperShell Users Guide 4.4.2 Program control SHARE directive If we have a number of hyperfiles which use a common HEADER, FOOTER and set of global items, the following directive can be used. .SHARE This is used in secondary hyperfiles in place of the HEADER, FOOTER and global items, and causes that hyperfile to use those items from the primary hyperfile. A primary hyperfile is the one specified on the command line (or HOME.HYP if no hyperfile is specified). The secondary hyperfiles can be pre-loaded using the action:- ZPfilename Autoreferencing Autoreferencing is the dynamic addition of reference flags to text as it is displayed. Using autoreferencing, you can view normal text files, and key words and phrases will be highlighted as references which can be selected. This enables a reference hyperfile to be resident when viewing a technical document file. There are many other possibilities to the various forms of autoreferencing. The autoreference capabilities provided by HyperShell are as follows:- Autoreference categories Option +--------------------------------------+ | Frame name autoreference | O41 | | Global note name autoref | O44 | | Application Specified autoref | O42 | +--------------------------------------+ Autoreference targets Option +--------------------------------------+ | Files displayed by `T' action | O*40 | | As above plus frame texts | O*41 | +--------------------------------------+ The settings for option 4 may be added together to form a combination of autoreferencing. If option 4 is set to 0, no autoreferencing takes place. Frame name autoreference should only be specified for hyperfiles with a low number of frames (possibly up to 100 frames), as it slows down the display depending on the number of frames. Global note name autoreference is very useful for reference and tutorial applications, where a number of terms can be explained in global notes, and these can be popped up for an explanation. - 74 - HyperShell Users Guide The HyperShell language Application specified autoreference is a more general form of autoreferencing, and is specified for the current hyperfile using the ZA action. This takes the following form:- ZAkey:action The `key' part of this is of the form:- Astring Where `A' is the reference type letter, and `string' is the key string to be matched in the displayed text. The `:action' part specifies the action parameter to be added to the reference. The `:action' part can be omitted, in which case the reference is substituted without a parameter part. For example:- ZAMIndex Will replace the string `Index' in the displayed text with `~MIndex~E'. When selected, this will display the global menu `Index'. Or:- ZAAbell:ZB Will replace the string `bell' with `~Abell~PZB~E'. When selected, this will sound the bell on the PC. Uses for this form of autoreferencing are limited only by your imagination. Unget character One of the more useful tricks in HyperShell is the use of the ZU action. This action `ungets' a character so that it will appear as though that character has been pressed. This takes the form:- ZUc Where `c' is the character to `unget'. For example, suppose we wish to activate a specific field on an input form. If we provide a key mapping for each input field, we just have to unget the appropriate key to select that field. - 75 - The HyperShell language HyperShell Users Guide Immediate reference One reference on a frame or note display may be flagged as an `immediate' reference. This will be selected automatically after the frame or note text has been displayed. This is done by including the sequence ~Q after the complete reference sequence for the reference to be selected. This may be used for many purposes, but the most common would be to select the first input field on a form frame, and therefore put the frame into a data input mode automatically on entry. [n] Name: ~I$n~W20~PVn%s;I~Kn~E~Q The immediate reference flag may also be used with an `invisible' reference. This has a zero length reference string and does not therefore permit manual selection. This could be placed in the header or footer to, for instance, write a log file of frames visited. It can also be used to pop up a note or a menu on moving to a frame. The following writes the frame name to the current output file (this could be included in the HEADER text). ~A~PW$1~E~Q 4.4.3 Communicating with other programs When running your program from HyperShell, it would sometimes be useful to pass information back to HyperShell. If you write your own programs, this can be possible, using the following technique. A function is provided which returns a string representing the segment:offset address of a variable:- &vV - where V is the variable name This address should be placed in the command line of the program which you are running. This can then allow it to access the variable directly. A number of such addresses can be supplied. The variable to receive the data MUST be set up in HyperShell to a length sufficient for the data to be loaded into it, using any data string e.g. VV----------------- The variable, after the call to the program, will contain the value set by that program. It may be reused on subsequent calls, and may be freed as normal when no longer required e.g. VV - 76 - HyperShell Users Guide The HyperShell language 4.4.4 String conversions Processing strings input from the user, or from a file, is a common requirement in some applications. Computer Aided Instruction applications often process a reply to a question before testing it against possible answers. There is an additional string function to perform explicit conversions on strings:- &#vstring This converts variable `v' according to `string' The `according to' string is a string of directives to show the conversion required. String conversion directives +---------------------------------------------------+ | l | convert to lowercase | | u | convert to uppercase | | s | strip leading, trailing and extra spaces | | tv | translate according to variable v | | rv | remove characters as specified in variable v | +---------------------------------------------------+ The translate variable will contain pairs of characters, the first of a pair being the character to translate from, and the second character being the character to translate to. The remove variable simply contains those characters which you want to remove from the string. Each directive can be made conditional by preceding it with:- ic where c is any condition code letter. eg. i3rr removes characters specified in variable `r' if frame-local flag 3 is set Directives and conditional directives can be combined in a single string:- ls - convert to lowercase and remove spaces For example, if variable `x' contains a response string, to convert this to lowercase and remove extraneous spaces, the following action is issued:- Vx&#xls - 77 - The HyperShell language HyperShell Users Guide The usual method of setting up for complex string processing is to set the translation and exclusion characters in the SETUP script. For example, to set up variable `t' to hold the translation for lowercase vowels to uppercase, the action would be:- VtaAeEiIoOuU The `remove' variable may also be set up here. A complication arises if you want to remove a `$' or `;' or `|' character. These would normally cause problems in a simple variable assignment action, and it has to be done by use of pseudo variables, or by first setting up a variable to hold the special characters:- Vd&C36 - set dollar in `d' Then, to assign the string `.,:;|@$' to variable `r':- Vr.,:$,$!@$d Also note the special characters which cannot be immediately after the variable name (&%@!?) - these should be put further along the string. 4.4.5 Formatting Patterns Earlier, we learnt how a formatting pattern could be added to an action modifier to format the result before it was applied to the action. Formatting pattern strings consist of the string expected as a parameter, with all occurrences of the chosen string represented by the token `%s'. Up to three tokens can be specified. As well as the more trivial example introduced earlier, this facility can be used for more complex formatting. The token can be coded in different ways for different format effects. Format token structure +-------------------------------------------------+ | %{-}{nn){.mm}s | | | | | | | | | maximum length (truncated at right end) | | | minimum length (right aligned, space fill) | | left align (else right align) | +-------------------------------------------------+ For example:- %s full string as supplied %8s string to minimum length of 8, right aligned %-8s ditto, left aligned %.23s string to maximum length of 23 - 78 - HyperShell Users Guide The HyperShell language 4.4.6 Pattern match In many applications, it is desirable to be able to compare a variable against a text `pattern'. This can be used for validation of fields, for instance to see if a date is in the correct format. The pattern match facility is available in HyperShell in a number of places, as follows:- Pattern match availability +----------------------------------------+ | Variable comparisons | | Menu table lookup | | Title and text searches | | String search in file display | +----------------------------------------+ Pattern specification The `pattern' can contain literal characters, ie. actual characters which must be present, and various `metacharacters' which represent patterns and classes of character:- Pattern metacharacters +------------------------------------------------------+ |< | at start - match start of string | |> | at end - match end of string | |? | match any character | |_ | match one or more space or TAB characters | |(a1/a2) | match a1 or a2 (optional if only one) | |[abc] | match `a', `b' or `c' | |[^abc] | match any character but `a','b' or `c' | |[x-y] | match any character in range x to y | |{ | start of word | |} | end of word | |x# | zero or more of character/subexpression x | |x+ | one or more of character/subexpression x | |* | any string (equivalent to ?#) | |\x | character `x' (for literal metacharacters) | +------------------------------------------------------+ Examples of patterns [a-zA-Z] Match any letter [a-zA-Z]+ Match an alphabetic string [0-9]+ Match a numeric string [aeiou] Match lowercase vowels (perhaps) Match optional string `perhaps' (cat/dog)(s) Match `cat' or `cats' or `dog' or `dogs' ((pine)apple/grape(fruit)) `apple','pineapple','grape', or `grapefruit' {and} Match the whole word and (not brandy) <This The word This at the start of a line or string \\ Match the '\' character - 79 - The HyperShell language HyperShell Users Guide cat*dog Match string with cat and dog in that order Th[^e] This, That, Those etc, but not The -{ A hyphen immediately before a word <????> Any four character string [A-Z][A-Z][0-9]+_[0-9][A-Z][A-Z] A british postcode?? Variable comparison The normal variable comparison can be made to perform a pattern match in addition to its other comparisons. An extended comparison is triggered by variable `~' being set. The value of variable `~' is used to contain a string conversion specification, or another character such as `#' if no conversion is required. The comparison translates both operands according to the conversion specified in variable `~', then if the second operand starts with a `^' character, the rest of that operand is treated as a pattern match string, otherwise a case sensitive comparison is performed. The variable comparison will then perform a pattern match comparison, setting condition code `m' is the match succeeded or code `f' if the match failed. If variable `~' is NOT set, the condition code `f' will be returned in all cases, even when code `e' is set. The conversions performed do not affect the value of the variable, and are effective for the comparison only. Menu table lookup The pattern match capability can also be used in a menu lookup table. @m[string] NOTE:- @m,@M,@F are all handled this way. This converts the string according to the variable `~' (if this has a value), and then compares the string against each key in the menu. If the pattern starts with a `^' character, it does a pattern match with rest of string as a pattern else it does a case sensitive string comparison, returning the action string if it matches. If the pattern is the character `*' it returns the action string. NOTE: Any conversions specified by the variable `~' will be applied against the pattern string as well as the comparator string. This means that case conversions, space removal, punctuation removal and diacritic conversions will be performed. Thus a variable containing characters to be removed must not contain any `pattern match' metacharacters used in the pattern strings, otherwise these will be removed before a pattern match, which will produce unexpected effects. - 80 - HyperShell Users Guide The HyperShell language The menu table lookup can save you a lot of effort, by reducing a series of comparisons to a simple table. The lookup menu has pattern strings which are handled like the additional variable comparison second operand. In this case, the action string is returned if the comparison succeeds, else it passes to the next in the table. For example, supposing we can have the a number of potential answers, which have varying degrees of correctness:- +---------------------------------------+ |.MENU school | |^(The boy/He) likes (the) school|C | |^(The boy/He) loves (the) school|N | |^(The boy/He) prefers (the) school|N | |^(The boy/He) hates (the) school|W | |^(The boy/He) dislikes (the) school|W | |*|H | +---------------------------------------+ This returns `C' if the answer is correct, `N' if it is nearly correct, `W' if it is wrong, and `H' if it is hopelessly wrong. We could then have a script to handle the input and testing:- +----------------------------------------------+ |.SCRIPT test | |-- ask question, get reply in `i' | |Vi?does he like school | |-- look up `correctness' and branch | |J@Mschool[$i] | |LH | |PThat answer is hopeless | |JCORR | |LC | |PWell done, that is correct | |-- add score | |Vs=s+10 | |JNEXT | |LN | |PThat is nearly correct | |Vs=s+5 | |JCORR | |LW | |PThat is wrong, but you have the right idea | |Vs=s+1 | |LCORR | |-- display correct answer | |pHe likes school | |LNEXT | +----------------------------------------------+ - 81 - The HyperShell language HyperShell Users Guide Note that the result of the menu lookup can be used to control almost anything, as the returned string can be used as the parameter to any action. Here it is used as a label to jump to. It could also be used to return the name of a note to display, or of a frame to branch to next. Patterns in searching The pattern match facilities can be used in the search operations available from the dynamic menus @S,@s,@X,@x. Also the search operation under the `T' (type file) action can make use of patterns in searches. To specify that a pattern search is to be done, prefix the search string with the `^' sign. It will then be interpreted as a pattern match search, in accordance with the rules for patterns given above. A@S^[0-9]# - Search for titles with numbers in them 4.4.7 Character input translation In computer assisted language learning (CALL) applications for languages with extended character sets which include diacritics (accented characters), the entry of these extra characters can prove a problem. Whilst alternative keyboard mappings are available with MSDOS, it is not always convenient to use these, and the key caps will not show the correct symbols if the keyboard is not intended for the language being used. A number of ways of entering these special characters are supported by different applications. HyperShell provides one method for supporting these, in the form of a character translation table. This capability allows string input characters (those input on the bottom line or to input fields) to have a translation mapping applied against them. This is usually used to map certain ALT shifted keys, or function keys, to the accented characters. Specification:- General key settings KG8 and KG9 provide the `from' and `to' tables of characters. Whenever a character in the `from' string is input, it is translated to the corresponding character in the `to' string. Thus, in a simple case, to map the keys `%&*' to produce `!=^' characters, the following settings are used:- KG8%&* KG9!=^ The two mapping strings must be the same length or results will be unpredictable. - 82 - HyperShell Users Guide The HyperShell language The `from' string specifications can be entered directly from keyboard, and the `to' strings can be entered using the ALT key with the numeric keypad to enter the extended character numeric code. The values of these are given in the appendix. The mappings do not have any effect on single keystroke inputs, such as function keys, menu selections, reference key mappings etc. The character input translation can also be used for stopping the input of certain characters by translating them to a character which is rejected during string input, such as TAB (ASCII 9). 4.4.8 Timing and timeouts Timing is an important feature of Computer Aided Instruction applications. HyperShell provides a number of facilities to help with this. Single character input with timeout The `&G' function takes the supplied numeric string as a timeout period in hundredths of a second. It then awaits a key depression and either returns the character pressed, or a null string if the timeout occurs. eg. Vn&G300 This waits 3 seconds for a key press and loads it into variable `n', or times out. The character input can be fed back as key input using the `unget' action (ZU), for use in selections from frame displays etc. For example, a multi-choice frame can be set up containing a number of key mappings for the choices. A script is run on entering the frame which issues the following sequence of actions:- +--------------------------------------+ |.SCRIPT get timeout | |-- Get key with timeout of 4 seconds | |Vn&G400 | |-- If timeout, branch | |jbTIMEOUT | |-- else put key back and continue | |ZUn | |q | |-- Tell them | |ZB;PSorry, your time is up | |-- Go to next question | |F+ | +--------------------------------------+ Time of day The `&H' function returns the time of day as hundredths of - 83 - The HyperShell language HyperShell Users Guide a second. This can be used to time long periods of activity, or to write a record to a log each time a frame is selected. Delta time The `&J' function returns the difference in time since the last call to function `&J', function `&G', function `&H' or the last frame display, in hundredths of a second. It can be used to time certain events, such as the time taken to select from a menu or a frame. Delay in displayed text The `wait' flag causes a delay in seconds before proceeding with the display. This is used to allow the user to read part of the text before showing subsequent text. eg. to wait 3 seconds in the display, the following flag is inserted:- ~w3 Teletype mode display The teletype flag causes text to be slowly displayed as though by an old fashioned teletype. The flag acts as a toggle, and is effective for the text following it on the line only. eg. fast text ~d slow text ~d fast text 4.5 Hints, Tips and Tricks This section offers advice on some of the obstacles you may encounter whilst using HyperShell and describes ways of getting around them. It also describes some useful tricks that can be used to utilise the power of the system in simple ways. 4.5.1 Special characters There is always a problem with getting special characters to appear where you want them, and to get them translated when you want them to. The sections later in this chapter describing the processing order for various stages should help in this process, but the following list is given of the more common problems. Frame and note displays To display a dollar sign or a flag character `~' in frame or note text, simply code two dollars or flags together. To have a variable token in a reference action string expand when a reference is selected rather than when it is displayed, code two dollar signs. To have a variable which contains another variable token which can expand in frame text, use a named variable for the container. - 84 - HyperShell Users Guide The HyperShell language Action strings To map a key to an action string which contains a variable token to be expanded when the key is pressed, code two dollar signs. To use an action modifier character at the start of an action parameter, code a `&W' function before the parameter. To get a `;' character or a `|' character into an action parameter, use the pseudo variables $, and $!. To include control characters and other special characters, set up a variable containing the character using the &C function to supply the ASCII value of the character, then use the variable token in the action string instead of the character. 4.5.2 Display tricks Local key mappings To get extra key mappings into a frame display, without having a visible reference, use a null reference string:- ~A~Paction~Kk~E This will map `k' to `action'. These can appear somewhere in the frame text, preferably at the end of a line or in a blank line, and preferably together if there are more than one. Frame revisits To display a frame for information, and return on any key press, code the following into the frame text:- ~A~PP;B~E~Q 4.5.3 General Staged backtrack To hold points on the backtrack to unwind to, hold the current backtrack level in a variable:- VL$6 And unwind using:- b$L Disabling Function keys To do this, simply map the function keys to a null string. So to disable ALL the function keys, do the following:- - 85 - The HyperShell language HyperShell Users Guide KF1;KF2;KF3;KF4;KF5;KF6;KF7;KF8;KF9;KF0 Also, you will need to map the ESCape key to a null string or something else, e.g. KH4MMy Menu This pops up a menu called `My Menu' instead of the control menu. Clear message line Simply issue the action p Extended matching frames list To give a contents list of matching frames from more than one hyperfile after an extended search:- O*63 A@X Automatic pick and search To configure a key to perform an automatic `pick and search', whereby the mouse cursor can be positioned over a word, a key pressed, and a search performed in the text for that word, the following action can be used K#pA@X&P This maps the `p' key to the pick and search action. Other search types can be used instead. It is also possible to map a key to show the first action associated with a displayed reference. This may be done as follows, which maps the `r' key to an action which displays the reference action on the bottom line. K#rp&Q The general key mapping 1 defines the action which will happen if the RETURN key or the LEFT mouse button is pressed when the mouse cursor is not over a reference. This could be mapped to the automatic pick and search to provide a different form of cross referencing. For example, it could be mapped to do a title search. KG1A@S&P - 86 - HyperShell Users Guide The HyperShell language 4.5.4 Keeping organised It is easy in a complicated application, when you only have a limited number of variables, to accidentally re-use one. This can cause problems for you, as the application will not work as expected. Also, the key mappings can cause similar problems if you have global mappings as well as key mappings for references. Application flags, local flags, option settings and other items which can conflict are all potential problem areas. The answer to these problems is to keep a chart of variables, key mappings, flags etc. with their usage written alongside. This will allow you to quickly determine if they have been used before. To keep things really tidy you could set up a REMARK which contained the chart, within the hyperfile. This would help you when you modified the hyperfile at a later date. 4.6 Processing flow These sections give a guide as to how certain processing stages operate, and are intended to help you understand how the system operates. Note interaction is similar to frame interaction. List interaction has similarities also, but differs in many respects. 4.6.1 Initialisation determine date format determine adaptor type process command line flags and set run options if filename not supplied, use HOME collect bits of frame name together from remaining arguments on command line and join together set up monochrome attributes if mono adaptor or -h specified set up default mappings save screen if -s specified call config initialisation - read HYPSHELL.CFG load main hyperfile if cannot open it - popup message and exit run SETUP script if present if -r or -n specified, run RESTART.HSF script if present if frame not displayed already, if frame name supplied on command line, display it else display first frame in hyperfile enter main interaction stage 4.6.2 Frame display Locate frame get frame name,title,date,time and memory variables for header text, frame text, footer text expand variable tokens display text, interpreting flags - 87 - The HyperShell language HyperShell Users Guide 4.6.3 Interaction (after frame display) a) if immediate action specified, goto b) accept input if control key, get mapped action, goto b) if RETURN / LEFT BUTTON, if over reference, get action string, go to b) else do default action (ie. KG... mapping) if key mapped globally, get action, goto b) if key mapped in frame display, get action, goto b) return to a) b) do action processing on action string return to a) 4.6.4 Action string processing a) if it has a `;' in it save bit from after first `;' for later truncate at `;' b) if it has a `|' in it, strip pattern string for later locate any action modifier character in pos 2 or 3 expand variables from modifier position or pos 2 onwards process action modifier (for dynamic menus look for further action modifier and do b) through c) on it.) apply pattern string to resultant line expand variables in resultant line c) handle action if further action to do, return to a) if bit saved from a) go back to a) return to caller - 88 -