Script files creation

- Constants
- Functions/Procedures
- Classes
- Script properties
- Debug tools

These script files are plain text files, so you can modify them with any text editor. But using Ant Movie Catalog's build-in editor allows to easily edit script header through the properties window.

The language used here is similar to Pascal and Delphi. If you never used Pascal but know another language (C, C++, PHP, Java or another), it will probably not be too difficult for you to learn it by studying existing scripts.

The script engine used here is the version 2 of Carlo Kok's Innerfuse Pascal Script.

Most of the basic functions are supported. There are also several functions and constants added for exchanging data with Ant Movie Catalog. This page describes them.

The script begins with a comment block, which is not visible when the script is opened with Ant Movie Catalog's editor. This block contains parameters that can be modified with the properties window.

Only scripts files that are in the "Scripts" folder will be displayed automatically in the list.

Constants

These constants are the identifiers of the fields, useful when you want to set or get the value of a movie field:

`fieldNumber
fieldChecked
fieldMedia
fieldMediaType
fieldSource
fieldDate
fieldBorrower
fieldRating
fieldOriginalTitle
fieldTranslatedTitle
fieldDirector
fieldProducer
fieldCountry
fieldCategory
fieldYear
fieldLength
fieldActors
fieldURL
fieldDescription
fieldComments
fieldVideoFormat
fieldVideoBitrate
fieldAudioFormat
fieldAudioBitrate
fieldResolution
fieldFrameRate
fieldLanguages
fieldSubtitles
fieldSize
fieldDisks`

Other constants:

`dirApp: string;` contains program's path
`dirScripts: string;` contains scripts' path

General Functions/Procedures

`function Input(caption, prompt: string; var value: string): Boolean;`
Displays an input box, allowing the user to enter a text. Returns True if user clicks OK, False if user clicks Cancel.

`function GetPage(address: string): string;`
Fetches an HTML page (or any other text file) using the GET method, and returns it as a string.

`function GetPage2(address: string; referer: string): string;`
Same as GetPage, but allows to specify a "referer" address (page that called the next one).

`function GetPage3(address: string; referer: string; cookies: string): string;`
Same as GetPage2, but allows to specify cookies as a string: 'uid=120; pwd=FHNHESW' for example.

`function PostPage(address: string; params: string): string;`
Fetches an HTML page (or any other text file) using the POST method, and returns it as a string. The parameters have to be encoded with the URLEncode function.

`function PostPage2(address: string; params: string; content: string; referer: string; forceHTTP11: Boolean; forceEncodeParams: Boolean): string;`
Same as PostPage, but allows to specify also the content-type (instead of 'application/x-www-form-urlencoded'), give a "referer" address, force the use of HTTP 1.1 (rather than 1.0) and ask to the function to encode the parameters itself.

`procedure GetPicture(address: string);`
Fetches a picture and assigns it to the current movie.

`procedure ImportPicture(filename: string;)`
Import a picture from specified file and assigns it to the current movie.

`procedure ExportPicture(dir: string; name: string)`
Export the picture of current movie in specified directory with specified name (without extension).

`procedure HTMLDecode(var Value: string);`
Decode HTML characters contained in the string "Value" (e.g. "&eacute;" -> "é").

`procedure HTMLRemoveTags(var Value: string);`
Delete HTML tags found in the string "Value".

`function URLEncode(source: string): string;
function URLDecode(source: string): string;`
Converts characters to URL parameters (e.g. " " -> "+") and the other way round.

`function GetField(field: Integer): string;`
Reads and returns the value of the specified field of the current movie.

`procedure SetField(field: Integer; value: string);`
Stores a value in the specified field of the current movie.

`function CanSetField(field: Integer): Boolean;`
Informs the script if the specified field is checked or not in the modifiables fields list. The script does not have to worry about that since a SetField will not do anything if the field is not checked, but this function allows to prevent for example to download an additionnal page in the case that some field does not have to by imported anyway.

`function GetCustomField(fieldTag: string): string;`
Reads and returns the value of the specified custom field of the current movie (fieldTag = Tag associed to the custom field).

`procedure SetCustomField(fieldTag: string; value: string);`
Stores a value in the specified custom field of the current movie.

`function CanSetCustomField(fieldTag: string): Boolean;`
Informs the script if the specified custom field exists and is checked or not in the modifiables fields list. The script does not have to worry about that since a SetCustomField will not do anything if the field does not exist or is not checked, but this function allows to prevent for example to download an additionnal page in the case that some field does not have to by imported anyway.

`function CustomFieldExists(fieldTag: string): Boolean;`
Informs the script if the specified custom field exists. The script does not have to worry about that since a SetCustomField will not do anything if the field does not exist, but this function allows to inform user that field does not exist.

`function CanSetPicture: Boolean;`
Similar to CanSetField, indicates if the script can get a picture.

`function GetOption(OptName: string): Integer;`
Returns the value that the use selected for the specified option. The options names and their values are defined in the properties window.

`function StringReplace(S, Old, New: string): string;`
Replaces Old by New into S, and returns the result (S is not modified). Use #13#10 (without quotes) if you want to replace the linebreaks.

`procedure Error;`
Stops the script at current line.

`procedure Sleep(ATime: Integer);`
Waits for the number of milliseconds specified in parameter (useful to avoid server connection errors in large imports).

`function CheckVersion(Major, Minor, Revision: Integer): Boolean;`
Returns True if the current version of the program is at least the version specified in the parameters.

`procedure Launch(command: string; parameters: string);`
Executes an external file. This can be a program, a file, or a web address. "parameters" can be an empty string: ''.

`function AnsiUpperCase(Value: string): string;`
Changes all the letters of a string to uppercase. *

`function AnsiLowerCase(Value: string): string;`
Changes all the letters of a string to lowercase. *

`function AnsiUpFirstLetter(Value: string): string;`
Changes the first letter of a string to uppercase. Other letters are unchanged. *

`function AnsiMixedCase(Value: string; Delimiters: string): string;`
Changes all the letters that follow a letter of "Delimiters" to uppercase (first letter is also changed). Other letters of the string are unchanged. *
The delimiter parameter is a string containing characters that must be followed by an uppercase letter, e.g.: ' -' will make "This Is A Sample-Text".

* Accentuated letters are also converted, using Windows' current locale settings.

`function UTF8Encode(Value: string): string;
function UTF8Decode(Value: string): string;`
Converts a standard string to UTF8 (unicode) and the other way round. The unicode is not really supported (using "string" rather than "WideString"), so the function will only keep the characters that are available in current charset.

`function AcceptLicense(LicenseVersion: Integer): Boolean;`
Displays in a window the contents of the "License" field of the script as defined in the properties window with "I agree" and "Cancel" buttons. When the use accepts the license, he does not have to accept it again until the license number given in parameter changes. This allows to show the window to all users when the license changes, but not annoy them at each execution of the script.

`procedure SetStatic(AName: string; AValue: string);
function GetStatic(AName: string): string;`
Allows to read/write a "permanent" variable : the value assigned to this virtual variable will be kept between each program execution, unlike a global variable that would be lost when the script execution on select movies is finished.

`procedure ShowMessage(message: string);`
"Neutral" window that simply displays the message.

`procedure ShowError(message: string);`
Error window ("x" icon on a red circle).

`procedure ShowInformation(message: string);`
Information window ("i" icon in a balloon).

`function ShowWarning(message: string): Boolean;`
Warning window ("!" icon on a yellow triangle), with "OK" (returns True) and "Cancel" (returns False) buttons.

`function ShowConfirmation(message: string): Boolean;`
Confirmation window ("?" icon in a balloon), with "Yes" (returs True) and "No" (returns False) buttons.

`function FileExists(FileName: string): Boolean;`
Returns True if the given file name exists.

`function DirectoryExists(DirName: string): Boolean;`
Returns True if the given folder name exists.

`function ExtractFileName(AFileName: string): string;`
Returns what follows the last "\" of the name.

`function ExtractFileExt(AFileName: string): string;`
Returns the last "." and what follows it.

`function ExtractFilePath(AFileName: string): string;`
Returns up to the last "\" of the name (included).

`function ChangeFileExt(AFileName: string; AExt: string): string;`
Returns the name with a new extension. The extension includes the dot so it can also be used to transform "File.abc" to "FileSomething.def" for example.

`function IncludeTrailingPathDelimiter(AFileName: string): string;`
Returns the path with a "\" added at the end if there wasn't one yet.

`function ExcludeTrailingPathDelimiter(AFileName: string): string;`
Returns the path removing the "\" at the end if there was one.

`function DeleteFile(AFileName: string): Boolean;`
Deletes the specified file.

`function CopyFile(ASourceFileName: string; ATargetFileName: string; SkipIfExists: Boolean): Boolean;`
Copy a file to a target file name. If last parameter is True it does not overwrite the target file if it already exists. The function returns True if the file was copied.

`function MoveFile(ASourceFileName: string; ATargetFileName: string): Boolean;`
Moves/renames a file to a target file name. The function returns True if the file was well changed.

`function ListDirectory(ADir: string; AMask: string): string;`
Returns the folder contents, with tab-separated colunns (name, size, datetime, "D" if directory). Lines are separated by linebreaks so it can be put in the ".Text" property of a TStringList.

PickTree functions

PickTree is the window displaying a Tree, typically to use to display a list of the available movie pages.

`procedure PickTreeClear;`
Clears the contents of the window - Call this before using the window since it is never cleared automatically.

`procedure PickTreeAdd(Caption, Address: string);`
Adds an item in the window. If Address is an empty string or if it the window is still empty, the item will be added as a root-level item. Else it will be added as a child item. The Address is the string returned by the window when the user selects an item.

`procedure PickTreeMoreLink(Address: string);`
Sets the address pointed by the button "Find more" on the PickTree window. This value is cleared by PickTreeClear, and the button is disabled if it is not initialized by PickTreeMoreLink.

`function PickTreeExec(var Address: string): Boolean;`
Shows the window. The Address parameter will contain the address string corresponding to the selected item. The function returns True if the user selected OK button, False if he selected the Cancel button.

PickList functions

PickList is the window displaying a simple List, typically to use to display a list of values available for one field (such as descriptions or comments). There is a large text area to display the currently selected item.

`procedure PickListClear;`
Clears the contents of the window - Call this before using the window since it is never cleared automatically.

`procedure PickListAdd(Text: string);`
Adds an item in the window.

`function PickListExec(WelcomeText: string; var Selected: string): Boolean;`
Shows the window. WelcomeText is the text displayed in the preview area when no item is selected. The Selected parameter will contain the selected item. The function returns True if the user selected OK button, False if he selected the Cancel button.

TStringList class

TStringList is a class that can be used to manage a list of strings. It can be useful to manage the webpages, sinces it allows to easily manage the lines separately.

Declaration: `aList: TStringList;`
Creation: `aList := TStringList.Create;`
Destruction: `aList.Free;`

The following methods and properties are available:
`procedure LoadFromFile(FileName: string);` loads a text file into the list
`procedure SaveToFile(FileName: string);` saves the contents to a text file
`function GetString(LineNr: string): string;` retrieves a line
`procedure SetString(LineNr: string);` sets a line
`function Count: string` Returns the number of lines of the list
`property Text: string;` Property allowing to get or set the whole list as just a simple string (used with function GetPage for example)

TJvSimpleXml and linked classes

This is a quite complete XML parser, allowing to handle XML documents easily. Not all its functionnalities are accessible through scripts, so the following list may be completed later when some features are added to the script engine.

The creation of the object is similar to the TStringList presented above.

It has the following methods and properties:
`procedure LoadFromString(Value: string);` loads an XML document from a string
`procedure LoadFromFile(FileName: string);` loads an XML document from a file
`procedure SaveToString: string;` stores the current XML document in a string
`procedure SaveToFile(FileName: string);` stores the current XML document in a file
`property Root: TJvSimpleXmlElemClassic;` items corresponding to the "root" node of the XML document

The various nodes of the document are TJvSimpleXmlElemClassic, based on TJvSimpleXmlElem. The latter has the following methods and properties:
`property Name: string;` node name: <name>
`property Value: string;` node value: <name>value</name>
`property Items: TJvSimpleXmlElems;` liste des sous-éléments du nœud
`property Properties: TJvSimpleXmlProps;` list of the properties (attributes) of the node: <name attr1="val1" attr2="val2">
`property Parent: TJvSimpleXmlElem` parent node
`function GetChildIndex(AChild: TJvSimpleXmlElem): Integer;` position in the list (Items) of the specified "child" node
`procedure Clear;` deletes all the items and properties of the node

The class TJvSimpleXmlElems has the following methods and properties:
`property Count: Integer` returns the number of items in the list
`function GetItem(Index: Integer): TJvSimpleXmlElem;` gives access to an item of the list by specifying its position
`function GetItemNamed(Name: string): TJvSimpleXmlElem;` gives access to an item of the list by specifying its name
`procedure Clear;` deletes all the items of the list
`procedure Delete(Index: Integer);` deletes the item at specified position
`procedure DeleteNamed(Name: string);` deletes the item that has the specified name
`function Add(Name: string): TJvSimpleXmlElemClassic;` creates and adds an item to the list

The attributes of each node are TJvSimpleXmlProp, that have the following properties:
`property Name: string;` name of the attribute
`property Value: string;` value of the attribute

These are stored and managed by the class TJvSimpleXmlProps, that has the following methods and properties:
`property Count: Integer;` returns the number of properties in the list
`function GetItem(Index: Integer): TJvSimpleXmlProp;` gives access to a property of the list by specifying its position
`function GetItemNamed(Name: string): TJvSimpleXmlProp;` gives access to a property of the list by specifying its name
`procedure Clear;` deletes all the properties of the list
`procedure Delete(Index: Integer);` deletes the property at specified position
`procedure DeleteNamed(Name: string);` deletes the property that has the specified name
`function Add(Name: string; Value: string): TJvSimpleXmlProp;` creates and adds a property to the list

Scripts properties

The title, the description and all other attributes/parameters of the scripts can be defined through this window. It is accessible by the "Properties" icon of the script editor.

The title of the script should be quite short; it is usually the name of the site from which the information are imported. The "Get info from web" field indicates if the script can be used to get information from Internet. Only the scripts that have this field set to "True" are visible when the script window is called through "Get information" -> "From Internet using a script". When the window is called through "Scripting" menu, all scripts are displayed.

For each option that you define, you have to define its available values (positive integer numbers, associated to a description).

Debug tools

The toolbar visible in the script editor has commands similar to those available in Delphi:

- Toggle breakpoint: places a breakpoint on the current line so the script execution is paused when executing this line. The line appears with a red background. You can also place a breakpoint by clicking in the left margin of the editor. Only the breakpoint placed on valid code lines are used. Unfortunately it is not possible to visually indicate what are invalid breakpoint like what Delphi does when executing the program. When the execution is paused, you can advance to the next like with the "Step over" button or continue the execution with the "Run" button.
- Clear breakpoints: deletes in one click all the breakpoints defined in the script.
- Step over: executes the current line (highlighted in blue) and goes to the next instruction.
- Run to cursor: executes the script until it reaches the current line (so it generates a "virtual" breakpoint).
- Evaluate variable: displays the contents of the variable that is at cursor position.
- Add variable watch: adds to the watch list the variable that is a cursor position. This allows to know at any time the contents of the variable.