L'utilitaire PasRef
Cette annexe des scribes PASREF, explique un programme utilitaire MPW Shell que vous pouvez utiliser pour générer une table de références croisées de références de variables dans votre texte source.
Syntaxe
| PasRef [option ... ] [ sourceFile...] |
Lit les fichiers source Pascal et écrit une liste de la source suivie d'une liste de références croisées de tous les identificateurs. Chaque identificateur est classé par ordre alphabétique, suivi des numéros de ligne sur lesquels il apparaît. Les numéros de lignes peuvent faire référence à l'intégralité du fichier source ou peuvent être relatifs à des fichiers et à des unités d'inclusion individuels. Chaque référence indique si l'identificateur est défini, attribué ou simplement nommé (par exemple, utilisé dans une expression).
Les identificateurs peuvent comporter jusqu'à 63 caractères et sont affichés dans leur intégralité à moins qu'ils ne soient remplacés par la directive -x. Les identificateurs peuvent rester tels qu'ils apparaissent dans l'entrée, ou ils peuvent être convertis en minuscules (-1) ou en majuscules (-u). Pour les fichiers à inclure, les numéros de ligne sont relatifs au début du fichier à inclure ; un numéro de clef supplémentaire indique à quel fichier d'inclusion il est fait référence. Une liste de chaque fichier d'inclusion traité et son numéro de clef associé s'affiche avant la liste des références croisées.
Les déclarations USES peuvent également être traitées par PasRef (leurs directives de compilateur de nom de fichier USES associées sont traitées comme dans le compilateur Pascal). Ces déclarations sont traitées exactement comme des fichiers d'inclusion; et, comme avec le compilateur, seule la déclaration USES la plus externe est traitée (c'est-à-dire que la déclaration USES d'une unité utilisée n'est pas traitée).
Au lieu de traiter les déclarations USES, PasRef accepte plusieurs fichiers sources. Vous pouvez ainsi croiser un ensemble de programmes principaux ainsi que les unités qu'ils utilisent. Toutes les sources sont traitées comme des fichiers d'inclusion à des fins d'affichage. De plus, PasRef vérifie s'il a déjà traité un fichier (par exemple, s'il est apparu deux fois dans la liste d'entrée ou si l'un des fichiers l'a déjà utilisé ou inclus). S'il a déjà été traité, le fichier est ignoré.
Entrée
Si aucun nom de fichier n'est spécifié, l'entrée standard est traitée. À moins que l'option -d ne soit spécifiée, plusieurs fichiers sources sont référencés dans leur ensemble, produisant une seule liste de sources et une seule liste de références croisées. Spécifier l'option -d revient à exécuter PasRef individuellement pour chaque fichier.
Sortie
Toutes les listes sont écrites sur la sortie standard. Les caractères de saut de formulaire sont placés dans le fichier avant chaque nouvelle liste source et sa référence croisée associée. Les directives du compilateur Pascal $P (éjection de page) sont également traitées par PasRef, ce qui peut générer des sauts de formulaire supplémentaires dans la liste de sortie standard.
Diagnostique
Les erreurs de paramètres et les informations de progression sont écrites dans la sortie de diagnostic.
État
Les codes d'état suivants sont renvoyés au Shell :
| Valeur | Description |
|---|---|
| 0 | Terminaison normale |
| 1 | Erreur de paramètre ou d'option |
| 2 | Exécution terminée |
Options
| Paramètre | Description |
|---|---|
| -a | Traitez tous les fichiers même s'il s'agit de doublons de fichiers déjà traités. La valeur par défaut est de traiter chaque fichier (include) ou unité USES une seule fois. |
| -c | Ne traitez pas une unité si le nom de fichier de l'unité est spécifié dans la liste des fichiers à traiter sur la ligne de commande, ou si l'unité a déjà été traitée. |
| -d | Traitez chaque fichier spécifié sur la ligne de commande comme distinct. La valeur par défaut consiste à traiter la liste entière des fichiers dans son ensemble, produisant une seule liste de sources et une seule liste de références croisées. Cette option revient à exécuter PasRef individuellement pour chaque fichier spécifié. |
| -i pathname [, pathname... ] | Recherche les fichiers d'inclusions ou USES dans les répertoires spécifiés. Plusieurs options -i peuvent être spécifiées. Au maximum 15 répertoires seront recherchés. |
| -l | Afficher tous les identificateurs de la table de correspondance en minuscules. Cette option ne doit pas être utilisée si -u est spécifié, mais si c'est le cas, -u est ignoré. |
| -ni | -noincludes | Ne traitez pas les fichiers d'inclusion. La valeur par défaut consiste à traiter les fichiers d'inclusion. |
| -nl | -nolisting | N'affichez pas la source d'entrée pendant son traitement. La valeur par défaut est de lister l'entrée. |
| -nolex | N'affichez pas les informations lexicales sur la liste des sources. Voir l'exemple à la fin de cette annexe pour plus de détails. |
| -nt | -nototal | N'affichez pas le nombre total de lignes dans la liste source. Cette option est ignorée si aucun listing n'est généré (-nl). |
| -n[u] | -nouses | Ne traitez pas les déclarations USES. La valeur par défaut consiste à traiter les déclarations USES. Si -nu est spécifié, l'option -c est ignorée. |
| -o | Le fichier source est un programme Object Pascal. L'identificateur OBJECT est considéré comme un mot réservé pour permettre le traitement des déclarations Object Pascal. La valeur par défaut est de supposer que la source n'est pas un programme Object Pascal. |
| -p | Afficher les informations de version et de progression sur le fichier de diagnostic. |
| -s | N'affichez pas les informations d'inclusion et USES dans la liste ou les références croisées, et les références croisées par nombre total de numéros de ligne source plutôt que par numéro de ligne de fichier d'inclusion. |
| -t | Référence croisée par nombre total de lignes source plutôt que par numéro de ligne de fichier d'inclusion. Cette option peut être utilisée si vous ne souhaitez pas connaître les positions dans les fichiers inclus. Cependant, les informations d'inclusion sont toujours affichées (sauf si -s, -ni ou -nu est spécifié). Cette option est impliquée par l'option -s. |
| -u | Afficher tous les identificateurs de la table de correspondance en majuscules. Cette option ne doit pas être utilisée si -l est spécifié. |
| -w width | Définissez la largeur de sortie maximale de la liste de références croisées. Ce paramètre détermine le nombre de numéros de ligne affichés sur une ligne de la liste de références croisées. Cela n'affecte pas la liste des sources. La largeur peut être une valeur comprise entre 40 et 255; la valeur par défaut est 110. |
| -x width | Définissez la largeur d'affichage maximale des identifiants dans la liste de références croisées. (La valeur par défaut est de définir la largeur sur la taille du plus grand identifiant référencé.) Si un identifiant l'est également. long pour tenir dans la largeur spécifiée, il est indiqué en faisant précéder les quatre derniers caractères de points de suspension (...). La largeur peut être une valeur comprise entre 8 et 63. |
Normalement, les fichiers d'inclusion et les déclarations USES sont traités. L'option -noincludes supprime le traitement des fichiers d'inclusion. L'option -nouses supprime le traitement des déclarations USES.
L'omission de l'option -nouses oblige PasRef à traiter une déclaration USES exactement comme le fait le compilateur Pascal. Cependant, vous souhaiterez peut-être croiser un système entier, y compris toutes les unités de ce système. Le traitement des unités via la déclaration USES entraînerait le traitement de seule la section d'interface de chaque unité. Si l'option -nous es est utilisée, alors USES ne sera pas traité et chaque unité de la liste de paramètres peut être référencée, traitant la liste entière comme une source unique.
Le PasRef peut également croiser toutes les unités d'un programme tout en développant d'autres unités ne faisant pas directement partie de ce programme, telles que les unités Toolbox. Dans ce cas, l'option -c doit être utilisée. Avec l'option -c, si le nom de fichier ($u interface) est le même que l'un des noms de fichiers spécifiés dans la liste de paramètres, alors l'unité ne sera pas traitée à partir de la déclaration USES car sa source complète sera (ou a été) traité.
Pour résumer, vous avez les choix suivants :
- Ne pas traiter les USES et spécifié une liste de tous les fichiers que vous souhaitez traiter, en utilisant l'option -nouses.
- Traitez uniquement les sections d'interface via les déclarations USES (comme le Compilateur), en omettant l'option -nouses.
- Traitez certaines unités via USES et d'autres comme sources complètes, en spécifiant l'option -c.
Dans tous les cas où une liste de fichiers est spécifiée, aucune unité ne sera jamais traitée plus d'une fois (sauf si l'option -a est donnée).
Exemple
| PasRef -nu -w 80 Memory.p > Memory.p.Xref |
Faites une référence croisée avec l'exemple d'accessoire de bureau Memory.p et écrivez la sortie dans le fichier Memory.p.Xref. Aucun USES n'est traitée (-nu). Les listes de sources et de références croisées suivantes sont générées :
|
... 8 1 8 -- {$D+} { MacsBug symboles est activé ) 9 1 9 -- ($R-} { Pas de vérification d'intervalle } 10 1 10 -- 11 1 11 -- UNIT Memory; 12 1 12 -- 13 1 13 -- INTERFACE 14 1 14 -- 15 1 15 -- USES 16 1 16 -- MemTypes, QuickDraw, OSintf, Toolintf, Packintf; 17 1 17 -- 18 1 18 -- 19 1 19 -- FUNCTION DRVROpen(ctlPB:ParmBlkPtr;dCtl:DCtlPtr):OSErr; 20 1 20 -- FUNCTION DRVRControl(ctlPB:ParmBlkPtr;dCtl:DCtlPtr):OSErr; 21 1 21 -- FUNCTION DRVRStatus(ctlPB:ParmBlkPtr; dCtl:DCtlPtr):OSErr; 22 1 22 -- FUNCTION DRVRPrime(ctlPB:ParmBlkPtr;dCtl:DCtlPtr):OSErr; 23 1 23 -- FUNCTION DRVRClose(ctlPB:ParmBlklPtr;dCtl:DCtlPtr):OSErr; 24 1 24 -- 25 1 25 -- 26 1 26 -- IMPLEMENTATION ... 63 1 63 -- A FUNCTION DRVRClose(ctllPB:ParmBlklPtr;dCtl:DCtlPtr):OSErr; 64 1 64 0- A BEGIN 65 1 65 -- IF dCtlA.dCtlwindow <>NIL THEN 66 1 66 1- BEGIN 67 1 67 -- DisposeWindow(WindowlPtr(dCtlA.dCtlWindow)); 68 1 68 -- dCtlA.dCtlWindow:=NIL; 69 1 69 -1 END; 70 1 70 -- DRVRClose:=NOErr; 71 1 71 -0 END; ... 178 1 178 -- 179 1 179 -- END. {Fin d'unité memory } 180 1 180 -- |
Chaque ligne de la liste du source est précédée de cinq colonnes d'informations :
- Le nombre total de lignes.
- La clef d'inclusion attribuée par PasRef pour un fichier d'inclusion ou USES (voir ci-dessous).
- Le numéro de ligne dans le fichier d'inclusion ou principal.
- Deux indicateurs (gauche et droite) reflétant le niveau d'imbrication des blocs statiques. L'indicateur de gauche est incrémenté (mod 10) et affiché chaque fois qu'un BEGIN, REPEAT ou CASE est rencontré. A la fin de ces structures avec une END ou UNTIL, l'indicateur de droite s'affiche, puis décrémenté. Il est ainsi facile de faire correspondre les instructions BEGIN, REPEAT et CASE avec leurs terminaisons correspondantes.
- Une lettre reflétant le niveau statique des procédures. Le caractère est mis à jour pour chaque niveau d'imbrication de la procédure (A pour le niveau 1, B pour le niveau 2,...), et affiché sur la ligne contenant l'entête ainsi que sur les BEGIN et END associés au corps de la procédure. À l'aide de cette colonne, vous pouvez facilement trouver le corps d'une procédure pour un entête de procédure lorsqu'il existe des procédures imbriquées déclarées entre l'entête et son corps.
La liste des références croisées suit :
|
1. Memory.p -A- accEvent 144 ( 1) accRun 158 ( 1) ApplicZone 121 ( 1) Away 33*( 1) 146 ( 1) -B- BeginUpdate 151 ( 1) BNOT 39 ( 1) 117 ( 1) Bold 90 ( 1) Boolean 31*( 1) BOR 39 ( 1) BSL 39 ( 1) -C- csCode 143 ( 1) CSParam 146 ( 1) ctlPB 19*( 1) 20*( 1) 21*( 1) 22*( 1) 23*( 1) 43*( 1) 63*( 1) 74*( 1) 143 ( 1) 146 ( 1) 168*( 1) 173*( 1) -D- dCtl 19*( 1) 20*( 1) 21* ( 1) 22* ( 1) 23*( 1) 37* ( 1) 39 ( 1) 43*( 1) 50 ( 1) 53 ( 1) 54 ( 1) 55 ( 1) 63*( 1) 65 ( 1) 67 ( 1) 68 ( 1) 74*( 1) 115 ( 1) 142 ( 1)168*( 1) 173*( 1) DCtlPtr 19 ( 1) 20 ( 1) 21 ( 1) 22 (1) 23 (1) 37 ( 1) 43 ( 1) 63 ( 1) 74 ( 1) 168 (1) 173 (1) dCtlRefNum 39 ( 1) 54 ( 1) dCtlWindow 50 ( 1) 55=( 1) 67 ( 1) 68= ( 1) 142 (1) ... -V- VolName 79* ( 1) 100 ( 1) 135 (1) -W- what 149 ( 1) WindowKind 54=( 1) windowpeek 54 ( 1) WindowPtr 48 ( 1) 67 ( 1) 151 ( 1) 153 ( 1) wRect 47*( 1) *** End PasRef: 105 id's 249 references |
Les nombres entre parenthèses suivant les numéros de ligne sont les clefs d'inclusion des fichiers d'inclusion associés (affichés dans la colonne 2 de la liste des sources). Les noms des fichiers inclus sont affichés après la liste des sources. Ainsi, vous pouvez voir quel numéro de ligne se trouvait dans quel fichier d'inclusion. Un astérisque (*) après un numéro de ligne indique une définition de la variable. Un signe égal (=) indique une affectation. Un numéro de ligne suivi de rien signifie une référence à l'identificateur.
Limitations
PasRef ne traite pas les directives de compilation conditionnelle ! Ainsi, étant donné la «bonne» combinaison de $IFcs et $ELSECS, les informations lexicales (imbrications) de PasRers peuvent être perdues. Si cela se produit ou si vous ne souhaitez tout simplement pas les informations lexicales, vous pouvez spécifier l'option -nolex.
PasRef entrepose toutes ses informations sur la mémoire de tas Pascal. Jusqu'à 5 000 identificateurs peuvent être gérés, mais plus d'identificateurs signifiera moins d'espace de références croisées. Un message est émis si PasRef manque d'espace sur la mémoire de tas.
Remarque : Bien que PasRef ne manque jamais une référence, il peut rarement être trompé en pensant qu'une variable est définie alors qu'elle ne l'est pas en réalité. Cela se produit notamment dans les variantes de structure d'enregistrement. La balise case de la variante d'enregistrement est toujours signalée comme une définition (même s'il n'y a pas de type de balise), et les constantes d'étiquette case de la variante (si elles sont des identifiants) sont également parfois signalées de manière incorrecte en fonction du contexte. (Cela se produit uniquement dans les parties de déclaration du programme.)
Bien que PasRef prenne en charge la fonction $$Shell de Pascal dans les fichiers d'inclusion et les déclarations USES, le traitement des fichiers MPW {Pinterfaces} n'est pas entièrement pris en charge car ces fichiers incluent des fichiers de manière conditionnelle (rappelez-vous que les conditions ne sont pas traitées). Pour cette raison, utilisez toujours l'option -nu pour supprimer le traitement des déclarations USES.
Les identificateurs Cycle et Leave sont traités comme des mots-clefs Pascal réservés par PasRef. Celles-ci sont traitées comme deux instructions de contrôle de boucle par Pascal, sauf si elles sont explicitement déclarées.