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.
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.
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.
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"
ChangeSetting Filetype.ChangeFrom To Replace.ChangeFrom_1
These two run one of the various processes. 'processname' should be the name of the process as detailed later. For example:
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...
this adds "path" to the path/s list.
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.
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 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."
"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."
"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:
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.
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.
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:
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:
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.
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.
There are five settings which are not mentioned in the above section, as follows:
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.
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.