Otherware

home *** CD-ROM | disk | FTP | other *** search

/ Otherware / Otherware_1_SB_Development.iso / amiga / utility / misc / agent10.lzh / Docs / Agent_E.doc next >

Wrap

Text File | 1992-05-17 | 25.1 KB | 618 lines

Personal Agent 1.0 (C) Copyright 1992 V. Gervasi - ICARUS Introduction -------------- ááPersonaláAgent is a program meant to make it easy operating on files via the Workbench's icons. Using this program, you will be able to easily look at graphics images, listen to music files, unpack archives of different kinds, read on-line manuals and other documents and, in general, perform many operations that would otherwise require using the CLI. By simply dragging a Workbench's icon and dropping it over Personal Agent's icon, the program will automatically recognize the file associated with the icon and perform the corresponding actions. ááThe program is completely configurable, thanks to a simple embedded programming language, and to a graphical user interface that conforms to your preferences. ááIt comes with some pre-built configurations, understanding many file types, and with a number of icons among which you can choose your favorites. ááThis manual will first illustrate Personal Agent's basic operations, from installing it to using the standard configurations. Then we will look at how to configure the program, and at FAM, the internal programming language, and his compiler. Installing and Using Personal Agent ------------------------------------- ááIf you followed the standard installation procedure, that only require a double-click on the "Install" icon, and chose to execute Personal Agent at boot time (that is the default), you don't need to do nothing more. ááIf, instead, you chose to NOT execute Personal Agent at boot time, you will need to run it by hand. Personal Agent can be run both from Workbench and from CLI. In the first case, a double-click on its icon is enough; in the second one, you should give the name as a command to the CLI, preferably preceded by "RUN" to ask for background execution. ááAn example of the latter case is run >NIL: <NIL: Agent ááUnless you incur in some error (if this is the case, have a look at Appendix A), the program will briefly display an information message, showing what FAM configuration it is currently using, and a copyright notice. Immediately after this, an icon will appear on the Workbench screen representing the program. ááFrom now, it is sufficient to drag and drop a file icon over Personal Agent's one, to have the program analyze the file type and execute the appropriate command specified in the FAM configuration. Usually, this command will permit to "look" at the file in the most appropriate way. ááA double-click on the Personal Agent's icon will open a window showing various statistics on the program's operations, together with three options to continue the execution, clear the accumulated statistics, or terminate the program. Configuring Personal Agent ---------------------------- ááThe main method used in configuring Personal Agent is by its icons' Tool Types. If you have followed the installation procedure, you'll find this Tool Types already set suitably; otherwise, you will have to manually enter all required informations. ááTo reach these options, you should select the icon "Agent," found in the same drawer you installed Personal Agent in, and choose "Informations" from the "Icons" menu of the Workbench (as an alternative, you can press Right Amiga-I). It will show a window containing, among other things, a list of Tool Types. You can change these options by selecting a line with the mouse and editing its contents in the editing area at the bottom of the list; press RETURN when you have modified it. ááWhen you are satisfied of your choices, press the "Save" gadget. If you changed your mind, and don't want to change the current configuration as well, you can press the "Cancel" gadget. ááHereafter we will discuss the parameters you can change to suit your needs or preferences. ICON=<icon-name> ááThis setting lets you choose which icon should appear on the Workbench screen to represent the program. The <icon-name> you supply must be the name of a file, with an optional path, whose icon is borrowed by Personal Agent. If this line is not present, Personal Agent will use its own icon (the icon of the file "Agent"). NAME=<name> ááBy using this setting, you can indicate what name should Personal Agent use to name its icon. This may be any name, but shorter ones are better. If this line is omitted, Personal Agent will use its own name ("Agent"). OUTPUT=<output> ááWith the OUTPUT parameter you can select where to send all messages produced by programs executed by Personal Agent. Usually, you will want this messages to be displayed in an on-screen window, and will use CON: as <output> (that is the default). It is also advisable to specify the /AUTO and /WAIT console attributes, asking to make the window closable and to not open it at all unless some message is actually produced. ááThe syntax for CON:áis CON:<left>/<top>/<width>/<height>/<title><attributes> as an example, OUTPUT=CON:0/15/600/120/Agent/AUTO/WAIT means that the messages will be displayed in a window which has its top left corner at (0,15), 600 pixels wide and 120 pixels tall, whose title will be "Agent." Moreover, the window will open only if there is some message to display, and even after the end of the command, will wait a click in the close gadget to disappear. You can find more detailed information on CON: on your "Using The System Software" manual. ááIf <output> contains the character sequence "%s," it will be replaced by the name of the command Personal Agent runs to view the file (including any parameter). CLASSES=<classes> ááThis Tool Type lets you indicate which file contains the source FAM program that defines file classes and related actions to look at them (the format of this file will be explained later). If this line is not present, the file "classes" will be used (if even "classes" cannot be found, an error message will be issued). XPOS=<x-position> YPOS=<y-position> ááWith these you can choose the position that Personal Agent's icon will occupy on the Workbench screen. The positions must be expressed in screen pixels; (0,0) is the upper left corner of the screen. If these lines are omitted, the icon will be placed in such a way to not interfere with other icons already present on the screen. You can obtain the same effect by setting one or both of the coordinates to "-1"; the system will then choose a suitable location. WAIT=<seconds> ááAt last, this parameter allows you to choose how long Personal Agent's messages should wait on screen. The standard setting is 7 seconds. Please note that every message will disappear as soon as you click a mouse button in the message window or press any key. To hold the message longer than the defined time, just click OUTSIDE of the message window; the time count will be suspended. The FAM Language ------------------ ááFAM is an acronym standing for File Analysis Machine, and this name explains well the goals and the limits of FAM. If you chose to install the examples, you can look at some FAM programming examples by reading the files "view_classes" and "unpack_classes." The files "view_classes.sys" and "unpack_classes.sys" contain the compiled version of the same FAM programs. ááFAM is a very specialized language, with only few commands oriented towards describing file's formats and specifying actions to perform on these files. ááThe format for a FAM source file is the so-called "free form." The placement of the commands is not significative: spaces, tabs and newlines doesn't change the meaning of a program. ááBesides this, the FAM has been thought to make for easy documentation of programs; because of this, comments may be anywhere in the source file, and don't need any particular delimitation characters. ááIndeed, the only parts of a source file at which the compiler look are those between "CLASS"-"END" and "ACTION"-"END" keywords; between these (in upper case), comments are not allowed. Any other element of the language is case-insensitive. ááComments apart, FAM sources are made of two kinds of commands, usually (but not necessarily) collected in two separate sections: Classes Definitions and Actions Definitions. ááClasses Definitions are needed to allow Personal Agent to recognize the kind of file it is dealing with; Actions Definitions are needed so that Personal Agent knows what to do with these files. ááClasses Definitions let you define "classes" of files, by specifying what format must the file match to be considered a member of the class. The format specification may be done on the name and on the contents of the file. The informal syntax for a class definition is CLASS <class-name> HAS <format> END ááThe <class-name> is the (unique) name used to refer to the class; this name will be used later to indicate what actions are to be performed on the file. The <format> is made from two kinds of items: name formats and contents formats. ááName formats are like NAME <pattern> where <pattern> can be any string containing AmigaDOS pattern characters: # ? ~ ( | ) % [ ]. You may wish to read your AmigaDOS manual on the meaning of these symbols. ááContents format are like <byte-list> AT <position> where <byte-list> is a sequence of bytes, that can be expressed in several ways, and <position> is the position into the file, expressed as byte from the start of the file. ááThe <byte-list> may contain decimal numbers: 123 octal numbers: 033 hexadecimal numbers: $AB o 0xC0 binary numbers: %01100110 strings: "FORM" (this string specifies 4 bytes) ááThese components may be specified in any order, to specify bytes sequences up to 256 bytes in length. This is not a strict limit: if, for example, you need to identify 300 bytes at the start of a file, you can write ... HAS <first 250 bytes> AT 0 AND <remaining 50 bytes> AT 250 ... ááYou can connect different formats with AND and OR operators to specify complex conditions; AND takes precedence over OR. It is possible to define several times the same class; in such cases, every single definition is ORed with the other ones. ááIt is time for some example: áá- An IFF ILBM file, the standard format for graphical images on the Amiga, contains the string "FORM" in the first four bytes, the length of the data in the following four and the string "ILBM" in the bytes from 8 to 11, followed by other data. A format for such a class could then be CLASS ILBM has "FORM" at 0 AND "ILBM" at 8 END áá- An executable file, on the Amiga, starts with the hexadecimal sequence 000003F3. This gives a definition like CLASS Exe has $00 $00 $03 $F3 at 0 END or CLASS Exe has 0 0 0x03 0xf3 at 0 END or CLASS Exe has 0 0 3 243 at 0 END etc. áá- The popular packer/archiver LhArc, and the similar LZ, produces archive files whose name usually ends with ".lzh" or ".lha." These names are not enforced, however, so we cannot rely on them to define our class. However, such archives always contain a string of the form "-lh?-" at position 2, where ? indicates the style of compression applied to the original file(s) (usually 0, 1 or 5). Let's write a definition for this class: CLASS LZH has NAME #?.lzh OR NAME #?.lha OR "-lh" at 2 AND "-" at 6 END ááWe could also write CLASS LZH has NAME #?.lzh OR NAME #?.lha OR "-lh0-" at 2 OR "-lh1-" at 2 OR "-lh5-" at 2 END ááPlease note how the layout of the definition is absolutely free, and dictated here from aesthetical considerations. ááNow we come to actions definitions. ááTheir format is ACTION VIEW <class-name> IS <action> END ááIn this case, <class-name> is (obviously) the class' name, the same used in the class' definition, while <action> is an AmigaDOS command that will be executed when Personal Agent will face a file conforming to the class' definition. ááIn the <action> part, every occurrence of the string "%s" will be substituted by the name of the file under exam. The AmigaDOS command will be executed in the same directory containing the file examined. ááIt is necessary to spend a few words on this topic. Usually, AmigaDOS commands are run from a Shell (or CLI), and may assume the presence of a "path," or, a list of directories where things like other programs or needed files are searched in. The same thing holds for Personal Agent IF the program has been ran from a CLI (or any other Shell, like AmigaShell); if Personal Agent was ran from the Workbench, it cannot find a path and thus the <action>s must explicitly indicate where to find the commands to execute. It is possible that this behavior will change on a future release of Personal Agent or the Operating System. ááLet's look at some example: áá- We want that, when Personal Agent meets an archive of class LZH (as defined above), it will show the list of the files contained in the archive: ACTION VIEW LZH is lz v "%s" END ááHere, we use the command LZ with the option v (that shows the contents of the archive); the %s will be substituted by the actual file name. We used "%s," not %s: this is a good rule of thumb, to avoid problems with file names containing spaces that could mess up LZ. áá- Now we want that, when an ILBM file is analyzed, Personal Agents starts a graphical editor (let's suppose it is named SuperPaint), ready to work on the analyzed file: ACTION VIEW ILBM is Work:usr/appl/SP/SuperPaint "%s" END ááIn this case, we have indicated the full path to reach SuperPaint: this may be needed if our usual path doesn't contain "Work:usr/appl/SP" or if we would like to start Personal Agent from the Workbench (that, as said above, doesn't provide a path as the Shell does). áá- Let's imagine that, to "look" at an archive file, we really mean to unpack it. An adequate definition for LhArc would be ACTION VIEW LZH is lharc -a -x x "%s" #? RAM: END ááThe "VIEW" in the syntax of actions definitions is actually a place holder; in a future release of the language you could indicate different actions to perform on a file. With this variation, we could have ACTION VIEW to look at a file, ACTION RUN to execute it, ACTION UNPACK to unpack it, ACTION HEAR to listen to it, ACTION INFO to get some information on the file... The user will be free to define his set of actions; a graphical interface will allow him to select which of the different actions to perform on the file. ááIt is useful to consider that <action>s are run ASYNCHRONOUSLY; in other words, Personal Agent does not wait the completation of a command, but is immediately ready to accept more manipulations. This fact may be of a certain importance when you drop on Personal Agent's icon not one, but a set of icons (obtained either by shift-clicking them, or by drag-selecting them): in such cases, Personal Agent will run almost contemporarily every command that pertains to any of the selected icons. ááLet's consider now the compilation pass. ááTo modify FAM programs, or to write brand new ones, you can use an editor, such as ED or MicroEmacs (both are part of the Amiga System Software) and save the text in a file, whose name is in the CLASSES=... Tool Type of Personal Agent. ááWhen Personal Agent starts, it automatically checks to see if the FAM program indicated in his CLASSES parameter needs recompilation (based on system date and time). If it can determine that a compilation is required, the process happens silently, leaving the result in a file with the same name as the source file, but with a ".sys" suffix appended. In the event of any compilation error (wrong syntax, insufficient memory, too many definitions...) a warning message will appear and the old (if any) compiled file will be retained. If all goes well, you should barely notice a small delay on startup: this is all. ááWhen Personal Agent is called to analyze a file, it will check the file's name against all patterns defined in the FAM program, in appearance order. Only if none of them matches will Personal Agent consider the "HAS xxx AT yyy" clauses (since checking them is a bit slower); again, them will be checked in appearance order. It is quite possible that a file doesn't match a given clause, but matches a subsequent one relating to the same class: CLASS LZH has "-lh1-" at 2 END CLASS FOO has "Foo1" at 10 END CLASS LZH has "-lh5-" at 2 END ááNow, the file is considered of class LZH only if it has "-lh1-" at position 2, or if it has "-lh5-" at the same position BUT does not contain "Foo1" at position 10 (in that case, it would be considered as being of class FOO). ááOnce the file's class has been determined, Personal Agent will check the class against the actions defined, as always in appearance order. If there is no "ACTION" relating to that class, an error message is displayed, else the corresponding AmigaDOS command is executed. ááIf the file doesn't fall in one of the defined class, it is considered as being of the special class "DEFAULT." An action for class DEFAULT may (and should) exist. Usually, ACTION VIEW DEFAULT will be some very general viewer (as "more %s" or "echo I don't know how to display %s!"), but the final choice is up to you. If no action for DEFAULT is defined, you will get a warning message. ááAppendix B contains the formal syntax of FAM. Appendix A - Guide to the Messages ------------------------------------ ááAll messages about compilation errors are rather auto-explicative. These messages may appear in three passes of compilation: compiling NAMEs (for HAS NAME xxx clauses), compiling CODEs (for HAS xxx AT yyy clauses) and compiling ACTIONs (for ACTION VIEW yyy IS zzz clauses). In every case, the message contains suggestions on how to remedy to the error condition, as well as the offending FAM source line. ááBesides the compilation errors, other unusual occurrences may happen, all signaled by a related message: "Error compiling FAM source file "xxx". FAM Object file "xxx.sys" unchanged." ááSince some error occurred during the compilation phase, it wasn't possible to produce a correct object file. The old one (if available) will be used instead. "Cannot open FAM source file "xxx" ! Look at the CLASSES=... ToolType in my icon." "Cannot read FAM object file "xx.sys" ! Look for the CLASSES=... ToolType in my icon." ááPersonal Agent could not find the file stated via the CLASSES parameter. Since it is not possible to know what class definitions to use, Personal Agent will not be executed. "Cannot start the File Analysis Machine !" ááThis messages appear usually after other, more specific, messages. It means that the part of Personal Agent that actually recognizes file types could not initialize itself; Personal Agent will not be executed. "Couldn't add my icon to the Workbench screen" ááThe system rejected Personal Agent's request to add its icon among those shown by Workbench. This could happen due to a low memory condition, or because Workbench is not actually running, or even as an effect of previous errors. "Couldn't get my .info file !" ááPersonal Agent could not find the file containing its own icon ("Agent.info"). Since this file contains all the Tool Types that Personal Agent needs to configure itself, the program cannot be executed. "Couldn't create a message port !" ááThis is an anomalous condition, that sometimes happens because of low memory. Personal Agent cannot be executed. "Cannot access that object (not a file ?)" ááPersonal Agent was called to examine an icon that isn't actually a file, such a disk's or drawer's icon, or even the icon of another program that, as Personal Agent does, resides on the Workbench screen. "Cannot access "xxx" !" "Cannot access that object !" ááFor some reason, Personal Agent cannot access to the file represented by the dropped icon. The file will not be examined. "Cannot open "xxx" !" "Cannot open that object !" ááAn existing file correspond to the given icon, but this file cannot be opened for reading. The file will not be examined. "Cannot start "xxx", system returned: yyyy yyyyyyyyyy yyy yyyyyyy yyyyyy" ááPersonal Agent did recognize the file related to the given icon, but in the attempt of executing the related action ("xxx"), the system incurred in an error. A more detailed description is given case by case. "Sorry, cannot open "xxx" for output. Look for the OUTPUT=... ToolType in my icon." ááThe OUTPUT Tool Type specifies a file (or a CON:) that cannot be opened. If it is a CON:, most probably there is an error in his syntax, or the given coordinates lay out of the screen. ááThere is another set of auto-explicative message, concerning cases of files not being recognized or, if recognized, of no action being defined for that class. These are not errors, but a consequence of presenting a file in a format that Personal Agent doesn't "knows." Appendix B - FAM Formal Syntax ------------------------------ ááThe FAM syntax is presented here using a variant of the EBNF notation. ááSpaces, tabs and newlines are not significant, and can appear in any arbitrary sequence anywhere a single space can. ááEverything not included between "CLASS" and "END", or between "ACTION" and "END" is considered as not being a part of the FAM program - in other words, it is a comment. The delimiters "CLASS", "ACTION" and "END" must appear in upper case, all other tokens of the language (including identifiers and patterns) are case-insensitive. ááAt last, here is the syntax: non-terminals are shown between "<" and ">", the symbol "<>" stands for the null string, alternative productions are separated by "|" and the production symbol is "::=". All terminals are written in upper case, but, except for CLASS, ACTION and END, case is not significative; informal definitions are delimited by "{" and "}". <program> ::= <stmt-list> <stmt-list> ::= <> | <stmt> <stmt-list> <stmt> ::= <class-def> | <action-def> <class-def> ::= CLASS <class-name> HAS <or-pr-list> END <class-name> ::= {Identifier} <or-pr-list> ::= <or-pred> | <or-pred> OR <or-pr-list> <or-pred> ::= NAME <pattern> | <and-pr-list> <and-pr-list> ::= <and-pred> | <and-pred> AND <and-pr-list> <and-pred> ::= <bytes> AT <offset> <bytes> ::= "<string>" | <byte> | "<string>" <bytes> | <byte> <bytes> <string> ::= {Any ASCII string, up to 255 bytes in length. It cannot contain '"'} <byte> ::= 0x<HH> | 0<OOO> | $<HH> | %<BBBBBBBB> | <DDD> <HH> ::= {At most two hexadecimal digits} <OOO> ::= {At most three octal digits, with value <256} <BBBBBBBB> ::= {At most eight binary digits} <DDD> ::= {At most three decimal digits, with value <256} <action-def> ::= ACTION <action> <class-name> IS <command> END <action> ::= {Identifier} <command> ::= {An AmigaDOS command} Notes: ááIdentifiers are made of any sequence of ASCII characters, except space, tab and newline. It is better (for future compatibility) to follow the usual rules for identifiers: a letter or _, followed by any number of letters, digits or _. Formally, using regular expressions, Identifier = [a-zA-Z_][a-zA-Z0-9_]* ááKeep in mind that, as of the current release, <byte>s expressed in binary form are not supported, and the only <action> supported is VIEW. If any <byte> denotes a value greater than 255, it will be considered modulo 256 (i.e., only the lowest-order byte is taken into account). Appendix C - Future Directions and Various Thanks ------------------------------------------------- ááThe FAM language will undergo some revision, as already anticipated in the previous sections. It will be possible to program different type of actions, with different icons for each of them, all in a single FAM file; a descriptive comment for each defined class is a probable addition. ááThe next revision of Personal Agent will use some new service of the OS to warrant support to different languages without the need for a separate version of the program for each language. ááThe Author wish to thank two other member of the ICARUS group, that have greatly contributed to Personal Agent verification and document preparation: Paolo Canali, that handled the German version, and Roberto Rosselli, that handled the French one.