Création de scripts

- Constantes
- Fonctions/Procédures
- Classes
- Propriétés des scripts
- Outils de débogage

Ces scripts sont de simples fichiers texte, donc vous pouvez les modifier avec n'importe quel éditeur texte. Mais l'utilisation de l'éditeur intégré à Ant Movie Catalog permet de facilement éditer l'en-tête du script via la fenêtre des propriétés.

Le langage utilisé ici un dérivé du Pascal et de Delphi. Si vous n'avez jamais utilisé de Pascal mais que vous connaissez un autre language (C, C++, PHP, Java ou autre), il ne sera probablement pas trop difficile pour vous de l'apprendre en observant les scripts existants.

Le moteur de script utilisé est Innerfuse Pascal Script de Carlo Kok's, dans sa version 2.

La plupart des fonctions de base sont supportées. Il y a également une série de fonctions et constantes destinées à l'échange de données avec Ant Movie Catalog. Cette page les décrit.

Le script commence par un bloc de commentaires, qui n'est pas visible lorsque le script est ouvert avec l'éditeur de Ant Movie Catalog. Ce bloc contient les différents paramètres modifiables via la fenêtre des propriétés.

Seuls les scripts placés dans le dossier "Scripts" seront affichés automatiquement dans la liste.

Constantes

Ces constantes sont les identifiants des champs, utiles lorsque vous voulez écrire ou lire la valeur d'un champ du film :

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

Autres constantes :

`dirApp: string;` contient le dossier du programme
`dirScripts: string;` contient le dossier dans lequel sont les scripts

Fonctions/Procédures générales

`function Input(caption, prompt: string; var value: string): Boolean;`
Affiche une fenêtre, permettant à l'utilisateur d'entrer un texte. Retourne True si l'utilisateur clique sur OK, False si l'utilisateur clique sur Cancel.

`function GetPage(address: string): string;`
Télécharge une page HTML (ou autre fichier texte) via la méthode GET et la retourne sous forme de chaîne.

`function GetPage2(address: string; referer: string): string;`
Idem que GetPage, mais permet de donner une adresse de "referer" (la page depuis laquelle on appelle la page suivante).

`function PostPage(address: string; params: string): string;`
Télécharge une page HTML (ou autre fichier texte) via la méthode POST et la retourne sous forme de chaîne. Les paramètres doivent être encodés par la fonction URLEncode.

`function PostPage2(address: string; params: string; content: string; referer: string; forceHTTP11: Boolean; forceEncodeParams: Boolean): string;`
Idem que PostPage, mais permet de spécifier en plus le content-type (au lieu de 'application/x-www-form-urlencoded'), donner une adresse de "referer", forcer l'utilisation de HTTP 1.1 (au lieu de 1.0) et demander à la fonction d'encoder elle-même les paramètres.

`procedure GetPicture(address: string);`
Télécharge une image et l'associe au film courant.

`procedure ImportPicture(filename: string;)`
Importer une image à partir du fichier spécifié et l'associer au film courant.

`procedure ExportPicture(dir: string; name: string)`
Exporter l'image du film courant dans le répertoire spécifié avec le nom spécifié (sans extension).

`procedure HTMLDecode(var Value: string);`
Décode les caractères HTMLc ontenus dans la chaîne "Value" (ex. "&eacute;" -> "é").

`function URLEncode(source: string): string;
function URLDecode(source: string): string;`
Convertit les caractères en paramètres d'URL (ex. " " -> "%20") et vice versa.

`function GetField(field: Integer): string;`
Lit et retourne la valeur du champ spécifié du film courant.

`procedure SetField(field: Integer; value: string);`
Stocke la valeur dans le champ spécifié du film courant.

`function CanSetField(field: Integer): Boolean;`
Permet au script de savoir si le champ spécifié est coché ou non dans la liste des champs modifiables. Le script n'a normalement pas à s'en soucier car un SetField d'un champ sera inactif si le champ n'est pas coché, mais cette fonction permet d'éviter par exemple de télécharger une page supplémentaire dans le cas où un certain champ ne doit de toute façon par être récupéré.

`function GetCustomField(fieldTag: string): string;`
Lit et retourne la valeur du champ personnalisé spécifié du film courant (fieldTag = Tag associé au champ personnalisé).

`procedure SetCustomField(fieldTag: string; value: string);`
Stocke la valeur dans le champ personnalisé spécifié du film courant.

`function CanSetCustomField(fieldTag: string): Boolean;`
Permet au script de savoir si le champ personnalisé spécifié existe et est coché ou non dans la liste des champs modifiables. Le script n'a normalement pas à s'en soucier car un SetCustomField d'un champ sera inactif si le champ n'existe pas ou n'est pas coché, mais cette fonction permet d'éviter par exemple de télécharger une page supplémentaire dans le cas où un certain champ ne doit de toute façon par être récupéré.

`function CustomFieldExists(fieldTag: string): Boolean;`
Permet au script de savoir si le champ personnalisé spécifié existe. Le script n'a normalement pas à s'en soucier car un SetCustomField d'un champ sera inactif si le champ n'existe pas, mais cette fonction permet d'avertir l'utilisateur qu'un champs n'existe pas.

`function CanSetPicture: Boolean;`
Similairement à CanSetField, indique si le script peut récupérer une image.

`function GetOption(OptName: string): Integer;`
Retourne la valeur que l'utilisateur a choisi pour l'option spécifiée. Les noms d'options et leurs valeurs possibles sont définis dans la fenêtre des propriétés.

`function StringReplace(S, Old, New: string): string;`
Remplace Old par New dans S, et retourne le résultat (S n'est pas modifié). Utilisez #13#10 (sans guillemets) pour remplacer les retour de ligne.

`procedure Error;`
Interrompt l'exécution du script.

`procedure Sleep(ATime: Integer);`
Attend pendant le nombre spécifié de millisecondes (utile pour éviter les erreurs de connexion au serveur lors des importation en masse).

`function CheckVersion(Major, Minor, Revision: Integer): Boolean;`
Renvoie True si la version courante du programme est égale au supérieure à la version spécifiée dans les paramètres.

`procedure Launch(command: string; parameters: string);`
Lance un fichier externe, pouvant être un programme, un fichier, ou une adresse web. La valeur de "parameters" peut être une chaîne vide : ''.

`function AnsiUpperCase(Value: string): string;`
Convertit toutes les lettres de la chaîne en majuscule. *

`function AnsiLowerCase(Value: string): string;`
Convertit toutes les lettres de la chaîne en minuscule. *

`function AnsiUpFirstLetter(Value: string): string;`
Convertit la première lettre de la chaîne en majuscule. Les autres restent inchangées. *

`function AnsiMixedCase(Value: string; Delimiters: string): string;`
Convertit toutes les lettres suivant une lettre de "Delimiters" en majuscule (la première lettre est aussi convertie). Les autres lettres restent inchangées. *
Le paramètre "Delimiter" est une chaîne contenant les caractères devant être suivi d'une majuscule, ex : `' -'` créera "This Is A Sample-Text".

* Les lettres accentuées sont aussi converties, selon les paramètres régionnaux définis dans Windows.

`function UTF8Encode(Value: string): string;
function UTF8Decode(Value: string): string;`
Convertit une chaîne classique en UTF8 (unicode) et vice versa. L'unicode n'était pas réellement supporté (utilisation de "string" et non "WideString"), seuls les caractères disponibles dans le jeu de caractère courant seront conservés.

`function AcceptLicense(LicenseVersion: Integer): Boolean;`
Affiche dans une fenêtre le contenu du champ "Licence" du script tel que défini dans la fenêtre des propriétés avec des boutons "J'accepte" et "Annuler". Lorsque l'utilisateur a accepté la licence, il ne doit plus la réaccepter jusqu'à ce que le numéro de licence passé en paramètre change. Cela permet de réafficher la fenêtre chez tous les utilisateurs lorsque la licence est modifiée, tout en ne les ennuyant pas à chaque exécution du script.

`procedure SetStatic(AName: string; AValue: string);
function GetStatic(AName: string): string;`
Permet de lire/écrire une variable "permanente" : la valeur assignée à cette variable virtuelle sera conservée à travers les différentes exécutions du programme, contrairement à une variable globale dont la valeur est perdue lorsque l'exécution du script sur les films sélectionnés est terminée.

`procedure ShowMessage(message: string);`
Fenêtre "neutre" affichant simplement le message.

`procedure ShowError(message: string);`
Fenêtre d'erreur (icône de "x" sur un cercle rouge).

`procedure ShowInformation(message: string);`
Fenêtre d'information (icône de "i" dans une bulle).

`function ShowWarning(message: string): Boolean;`
Fenêtre d'avertissement (icône de "!" sur un triangle jaune), avec boutons OK (retourne True) et Annuler (retourne False).

`function ShowConfirmation(message: string): Boolean;`
Fenêtre de confirmation (icône de "?" dans une bulle), avec boutons Oui (retourne True) et Non (retourne False).

`function FileExists(FileName: string): Boolean;`
Renvoie True si le nom de fichier donnée existe.

`function DirectoryExists(DirName: string): Boolean;`
Renvoie True si le nom de dossier donné existe.

`function ExtractFileName(AFileName: string): string;`
Renvoie ce qui suit le dernier "\" du nom.

`function ExtractFileExt(AFileName: string): string;`
Renvoie le dernier "." et ce qui suit.

`function ExtractFilePath(AFileName: string): string;`
Renvoie tout jusqu'au dernier "\" du nom (y compris).

`function ChangeFileExt(AFileName: string; AExt: string): string;`
Renvoie le nom avec une nouvelle extension. L'extension inclut le point, donc la fonction peut aussi être utilisée pour transformer "Fichier.abc" en "FichierQuelquechose.def" par exemple.

`function IncludeTrailingPathDelimiter(AFileName: string): string;`
Renvoie le chemin avec un "\" ajouté à la fin s'il n'y en avait pas encore.

`function ExcludeTrailingPathDelimiter(AFileName: string): string;`
Renvoie le chemin en retirant le "\" à la fin s'il y en avait un.

`function DeleteFile(AFileName: string): Boolean;`
Supprime le fichier spécifié.

`function CopyFile(ASourceFileName: string; ATargetFileName: string; SkipIfExists: Boolean): Boolean;`
Copie un fichier vers un nom de fichier cible. Si le dernier paramètre est True le fichier cible n'est pas écrasé s'il existe déjà. La fonction renvoie True si le fichier a été copié.

`function MoveFile(ASourceFileName: string; ATargetFileName: string): Boolean;`
Déplace/renomme un fichier vers un nom de fichier cible. La fonction renvoie True si le fichier a été bien été changé.

`function ListDirectory(ADir: string; AMask: string): string;`
Renvoie le contenu du dossier, avec des colonnes séparées par des tabulations (nom, taille, date et heure, "D" si dossier). Les lignes sont séparées par des retours à la ligne et le contenu peut donc être mis dans la propriété ".Text" d'une TStringList.

Fonctions de la fenêtre "PickTree"

Cette fenêtre affiche une arborescence, typiquement pour afficher la liste des films trouvés sur le site.

`procedure PickTreeClear;`
Vide le contenu de la fenêtre - Applez cette fonction avant d'utiliser la fenêtre car elle n'est jamais vidée automatiquement.

`procedure PickTreeAdd(Caption, Address: string);`
Ajoute un nouvel élément a la fenêtre. Si l'adresse est une chaîne vide ou si la fenêtre est vide, l'élement est ajouté au niveau racine. Sinon il est ajouté en tant qu'élément "enfant". L'adresse est la chaîne retournée par la fenêtre lorsque l'utilisateur sélectionne l'élément.

`procedure PickTreeMoreLink(Address: string);`
Initialise l'adresse pointée par le bouton "Find More" de la fenêtre PickTree. Cette valeur est effacée par la fonction PickTreeClear, et le bouton est désactivé s'il n'est pas initialisé par PickTreeMoreLink.

`function PickTreeExec(var Address: string): Boolean;`
Affiche la fenêtre. Le paramètre Address contiendra l'adresse correspondant à l'élément sélectionné. La fonction renvoie True si l'utilisateur clique sur OK, False si l'utilisateur clique sur Cancel.

Fonctions de la fenêtre "PickList"

Cette fenêtre affiche une simple liste, typiquement pour afficher une liste de valeurs disponibles pour un champ (comme la description ou les commentaires). Il y a une grande zone de texte pour afficher l'élement sélectionné.

`procedure PickListClear;`
Vide le contenu de la fenêtre - Applez cette fonction avant d'utiliser la fenêtre car elle n'est jamais vidée automatiquement.

`procedure PickListAdd(Text: string);`
Ajoute un nouvel élément à la fenêtre.

`function PickListExec(WelcomeText: string; var Selected: string): Boolean;`
Affiche la fenêtre. Le paramètre WelcomeText est le texte affiché dans la zone du bas de la fenêtre lorsqu'aucun élément n'est sélectionné. Le paramètre Selected contiendra le texte de l'élément sélectionné. La fonction renvoie True si l'utilisateur clique sur OK, False si l'utilisateur clique sur Cancel.

Classe TStringList

TStringList est une classe qui peut être utilisée pour gérer une liste de chaînes. Elle peut être utile pour la gestion des pages web, étant donné qu'elle permet de facilement accéder aux lignes séparément.

Déclaration : `aList: TStringList;`
Création : `aList := TStringList.Create;`
Destruction : `aList.Free;`

Les méthodes et propriétés suivantes sont disponibles :
`procedure LoadFromFile(FileName: string);` charge un fichier texte dans la liste
`procedure SaveToFile(FileName: string);` sauve le contenu vers un fichier texte
`function GetString(LineNr: string): string;` lit une ligne
`procedure SetString(LineNr: string);` écrit une ligne
`function Count: string` retourne le nombre de lignes de la liste
`property Text: string;` permet de lire ou écrire la liste complète comme une simple chaîne (utilisé par lea fonction GetPage par exemple)

Classe TJvSimpleXml et classes liées

Il s'agit d'un parseur XML assez complet, permettant de manipuler des documents XML plus facilement. Toutes ses fonctionnalités ne sont pas accessibles via les scripts, il se peut donc que la liste suivante soit complétée lorsque certaines fonctionnalités soient rajoutées au moteur de script.

La création de l'objet se fait de manière similaire à la TStringList présentée ci-dessus.

Il possède les méthodes et propriétés suivantes :
`procedure LoadFromString(Value: string);` charge un document XML à partir d'une chaîne
`procedure LoadFromFile(FileName: string);` charge un document XML à partir d'un fichier
`procedure SaveToString: string;` stocke le document XML courant dans une chaîne
`procedure SaveToFile(FileName: string);` stocke le document XML courant dans un fichier
`property Root: TJvSimpleXmlElemClassic;` élément correspondant au nœud "racine" du document XML

Les différents nœuds du document sont des TJvSimpleXmlElemClassic, dérivant de TJvSimpleXmlElem. Ce dernier possède les méthodes et propriétés suivantes :
`property Name: string;` nom du nœud : <nom>
`property Value: string;` valeur du nœud : <nom>valeur</nom>
`property Items: TJvSimpleXmlElems;` liste des sous-éléments du nœud
`property Properties: TJvSimpleXmlProps;` liste des propriétés (attributs) du nœud : <nom attr1="val1" attr2="val2">
`property Parent: TJvSimpleXmlElem` nœud parent
`function GetChildIndex(AChild: TJvSimpleXmlElem): Integer;` position dans la liste (Items) du nœud "enfant" spécifié
`procedure Clear;` supprime tous les éléments et propriétés du nœud

La classe TJvSimpleXmlElems possède les méthodes et propriétés suivantes :
`property Count: Integer` retourne le nombre d'éléments de la liste
`function GetItem(Index: Integer): TJvSimpleXmlElem;` permet d'accéder à un élément de la liste en spécifiant sa position
`function GetItemNamed(Name: string): TJvSimpleXmlElem;` permet d'accéder à un élément de la liste en spécifiant son nom
`procedure Clear;` supprime tous les éléments de la liste
`procedure Delete(Index: Integer);` supprime l'élément à la position spécifiée
`procedure DeleteNamed(Name: string);` supprime l'élément ayant le nom spécifié
`function Add(Name: string): TJvSimpleXmlElemClassic;` crée et ajoute à la liste un élément

Les attributs de chaque nœud sont des TJvSimpleXmlProp, possédant les propriétés suivantes :
`property Name: string;` nom de l'attribut
`property Value: string;` valeur de l'attribut

Ceux-ci sont stockés et gérés par la classe TJvSimpleXmlProps, possédant les méthodes et propriétés suivantes :
`property Count: Integer;` retourne le nombre de propriétés de la liste
`function GetItem(Index: Integer): TJvSimpleXmlProp;` permet d'accéder à une propriété de la liste en spécifiant sa position
`function GetItemNamed(Name: string): TJvSimpleXmlProp;` permet d'accéder à une propriété de la liste en spécifiant son nom
`procedure Clear;` supprime toutes les propriétés de la liste
`procedure Delete(Index: Integer);` supprime la propriété à la position spécifiée
`procedure DeleteNamed(Name: string);` supprime la propriété ayant le nom spécifié
`function Add(Name: string; Value: string): TJvSimpleXmlProp;` crée et ajoute à la liste une propriété

Propriétés des scripts

Le titre, la description et tous les autres attributs/paramètres des scripts peuvent être définis via cette fenêtre. Elle est accessible par l'icône "Propriétés" de l'éditeur de scripts.

Le titre du script doit être relativement court ; il s'agit a priori du nom du site duquel les informations sont importées. Le champ "Infos d'Internet" indique si le script sert à importer des informations d'internet. Seuls les scripts ayant ce champ à "True" sont visibles lorsque la fenêtre de script est appelée via "Extraire des informations" -> "D'Internet via un script". Lorsque la fenêtre est appelée via le menu "Scripting" tous les scripts sont affichés.

Pour chaque option que vous définissez, vous devez définir ses différentes valeurs possibles (nombre entiers positifs, associés à une description).

Outils de débogage

La barre d'outils visible dans l'éditeur de script possède des commandes similaires à celles disponibles dans Delphi :

- Basculement de point d'arrêt : place un point d'arrêt sur la ligne en cours pour que l'exécution du script soit mise en pause avant exécution de cette ligne. La ligne apparaît avec un fond rouge. Vous pouvez également placer un point d'arrêt en cliquant dans la marge gauche de l'éditeur. Seuls les points d'arrêts placés sur des lignes de code valides seront utilisés. Il n'est malheureusement pas possible d'indiquer visuellement quels sont les point d'arrêts invalides comme le fait Delphi lors de l'exécution d'un programme. Lorsque l'exécution est en pause, vous pouvez avancer à l'instruction suivante manuellement via le bouton "Avancer" ou relancer l'exécution via le bouton "Exécuter".
- Supprimer les points d'arrêt : supprime en un coup tous les points d'arrêts définis dans le script.
- Avancer : exécute la ligne en cours (surlignée en bleu) et passe à l'instruction suivante.
- Exécuter jusqu'au curseur : exécute le script jusqu'à ce qu'il arrive à la ligne courante (génère donc un point d'arrêt "virtuel").
- Évaluer la variable : affiche le contenu de la variable qui est à la position du curseur.
- Ajouter un suivi de cette variable : rajoute à la liste de suivis la variable à la position du curseur. Cela permet de connaître à tout moment le contenu de la variable.