WebChange for RISC OS

from Soft Rock Software

User Guide

Scripts

The WebChange script language is fairly straightforward and (I hope!) should be fairly easy to learn/use by anyone who has a simple grasp of programming. This guide is written with that sort of person in mind.

[Main Contents]

Script file format

Script files should be file typed as text, and have on the very first line:

WebChange.Script

This is so that WebChange can identify a script file dragged to its icon bar as being just that - a script file!

All subsequent lines should be either blank or contain a valid command.

[Main Contents]

The script language overview

The script language itself consists of a number of different things:

Commands
Processes
Settings
Conditions

Commands are the actual commands recognised internally by the script interpreter. Every (non blank) line within a script file should begin with a command. There are only a small number of commands.

Processes are the equivalent to the various tasks you can make WebChange carry out from the front end (eg find and replace, etc). There are, in fact, more processes available via the script language than via the front end.

Settings are essentially the choices that you set from the front end. Again, there are actually more in the script language than the front end - this is because some of the settings from the front end are used for more than one process, and in the script language they are expanded out accordingly, and there are also additional settings to deal with extra processes.

Note that where a setting represents something normally set in the front end, please refer to the relevant part of the documentation for a better explanation of what that setting should contain.

Conditions follow an 'If' command, and allow your script to do something only if appropriate - unfortunately, this is limited at present to a small number of built in conditions.

The way this guide will proceed from here is to first provide a "reference guide" to the internal commands. The next section following that will look at each of the processes, and will include an explanation of the relevant settings, and include an example. Conditions will be dealt with at the end.

[Main Contents]

Commands

; (semicolon)
the semicolon at the start of a line means the rest of the line is ignored, so you can use this to pad your script out with comments.

ChangeSetting settingname To "value"
Set settingname To "value"
these two are used to change one of the various settings. 'settingname' should be the name of the setting, as detailed later with the relevant processes, and "value" is the value to use - if it is enclosed in quotes, the string between those quotes is used. For example:

ChangeSetting Filename.Case To "Upper"

However, you can also use another setting as the source, in which case, use its name without quotes. For example:

ChangeSetting Filetype.ChangeFrom To Replace.ChangeFrom_1

Note that all settings are strings, so quotes should always be used if you aren't using another setting as the source.
Note also that the path/s setting is a special case, and as such has its own commands for manipulating it (see below).

RunProcess processname
Run processname
These two run one of the various processes. 'processname' should be the name of the process as detailed later. For example:

RunProcess Content.Replace

If condition Then command
this is the conditional command. 'condition' should be one of the predefined conditions (see later) and command can be any command as defined in this section.

ClearPath
this empties the path/s list, which means no subsequent process will have any effect until/unless you "add" a new path, using...

AddPath "path"
this adds "path" to the path/s list.

Prompt "message"
this pops up a window, with ok/cancel buttons, displaying the specified buttons. The button clicked can be checked in an If command (See later).

Stop
this halts execution, with a window informing the user.

QuietStop
this halts execution without the notification window.

[Main Contents]

Processes and settings

The processes should be used in a "RunProcess" or "Run" command. Most processes have a number of associated settings, which (unless using the equivalents from the front end, or the inbuilt default for those with no front end equivalent) should be set before the process is called. All processes use the path list setting.

Content.Replace

this is the main search and replace process. The associated settings are: Replace.ChangeFrom_1, Replace.ChangeTo_1, Replace.Context, Replace.CaseSensitive, Replace.Wildcards and Replace.ContextType

Replace.ChangeFrom_1 contains the text which is to be searched for.
Replace.ChangeTo_1 contains the replacement text. (if this is empty, the above text is deleted each time it is found).
Replace.CaseSensitive should contain either "Yes" or "No". If "No" then when it searches there is no distinction between upper and lower case letters (so "wibble" is the same as "WiBBLe").
Replace.Wildcards should also contain either "Yes" or "No" and determines if searches can included wildcarded text. Note that only simple wildcards are allowed - basically just "*" in the search string (Replace.ChangeFrom_1) to represent one or more unspecified characters.
Replace.ContextType and Replace.Context
The two 'Context' settings are the only two which aren't set from your front end choices, and the default is therefore that they aren't used. If, however, you put "0", "1" or "2" into Replace.ContextType, the Replace.Context setting is used as follows:
"0" means not used (the default) "1" means the search and replace is only carried out on files which contain the context string. "2" means the search is only carried out on any files which do *not* contain the context string. Further context options are to be added in the future.

The following script segment, for example, will perform two search and replaces straight after one another:

ChangeSetting Replace.CaseSensitive To "No"
ChangeSetting Replace.Wildcards To "Yes"
ChangeSetting Replace.Context To "0"

ChangeSetting Replace.ChangeFrom_1 To "Captain*Kirk"
ChangeSetting Replace.ChangeTo_1 To "Captain Picard"
RunProcess Content.Replace

ChangeSetting Replace.ChangeFrom_1 To "Spock"
ChangeSetting Replace.ChangeTo_1 To "Commander Ryker"
RunProcess Content.Replace

What that script will do is first ensure that the searches are *not* case sensitive, and that wildcards are enabled. (So Captain James T. Kirk will be found, as well as Captain Kirk, or Captain James Kirk).

The third line ensures the context searching is switched off.

The next group of three lines changes all occurrences of Captain[something]Kirk to read Captain Picard.

The next group of lines changes all occurrences of Spock to read Commander Ryker. Thus:

"Captain James T. Kirk's first officer was Spock. Captain Kirk also considered Spock a friend."

would become:

"Captain Picard's first officer was Commander Ryker. Captain Picard also considered Commander Ryker a friend."

Content.EnhancedReplace

This is a slightly enhanced version of the search and replace, and works the same as above but uses two additional settings, not available from the front end: Replace.ChangeFrom_2 and Replace.ChangeTo_2

Replace.ChangeFrom_2 holds an alternative text to search for, and the enhanced replace will swap between finding Replace.ChangeFrom_1 and Replace.ChangeFrom_2 each time it finds what it is looking for. If Replace.ChangeFrom_2 is null, only Replace.ChangeFrom_1 is used.
Replace.ChangeTo_2 holds an alternative replacement text, and the enhanced replace code will alternate between using the contents of Replace.ChangeTo_1 and this. If Replace.Change2 is null, it will alternate between replacing found text with the contents of Replace.ChangeTo_1 and deleting it.

Consider this script segment:

ChangeSetting Replace.ChangeFrom_1 To "Miss"
ChangeSetting Replace.ChangeTo_1 To "Mrs"
ChangeSetting Replace.ChangeFrom_2 To "Smith"
ChangeSetting Replace.ChangeTo_2 To "Brown"
RunProcess Content.EnhancedReplace

This would alternate between finding "Miss" and "Smith", and replacing them with "Mrs" and "Brown". The text:

"Miss A. Smith is watching the tv. Miss Smith's first name is Angela."

Would become:

"Mrs A. Brown is watching the tv. Mrs Brown's first name is Angela."

Content.FileReplace

This is a third variation on the find and replace process, and this version allows you to perform a replace based on the contents of files. In other words, instead of supplying some text which is to be found (eg "original text") and the replacement text (eg "new text") you supply the paths to files which contain those two bits of text.

This approach allows you to use longer strings than the front end allows (writable icons are limited to 255 bytes).

This process uses just three settings:

FileReplace.ChangeFrom contains the path to the file containing the text to be replaced.
FileReplace.ChangeTo contains the path to the file containing the replacement text.
FileReplace.CaseSensitive should be set to either 'yes' or 'no' according to whether you want the search to be case sensitive.

This process provides a fine example of when you might want to copy the contents of one setting into another. Consider:

ChangeSetting FileReplace.ChangeFrom To Replace.ChangeFrom_1
ChangeSetting FileReplace.ChangeTo To Replace.ChangeTo_1
RunProcess Content.FileReplace

That in a script would copy the text from the two main window writable icons into the main two settings for the FileReplace process.

Content.IncludeDates
Content.IncludeSizes
Content.IncludeFiles

These are the three processes which are used to insert a files, their datestamps, or their sizes into the HTML. They use no settings other than the paths so, depending which one you are using, their usage is simply:

RunProcess Content.IncludeDates

or:

RunProcess Content.IncludeSizes

or:

RunProcess Content.IncludeFiles

Content.EnsureAlt

This is the process which is used to ensure all <IMG> tags include some form of ALT text. Note, it *only* puts in any alt text when the alt attribute is not present - existing alt text is untouched. It uses two variables, AltText.Value and AltText.Braces.

AltText.Value should be set to either 'i', 'p' or 'l' (though only the first letter is "checked", so you could write them in full as "image", "picture" or "leafname".
If 'i' or "image" is used, the word "Image" is used for the alt text. If 'p' or "picture" is used, then the word "Picture" is inserted as alt text. If 'l' or "leafname" is used, then the image's leafname is used.
AltText.Braces should be set to either 'y' or 'n' ("yes" or "no") and simply determines whether or not the alt text takes the form "alt text" or the form "[alt text]"

On it's own, this process isn't particularly powerful - alt text should be more meaningful than just saying "Image", "Picture" or "mydog3.jpeg". However, this is where the use of scripts is ideal!

ChangeSetting AltText.Value To "Leafname"
ChangeSetting AltText.Braces To "No"
RunProcess Content.EnsureAlt

ChangeSetting Replace.CaseSensitive To "No"
ChangeSetting Replace.Wildcards To "Yes"
ChangeSetting Replace.Context To "0"

ChangeSetting Replace.ChangeFrom_1 To "ALT=|Smydog*|S"
ChangeSetting Replace.ChangeTo_1 To "ALT=|SA picture of my dog|S"
RunProcess Content.Replace

This would replace all alt texts which contained 'mydog' to read ALT="A picture of my dog", which is only the very simplest of uses - better still would be a script which includes a search and replace for every image leafname which would appear on the site - so that "cologo.gif" would expand to "Company Logo", "mydog1.jpeg" to "A picture of my dog playing with a tennis ball", "mydog2.jpeg" to "A picture of my dog sitting in the garden", "mydog3.jpeg" to... you get the picture.

Note that the searches in the above example use wildcards, and case insensitivity - just in case filename case and extension length get modified!

Note also that the ALT=" and the closing " (the quotes being encoded as |S) are included in the search. This is to ensure only the leafnames in ALT text are modified, and not in any SRC attributes or links.

Content.NewLines

This process is used to change all the newlines in the HTML/text files into the format specified by the contents of the setting NewLines.Type

The setting can be:
"0" for
"1" for
"2" for
"3" for

So, for example:-

ChangeSetting NewLines.Type To "0"
RunProcess Content.NewLines

is all that is required to set all newlines to be linefeeds.

Content.TagCase

This is the process by which, as its name suggests, the case of all the html tags is changed. There are two relevant settings, as follows:

TagCase.Case should be set to either "u" (or "upper") or "l" (or "lower").
TagCase.Parameters should be set to either "y" (or "yes") or "n" ("no").

So, upper case tags and parameters would be done with:-

ChangeSetting TagCase.Case To "Upper"
ChangeSetting TagCase.Parameters To "Yes"
RunProcess Content.TagCase

Content.Concatenate

Whereas the search and replace process is more powerful when using the script facility, this process is an extra one, not accessible from the front end.

Content.Concatenate allows two files (or items of text) to be concatenated to the html files found in your paths - one at the start and one at the end. Thus, it can be used to add a standard 'header' and 'footer' to files - useful when converting files to HTML, for example. Additionally, to use to ensure the files/text haven't already been added, you can specify the number of characters which should be compared between the start (and end) of the file and the files/text to be added.

The four settings it uses are:-

Concatenate.PrefixFile, which should specify the location of the file to add at the start. If the contents of this setting don't point to a valid file, then it is treated as an explicit item of text to be prepended.
Concatenate.SuffixFile, which is the location of the file to add to the end. If the contents of this setting don't point to a valid file, then it is treated as an explicit item of text to be appended.
Concatenate.PrefixCheck, which should contain the number of characters to check at the start.
Concatenate.SuffixCheck, which should contain the number of characters to check at the end.

Example:-

ChangeSetting Concatenate.PrefixFile To "ADFS::foo.$.web.startfile"
ChangeSetting Concatenate.PrefixCheck To "6"
ChangeSetting Concatenate.SuffixFile To "ADFS::foo.$.web.endfile"
ChangeSetting Concatenate.SuffixCheck To "7"
RunProcess Content.Concatenate

In that example, if the first 6 characters of "startfile" are "<HTML>", then that file will be added to all the html files provided they don't already start with the 6 characters "<HTML>".

Similarly, if the last 7 of "endfile" are "</HTML>" then that file will be added to those which don't end with "</HTML>".

Files.NameCase

This is the process for changing the case of filenames. It uses one setting, Filename.Case, which should be set to "Upper", "Lower" or "Proper" (or 'U', 'L' or 'P'). For example:-

ChangeSetting Filename.Case To "Proper"
RunProcess Files.NameCase

Files.NameExtensions

This is the process used to change the extension length used in filenames between long, short and none. The setting Filename.ExtensionLength should contain either "Long", "Short" or "None" ("L", "S" or "N"). Example:-

ChangeSetting Filename.ExtensionLength To "None"
RunProcess Files.NameCase

The above script will strip the extensions from all the files in the path.

Files.TypeSet

This process is used to attempt to set the RISC OS filetypes of all the files in the selected directories, based on the file's extension. Other than the path setting, no others are used, so it is used as:

RunProcess Files.TypeSet

Files.TypeChange

This is another 'extra' process, only available via the script language. It's use is to seek out all files in the path of type 'x' and change their filetype to be 'y' - for example it could be used to change the filetype of all text files (&FFF) to be HTML files (&FAF), which you might wish to do as part of a conversion script.

The two settings used by this process are Filetype.ChangeFrom, which should be the filetype which will be looked for/changed, and FileType.ChangeTo, which is the filetype to change to.

For example:-

ChangeSetting Filetype.ChangeFrom To "Text"
ChangeSetting Filetype.ChangeTo To "HTML"
RunProcess Files.TypeChange

After running this script, all files whose type is 'Text' will be filetyped as "html".

Note that only the RISC OS filetype will be affected by this - the contents of the file will be unaffected, unless modified in other ways.

Files.NameChange

This is an extra process, only available via the script language, which can be used to change one or more characters within filenames. Being written for a specific purpose, unrelated to websites, etc, it is quite limited, but included in WebChange in case someone else finds it useful.

It uses two settings (along with the path) as follows:-

Filename.ChangeFrom should be set to the character(s) you wish to be changed if they appear in any filenames.
Filename.ChangeTo should be set to the character(s) you wish to change them to.

The simplest example, as demonstrated by the following script segment, changes any underscore characters in filenames into slash characters - old versions of SparkPlug would extract files using an underscore to delimit the extension, whereas the normal delimiter is the slash character. Therefore, this script could be used after extracting websites from zip files using such a version of SparkPlug, and would 'fix' the filenames for normal use...

ChangeSetting Filename.ChangeFrom To "_"
ChangeSetting Filename.ChangeTo To "/"
RunProcess Files.NameChange

Generate.FileList

This is the process which is used to generate a list of all the files in the site (or rather, the directories on the path). The resulting file is a HTML file containing the list in the form of a link for each file. The settings it uses are:-

Filelist.Output - this specifies the name and location of the file containing the list.
FileList.Template - this specifies the name and location of a HTML file to be used as a template for the list.
FileList.Prefix - this contains the string to be used as a prefix for the line containing each item listed. i.e. it might be some indentation, etc.
FileList.ExtensionLength - this should contain the type of extension to be used for each item listed. i.e. "Long", or "Short".

ChangeSetting FileList.Output To "ADFS::foo.$.web.misc.MyList"
ChangeSetting FileList.Template To "ADFS::foo.$.web.misc.MyListTemp"
ChangeSetting FileList.Prefix To "  <LI>"
ChangeSetting FileList.ExtensionLength To "Long"
RunProcess Generate.FileList

In this example, the file "MyListTemp", in the "misc" subdirectory of the "web" directory would be used as a template, and the output would be put in the same location, but with the name "MyList", each link would be prefixed with two spaces and a list item tag, and the extension lengths would be 4 or more characters, for those items with optional long extensions (html, jpeg, etc).

Generate.IndexList

This process is similar to the above, in that it generates a list of links, but this time the only files linked to are HTML files, and then only if they contain the tags being indexed on - the process can optionally index items in anchor tags, items listed in the meta keywords tag in the headers, or the between the opening and closing  comment tag.

Indexer.Output is the name/location where the result should be saved, and Indexer.Template points to the template file,
Indexer.Prefix is the prefix for each line of the list, and
Indexer.ExtensionLength contains the extension length to be used - all much the same as the "FileList" equivalents, above.
Indexer.MetaTags should contain either "yes" or "no" and determines whether the meta keywords tags are used as a source of index material.
Indexer.AnchorTags should contain either "yes" or "no" and determines if any anchor tags in the site should be indexed.
Indexer.IndexTags should contain either "yes" or "no" and determines if the special index tags should be looked for and indexed.

ChangeSetting Indexer.Output To "ADFS::foo.$.web.misc.MyIndex"
ChangeSetting Indexer.Template To "ADFS::foo.$.web.misc.MyListTemp"
ChangeSetting Indexer.Prefix To "  <LI>"
ChangeSetting Indexer.ExtensionLength To "Long"
ChangeSetting Indexer.IndexTags To "yes"
ChangeSetting Indexer.AnchorTags To "yes"
ChangeSetting Indexer.MetaTags To "no"
RunProcess Generate.IndexList

This example uses the same template, prefix and extension length as the FileList example, but saves the result in the same location with the name "MyIndex". Index tags and Anchor tags are indexed, but meta keywords tags are ignored.

Generate.ValidationFile

This process is used to generate a list of links to check all your html files with a validation engine, such as the one at http://validator.w3.org

The first two settings it uses are Validator.Output and Validator.ExtensionLength - the use of these two is the same as the equivalents used by Generate.FileList and Generate.IndexList; the location of the output file, and the extension length to be used. Additional settings are:

Validator.SiteURL, which should contain the URL or 'base' address of your uploaded website.

Validator.Prefix should contain the address of the validation engine and any parameters which need to be listed before the address of the page to be checked, up to and including specifying that what follows is the URL of the page to be checked.

Validator.Suffix should contain any further parameters which would follow the URL within the link.

ChangeSetting Validator.Output To "ADFS::vmh.$.sites.srs"
ChangeSetting Validator.ExtensionLength To "Long"
ChangeSetting Validator.SiteURL To "http://www.softrock.co.uk/"
ChangeSetting Validator.Prefix To "http://validator.w3.org/check?uri="
ChangeSetting Validator.Suffix To ""
RunProcess Generate.ValidationFile

The above example shows how I might use this to validate the Soft Rock Software site.

[Main Contents]

Other settings

There are five settings which are not mentioned in the above section, as follows:

Prompt.Response - this will normally contain either "yes" or "no", depending on which button was clicked in response to a user prompt.
- this will usually contain either "yes" or "no" depending on whether the relevant option is ticked in the main window.
Process.AltText - this will usually contain either "yes" or "no" depending on whether the relevant option is ticked in the main window.
Process.IncludeSizes - this will usually contain either "yes" or "no" depending on whether the relevant option is ticked in the main window.
Process.IncludeDates - this will usually contain either "yes" or "no" depending on whether the relevant option is ticked in the main window.
Process.IncludeFiles - this will usually contain either "yes" or "no" depending on whether the relevant option is ticked in the main window.

[Main Contents]

Conditions

There are only three conditions currently available in a WebChange script, to see if a setting is "set" (contains "yes") "unset" (contains "no") or is "null" (an empty string, containing not even any spaces).

You use the condition with an If command, followed by a pair of brackets containing the setting being checked. This should be followed by the word "Then", and then any other command.

For example:-

Prompt "Do you want a file list this time?"
If Set(Prompt.Response) Then RunProcess Generate.FileList

This will ask the user if a file list is required, and if the user clicks yes/okay, one is generated (other settings relevant to the process assumed).

Prompt "Do you want to leave the date inclusion until another time?"
If Unset(Prompt.Response) Then RunProcess Content.IncludeDates

This asks the user if he/she doesn't want to run the date inclusion process and if no is clicked (ie the user does want it run), the process is started.

ChangeSetting Prompt.Response To "Yes"
If Null(Replace.ChangeTo_1) Then Prompt "That'll delete stuff. Are you sure?"
If Set(Prompt.Response) Then RunProcess Content.Replace

Null is used here to check that the 'replace' string isn't null and, if it is, the user is warned that it'll mean deletion of any found text. If he/she confirms, the task is carried out.

Note that ChangeSetting is used to set Prompt.Response to "yes" - this ensures that if the replace string is not null (which means the user isn't prompted), the If Set() condition will be evaluated as true.

Main contents