WebChange for RISC OS

from Soft Rock Software

User Guide



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:


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 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]


; (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.

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).

this halts execution, with a window informing the user.

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.


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

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."


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

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."


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:

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.


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


RunProcess Content.IncludeSizes


RunProcess Content.IncludeFiles


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.

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.


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.


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:

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

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


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:-


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>".


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


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.


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


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.


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:-

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


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:-

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).


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 <!-- Index --> comment tag.

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.


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:

[Main Contents]


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