Personal Agent 1.0 (C) Copyright 1992 V. Gervasi - ICARUS Presentazione --------------- Personal Agent è un programma pensato per facilitare la manipolazione di files tramite le icone del Workbench. Usando questo programma, vi sarà facile vedere immagini grafiche, ascoltare brani musicali, scompattare archivi di vario tipo, leggere manuali ed altra documentazione, e compiere molte di quelle operazioni che, normalmente, sarebbero soltanto accessibili dal CLI. Basterà infatti trascinare delle icone del Workbench sull'icona di Personal Agent perché il programma riconosca automaticamente il tipo di file associato e compia le azioni opportune.   Il programma è completamente configurabile, grazie anche ad un semplice linguaggio di programmazione interno, di uso intuitivo, e ad una interfaccia grafica che si adatta alle preferenze dell'utente.   Per facilitare l'uso da parte di utente inesperti, il programma viene fornito con alcune configurazioni standard già preparate, capaci di riconoscere molti tipi di files, e con un discreto numero di icone (che appaiono sullo schermo del Workbench) fra cui l'utente può scegliere la preferita.   In questo manuale, verranno dapprima illustrate le modalità di funzionamento basilari del programma, dall'installazione all'uso con la configurazione standard. In seguito vengono esaminate le possibilità di configurazione e, per ultimo, viene illustrato il FAM, il linguaggio di programmazione interno, e il relativo compilatore. Installazione e uso ---------------------   Se avete eseguito la procedura di installazione standard, che richiede semplicemente un doppio click sull'icona "Install", e avete scelto di eseguire Personal Agent alla partenza del sistema (come consigliato), non dovete fare nient'altro.   Se invece avete scelto di NON eseguire Personal Agent alla partenza del sistema, dovrete eseguirlo manualmente: Personal Agent può essere attivato sia dal Workbench, sia dal CLI. Nel primo caso, basta un doppio click sull'icona del programma, nel secondo occorre invece digitare il nome del programma, preferibilmente preceduto dal comando "run" per richiedere una esecuzione "in background", cioè concorrente. Un esempio di questa seconda modalità è run >NIL:   Questo parametro consente di scegliere quale icona deve apparire sullo schermo del Workbench a rappresentare il programma. Il che inserite deve essere il nome di un file, eventualmente preceduto da un percorso (path) relativo alla directory in cui si trova Agent (in genere quella di installazione), la cui icona viene presa in prestito da Personal Agent. Se questo parametro non viene specificato, Personal Agent userà la propria icona (quella del file "Agent"). NAME=   Con questo parametro potete stabilire sotto quale nome l'icona scelta precedentemente appare sullo schermo del Workbench. Questo può essere un nome qualsiasi, ma è preferibile che non sia troppo lungo. Se il parametro non viene specificato, Personal Agent usa il proprio nome ("Agent"). OUTPUT=   Tramite il parametro OUTPUT potete scegliere dove verranno inviati i messaggi prodotti dai programmi che Personal Agent esegue per trattare i files che gli vengono indicati. Usualmente, vorrete che questi messaggi vengano visualizzati sullo schermo, e quindi si userà un indirizzato a CON: (che è anche la destinazione standard, usata se questa voce non viene specificata). È anche consigliabile specificare gli attributi di console /AUTO e /WAIT, che consentono di chiudere la finestra aperta se i messaggi non sono di interesse, e di non aprirla affatto nel caso non vi siano messaggi da visualizzare. La sintassi di CON: è CON://// per esempio, OUTPUT=CON:0/15/600/120/Agent/AUTO/WAIT vuol dire che i messaggi verranno visualizzati in una finestra il cui angolo superiore sinistro si troverà alla posizione (0,15) dello schermo, larga 600 pixel e alta 120, il cui titolo sarà "Agent". Inoltre, la finestra si aprirà soltanto se vi saranno effettivamente dei messaggi da visualizzare, ed anche dopo che il programma sarà terminato, attenderà la conferma dell'utente (con un click sul pulsante di chiusura) prima di chiudersi. Potete trovare informazioni più dettagliate su CON: sul manuale "Using The System Software", fornito con l'Amiga o con l'aggiornamento del sistema operativo.   Se contiene la sequenza di caratteri "%s", essa verrà sostituita con il nome del comando che Personal Agent esegue per la visualizzazione (completo di eventuali parametri). CLASSES=   Questo parametro consente di indicare quale file contiene il testo sorgente del programma FAM che definisce i formati dei files (classi) e le azioni da intraprendere per trattarli. Vedete più oltre per il formato di tale file. Se il parametro non è presente, viene usato il file "classes". XPOS= YPOS=   Con questi parametri potete scegliere in quale posizione dello schermo apparirà l'icona di Personal Agent; le posizioni specificate devono essere in pixel (punti di schermo), la posizione (0,0) è l'angolo in alto a sinistra dello schermo. Se questi parametri non vengono specificati, l'icona verrà posizionata sullo schermo in maniera tale da non interferire con altre icone già presenti. Potete ottenere lo stesso effetto dando il valore "-1" per una o entrambe le coordinate; il sistema sceglierà una posizione libera opportuna. WAIT=   Infine, questo parametro permette di decidere per quanto tempo i messaggi di Personal Agent devono rimanere sullo schermo. Il tempo standard è di 7 secondi. Notate comunque che tutti i messaggi di Personal Agent scompaiono non appena viene premuto un tasto, o viene premuto il pulsante del mouse all'interno del quadro che mostra il messaggio. Per mantenere il messaggio a tempo indeterminato, basta clickare con il mouse FUORI dal quadro che contiente il testo; in tal caso il conteggio del tempo viene sospeso. Il linguaggio FAM -------------------   FAM sta per File Analisys Machine (macchina per l'analisi dei file), e questo nome sintetizza bene gli scopi e i limiti del FAM. Se avete installato gli esempi, potete vedere alcuni esempi di programmazione in FAM nei files "view_classes" e "unpack_classes". I file "view_classes.sys" e "unpack_classes.sys" non sono invece leggibili; essi contengono le versioni compilate dei due files precedenti.   Il FAM è un linguaggio molto specializzato, con soltanto pochi comandi orientati alla descrizione di formati di files e alla descrizione di azioni da intraprendere per la visualizzazione (o altra attività) dei files stessi.   Il formato di un file sorgente FAM è il cosiddetto "free form", cioè "formato libero". Infatti la dislocazione dei comandi è del tutto ininfluente: spazi, tabulazioni e a-capo non cambiano il significato del programma. Inoltre, il FAM è stato pensato per facilitare la documentazione dei programmi scritti con esso; per tale motivo, i commenti possono apparire quasi in qualunque posto nel sorgente, e non necessitano di caratteri di delimitazione particolari.   In effetti, le uniche parti del file sorgente analizzate dal compilatore sono quelle comprese tra i delimitatori "CLASS"-"END" e "ACTION"-"END"; fra questi delimitatori (in maiuscolo) i commenti non sono permessi. Tutti gli altri elementi del linguaggio sono insensibili al maiuscolo/minuscolo.   Ignorando dunque i commenti, i sorgenti FAM sono composti da due tipi di comandi, usualmente (ma non obbligatoriamente) raccolti in due sezioni distinte: Definizioni di Classi e Definizioni di Azioni.   Le definizioni di classi servono a Personal Agent per riconoscere il tipo del files con cui ha a che fare; le definizioni di azioni servono invece ad indicare cosa fare con tali files.   Le definizioni di classi consentono di definire "classi" di files, specificando quale formato i files devono avere per appartenere alla classe; la specifica del formato può essere fatta in base al nome e/o in base al contenuto del file. La sintassi informale di una definizione di classe è CLASS HAS END   Il è il nome (unico) che viene dato alla classe; questo nome verrà usato in seguito per stabilire quali azioni vanno compiute per operare sui files di questa classe. La è composta, a sua volta, di due tipi di elementi: specifiche sul nome e specifiche sul contenuto. La specifica sul nome ha questa forma: NAME dove il è una stringa che può contenere i caratteri jolly (pattern) dell'AmigaDOS: # ? ~ ( | ) % [ ]. Potete consultare il vostro manuale sull'AmigaDOS per il significato di questi caratteri. La specifica sul contenuto ha invece la forma AT dove è una sequenza di byte, espressa in vari modi, e è una posizione all'interno del file, espressa in byte dall'inizio del file. La può contenere: numeri decimali: 123 numeri ottali: 033 numeri esadecimali: $AB o 0xC0 numeri binari: %01100110 stringhe: "FORM" (questa stringa specifica 4 bytes)   Questi componenti possono essere specificati in qualunque ordine, fino ad indicare stringhe lunghe al massimo 256 bytes. Questa non è una grossa limitazione; se ad esempio si vogliono riconoscere 300 bytes all'inizio di un file, si scriverà ... HAS AT 0 AND AT 250 ...   Le varie specifiche, possono poi essere connesse tramite AND e OR per specificare condizioni complesse; l'AND ha la precedenza sull'OR. È possibile definire diverse volte la stessa classe, in tal caso ogni singola definizione viene posta in OR con le precedenti. Il momento è adatto ad alcuni esempi:   - Un file IFF ILBM, lo standard per le immagini grafiche, ha la caratteristica di contenere la stringa "FORM" nei primi quattro bytes, la lunghezza dei dati nei successivi quattro e la stringa "ILBM" dall'ottavo al dodicesimo, seguiti da altri dati. Una specifica per tale classe potrebbe allora essere CLASS ILBM has "FORM" at 0 AND "ILBM" at 8 END   - Un file eseguibile, sull'Amiga, inizia con la sequenza esadecimale 000003F3. Ciò può essere specificato con CLASS Exe has $00 $00 $03 $F3 at 0 END o anche con CLASS Exe has 0 0 0x03 0xf3 at 0 END oppure con CLASS Exe has 0 0 3 243 at 0 END eccetera.   - Il popolare compattatore lharc, e il consimile LZ, producono archivi contenenti una serie di files compattati, consentendo un notevole risparmio di spazio. I nomi di questi archivi usualmente terminano per ".lzh" o ".lha", ma questo non è obbligatorio. In ogni caso, però essi contengono alla posizione 2 il tipo di compattazione del primo file, che è una stringa del tipo "-lh?-", in cui il "?" indica il tipo di compattazione usato (in genere 0, 1 o 5). Scriviamo allora la specifica per i file di questo tipo: CLASS LZH has NAME #?.lzh OR NAME #?.lha OR "-lh" at 2 AND "-" at 6 END Potremmo anche scrivere CLASS LZH has NAME #?.lzh OR NAME #?.lha OR "-lh0-" at 2 OR "-lh1-" at 2 OR "-lh5-" at 2 END   Notate come il formato in cui scriviamo le specifiche è del tutto libero, e dettato in questo caso solo da considerazioni estetiche e di chiarezza.   Veniamo ora alle definizioni di azioni. Il loro formato è ACTION VIEW IS END   In questo caso, è (ovviamente) il nome della classe, lo stesso usato (o che si userà: l'ordine è ininfluente) nella definizione della classe, mentre è un comando AmigaDOS che verrà eseguito quando Personal Agent verrà chiamato ad operare sui files di quella classe.   In , ogni occorrenza della stringa "%s" verrà sostituita con il nome del file in esame. Il comando AmigaDOS verrà eseguito nella directory contenente tale file.   A questo proposito è bene spendere qualche parola. Normalmente, i comandi AmigaDOS vengono eseguiti da una Shell (o CLI), e possono quindi contare sull'esistenza di un "path", ovvero di una lista di posti (directory) in cui cercare il comando da eseguire senza che sia necessario indicare esplicitamente dove trovare il comando stesso. Lo stesso vale per Personal Agent SE il programma è stato eseguito da CLI (o una qualunque Shell, come AmigaShell); in caso contrario (esecuzione da Workbench), Personal Agent non può contare sul path e quindi sarà necessario nelle indicare esplicitamente dove reperire il comando da eseguire. È possibile che questo comportamente venga corretto in una prossima versione del programma, o del Sistema Operativo. Vediamo qualche esempio:   - Vogliamo che, quando viene fornito a Personal Agent un archivio di classe LZH (come definita in precedenza), esso mostri la lista dei files contenuti nell'archivio stesso: ACTION VIEW LZH is lz v "%s" END   In questo caso, usiamo il comando LZ con l'opzione v (che mostra l'elenco dei files compresi nell'archivio); al %s verrà sostituito il nome del file da analizzare. Abbiamo inserito il %s fra virgolette: questa è una buona norma generale, per evitare che eventuali spazi presenti nel nome del file confondano LZ.   - Vogliamo che, quando viene analizzato un file ILBM, venga lanciato un editor grafico (poniamo si chiami SuperPaint), pronto a lavorare sul file passato. ACTION VIEW ILBM is Work:usr/appl/SP/SuperPaint "%s" END   In questo caso abbiamo indicato il percorso completo per arrivare a SuperPaint: ciò può essere necessario se il nostro path abituale non contiente "Work:usr/appl/SP" o se prevediamo che Personal Agent venga lanciato da Workbench (che, allo stato attuale, non fornisce il path).   - Immaginiamo che, per "vedere" un file di archivio, intendiamo scompattarlo. Una definizione adeguata per il compattatore LhArc sarebbe ACTION VIEW LZH is lharc -a -x x "%s" #? RAM: END   Il "VIEW" (vedi) che compare nella sintassi delle istruzioni è lì per permettere una futura estensione, in cui sia possibile indicare diversi tipi di azione per ogni classe di file. In tal caso potremmo avere ACTION VIEW per visualizzare il file, ACTION RUN per eseguirlo, ACTION UNPACK per scompattarlo, ACTION HEAR per ascoltarlo, ACTION INFO per avere delle informazioni... L'utente sarebbe comunque libero di definire i suoi tipi di azione; una apposita interfaccia grafica consentirebbe di selezionare l'azione che si intende svolgere fra quelle possibili su quel tipo di file. Tutto ciò è però rimandato alla prossima versione...   È da notare che le vengono eseguite in maniera ASINCRONA; in altre parole, Personal Agent non attende il completamento del comando, ma è subito pronto ad accettare ulteriori manipolazioni. Questo fatto può essere di una certa importanza quando si rilascia sull'icona di Personal Agent non una sola icona del Workbench, ma un'intera lista (ottenuta con shift-click o con il rettangolo di selezione del Workbench): in tali casi, vengono eseguiti quasi contemporaneamente tutti i comandi relativi ai file selezionati.   Veniamo adesso al processo di compilazione.   Per effettuare modifiche ai programmi FAM, o per scriverne di nuovi, dovrete usare un editor, come ED o MicroEmacs (che fanno parte del software di sistema dell'Amiga) e salvare il testo prodotto nel file indicato dal parametro CLASSES=... nell'icona di Agent. Quando Personal Agent viene eseguito, determina automaticamente (basandosi sulle date fornite dal sistema) se è necessario ricompilare il sorgente FAM, cioè se il sorgente porta una data posteriore al file compilato (file .sys), o se quest'ultimo non esiste affatto. Se è necessaria una compilazione, essa viene effettuata silenziosamente, lasciando il risultato in un file che porta lo stesso nome del sorgente, con suffisso ".sys", e che viene memorizzato nella stessa directory del file sorgente FAM. Naturalmente, possono verificarsi degli errori nella compilazione (errori di sintassi, troppe definizioni, esaurimento della memoria...); in tali casi, un messaggio di avvertimento informerà l'utente dell'accaduto. Quando tutto va bene, il processo di compilazione è invece del tutto trasparente, a parte un breve ritardo alla partenza del programma.   Quando Personal Agent è chiamato ad analizzare un file, confronterà dapprima il nome del file con tutte le specifiche ".. HAS NAME xxxxx ..", nell'ordine in cui esse appaiono nel file sorgente. Soltanto se nessuna di esse coincide col nome del file sotto analisi si passa al confronto sul contenuto del file (che è un processo più lento); anche in questo caso, le specifiche vengono considerate nell'ordine in cui appaiono nel sorgente. È del tutto possibile che un file fallisca l'accoppiamento con una clausola, ma abbia successo con una successiva specifica relativa alla stessa classe: CLASS LZH has "-lh1-" at 2 END CLASS FOO has "Foo1" at 10 END CLASS LZH has "-lh5-" at 2 END   In questo caso, un file viene considerato di tipo LZH solo se ha "-lh1-" alla posizione 2, oppure se ha "-lh5-" alla stessa posizione MA non contiene "Foo1" alla posizione 10 (altrimenti verrebbe considerato di classe FOO).   Una volta determinata la classe a cui il file appartiene, vengono esaminate le azioni, nell'ordine in cui appaiono nel sorgente. Se non vi è alcuna "ACTION" relativa a quella classe, viene visualizzato un messaggio d'errore, altrimenti viene eseguito il comando AmigaDOS corrispondente.   Se invece il file non appartiene a nessuna classe fra quelle definite, viene eseguita l'azione indicata per la classe speciale "DEFAULT". Tutti i file che non fanno parte di nessun'altra classe vengono considerati di classe "DEFAULT". Di solito ACTION VIEW DEFAULT sarà qualcosa di molto generale (come un "more %s" o un "echo Non so che file sia %s !"), la scelta spetta comunque all'utente. Se neanche l'azione relativa a DEFAULT è definita, si ottiene un messaggio d'avvertimento. Nell'Appendice B è fornita la sintassi formale del FAM. Appendice A - Guida ai messaggi ---------------------------------   I messaggi relativi agli errori di compilazione sono tutti piuttosto autoesplicativi. Tali messaggi di errore possono apparire in tre passi di compilazione: compilazione NAME (per le clausole HAS NAME xxx), compilazione codici (per le clausole HAS xxx AT yyy) e compilazione ACTION (per ACTION xxx yyy IS zzz). In ogni caso, il messaggio stesso contiene un suggerimento per la correzione dell'errore, nonché la linea del sorgente FAM che ha causato l'errore.   Oltre agli errori di compilazione, possono verificarsi altre condizioni anomale, segnalate da appositi messaggi: "Errore nella compilazione del file FAM "xxx". Il File Oggetto FAM "xxx.sys" non è stato modificato"   Poiché si sono verificati degli errori di compilazione, non è stato possibile produrre un file oggetto; verrà usato (se disponibile) il file oggetto preesistente. "Non posso aprire il file FAM "xxx" ! Controlla la linea CLASSES=... nella mia icona." "Non posso leggere il file oggetto FAM "xxx.sys" ! Controlla la linea CLASSES=... nella mia icona."   Personal Agent non riesce a trovare il file indicato tramite il parametro CLASSES, né riesce a trovare il file di default "classes". Poiché non è possibile sapere quale file di definizioni usare, Personal Agent non potrà essere eseguito. "Non posso far partire la FAM."   Questo messaggio appare solitamente dopo altri messaggi, più specifici. Esso indica l'impossibilità di eseguire la parte di Personal Agent che si occupa del riconoscimento delle classi di files; Personal Agent non potrà essere eseguito. "Non posso aggiungere la mia icona allo schermo del Workbench !"   Il sistema non ha accettato la richiesta di Personal Agent di inserire la propria icona fra quelle visualizzate dal Workbench. Questo potrebbe accadere in condizioni di scarsa memoria, oppure perché il Workbench non è correntemente in esecuzione, o anche a causa di errori precedenti. "Non trovo la mia icona !"   Personal Agent non può accedere al file contenente la propria icona ("Agent.info"). Poiché in tale file sono memorizzati tutti i parametri che regolano il funzionamento di Personal Agent, il programma non potrà essere eseguito.   "Non posso creare la message port !"   Si tratta di una situazione anomala, che si verifica generalmente per scarsità di memoria. Personal Agent non verrà eseguito. "Non posso accedere a quest'oggetto (Forse non è un file ?)"   È stato chiesto a Personal Agent di esaminare un'icona che non corrisponde ad un file, come l'icona di un disco o di un cassetto, o anche quella di un'altro programma che, come Personal Agent, risiede sullo schermo del Workbench. "Non posso accedere a "xxx" !" "Non posso accedere a quest'oggetto !"   Per qualche motivo, Personal Agent non può accedere al file corrispondente all'icona fornitogli. Il file non potrà essere esaminato. "Non posso aprire "xxx" !" "Non posso aprire quest'oggetto !"   All'icona fornita corrisponde un file esistente, ma che non può essere aperto per la lettura. Il file non potrà essere esaminato. "Non posso eseguire "xxx", il sistema riporta: yyyyyyyyyyyyyyyyyyyyyyyyyyyyyy"   Personal Agent ha riconosciuto il file associato all'icona fornitagli, ma nel tentativo di eseguire il comando relativo "xxx", il sistema ha riscontrato un errore. Una descrizione più dettagliata è fornita caso per caso. "Non posso aprire "xxx" per i risultati. Controlla la linea OUTPUT=... nella mia icona."   Il parametro OUTPUT specifica un file (o una CON:) che non può essere aperto. Se si tratta di CON:, probabilmente c'è un errore nella sintassi, oppure le coordinate indicate giacciono fuori dallo schermo.   Vi è infine un'altra serie di messaggi autoesplicativi, che riguardano i casi in cui un file non viene riconosciuto o, se riconosciuto, non è stata definita alcuna azione corrispondente. In questi casi non si tratta di errori, ma di formati non previsti nel programma FAM in uso. Appendice B - Sintassi del FAM -------------------------------- La sintassi del FAM viene data con una variante della notazione EBNF.   Gli spazi, i tab e i newline non sono significativi, e possono apparire in sequenze arbitrarie ovunque possa apparire un singolo spazio. Tutto ciò che non è compreso fra "CLASS" e "END", oppure fra "ACTION" e "END" è considerato non facente parte del testo del programma - in pratica un commento. I delimitatori "CLASS", "ACTION" e "END" devono apparire in maiuscolo, gli altri token del linguaggio (compresi gli identificatori e i pattern) sono case-insensitive.   Ecco infine la sintassi: i non terminali sono racchiusi fra "<" e ">", il simbolo "<>" indica la stringa nulla, produzioni alternative sono separate da "|" e il simbolo di produzione è "::=". I terminali sono indicati in maiuscolo, ma a parte che per CLASS, ACTION e END il case non è significativo; le definizioni informali sono racchiuse fra "{" e "}". ::= ::= <> | ::= | ::= CLASS HAS END ::= {Identificatore} ::= | OR ::= NAME | ::= | AND ::= AT ::= "" | | "" | ::= {Una qualunque stringa ASCII, lunga fino a 255 caratteri. Non può contenere '"'} ::= 0x | 0 | $ | % | ::= {Al più due cifre esadecimali} ::= {Al più tre cifre ottali, con un valore <256} ::= {Al più otto cifre binarie} ::= {Ap più tre cifre decimali, con un valore <256} ::= ACTION IS END ::= {Identificatore} ::= {Un comando AmigaDOS} Note:   Gli identificatori possono essere costituiti da una qualunque sequenza di caratteri ASCII, eccettuati spazio, tab e newline, ma è bene (per compatibilità futura) che essi seguano le regole usuali per gli identificatori: una lettera o _, seguiti da un qualunque numero di lettere, cifre o _. Formalmente, usando le espressioni regolari: Identificatore = [a-zA-Z_][a-zA-Z0-9_]*   Inoltre, è da tener presente che al momento i espressi in binario non sono supportati e che l'unica supportata è VIEW. Se il valore di un qualunque supera 255, esso viene preso modulo 256 (cioè, viene considerato soltanto il byte di ordine più basso). Appendice C - Sviluppi futuri e ringraziamenti ------------------------------------------------   Si prevedono alcuni cambiamenti al linguaggio FAM, già anticipati nelle sezioni precedenti. Sarà possibile programmare diversi tipi di azioni, con le diverse icone corrispondenti, all'interno di un solo file FAM; si prevede anche la possibilità di associare un commento descrittivo ad ogni classe definita.   La prossima versione di Personal Agent farà uso delle nuove caratteristiche del Sistema Operativo per garantire un supporto in diversi linguaggi senza che sia necessario preparare una versione specializzata del programma per ogni lingua supportata.   L'Autore desidera ringraziare due altri membri del gruppo ICARUS, che hanno grandemente contribuito alla verifica del programma e alla preparazione della documentazione: Paolo Canali, che ha curato la versione tedesca, e Roberto Rosselli, che ha curato quella francese.