This file is the concatenation of the README files from the individual packages that comprise m3tk. m3tk-misc.2 package This package contains miscellaneous modules that support the Modula-3 toolkit. M3Args Keyword/value (command-line) argument package M3Assert Toolkit specific assertions M3Time (Clean) Elapsed CPU time interface ------------------------------------------------------------------------------- m3tk-files.2 package This package provides an interface to files and directories for the Modula-3 toolkit. M3Extension Operations on "standard" Modula-3 file extensions M3Files Open file with given extension M3Files_m3p Friends interface for "M3Path" implementation M3Path Search path support M3Directory M3Extension-centric directiry enumerator ------------------------------------------------------------------------------- m3tk-gast.2 package This package provides basic facilities for specifying an Abstract Syntax Tree. It defines a basic node type AST.NODE, and in separate interfaces, specifies a set of standard methods applicable to an AST node. Language specific ASTs are defined by subtyping AST.NODE and providing implementations for the standard methods. AST defines AST.NODE and explains the basic framework AST_Init adds an "init" method to AST.NODE AST_Name adds a "name" method to AST.NODE AST_Iter adds an iterator for node children AST_WalkRep adds support for tree walks with client callback AST_CopyRep adds support for tree copies with client callback AST_DisplayRep adds support for "displaying" a tree node AST_LAST defines the "last" interface to extend AST.NODE The interfaces AST_{Walk.Copy,Display}Rep are not intended to be used by AST clients, they provide support for the following interfaces: ASTWalk walk a tree with callback to client ASTCopy copy a tree with callback to client Display is inherently language specific, so does not appear at this level. ASTName just a veneer on the "name" method. ASTNodeArray presents the children of a node as an array ------------------------------------------------------------------------------- m3tk-ast.2.2 package This package provides a specification of an Abstract Syntax Tree for Modula-3 in terms of the framework defined by the "m3tk-gast" package. It provides implementations for some of the basic methods defined in the "AST" interface in "m3tk-gast". Here is a guide to what is (publically) available: M3AST Defines M3AST.NODE, the root type of all M3AST nodes. M3AST_LX Lexical types in the AST M3AST_AS Modula-3 AST specification M3AST_PG Standard pragma AST extensions M3AST_SM Semantic extensions to the AST M3AST_TM "Temporary" attributes, mostly private. M3AST_FE AST extensions to support compiler front-end M3AST_TL AST extension for property sets on AST nodes The above interface are all "abstract" and do not reveal how the AST attributes are actually represented. There are a set of companion interfaces, "M3AST_XX_F", where "XX" is one of the above, that define the attributes as fields of the OBJECT types. You typically import both "M3AST_XX" and "M3AST_XX_F" into a client program. SeqElem A generic interface used to specify sequences and sets in the AST. It is instantiated with "Elem = M3AST_XX_TYPE", where "XX" is one of the above and "TYPE" is a type declared in the interface "M3AST_XX", that we want to make a sequence of. So there are lots of interfaces named "M3AST_XX_TYPE" that exist solely to rename "M3AST_XX.TYPE" to "M3AST_XX_TYPE.T" for generic instantiation. SeqElem_rep A representation for sequences as linked lists. Try not to import this as it makes your code dependent on this representation and there are alternatives that are, e.g., more space eficient. M3ASTWalk Obsolete tree-walk interface. Use ASTWalk instead. M3ASTCopySM A callback to use with ASTCopy to copy (share) the semantic attributes. M3ASTScope An interface that maintains a "scope" handle in sync with a walk of the AST. ------------------------------------------------------------------------------- m3tk-syn.2.2 package This package contains the Modula-3 toolkit parser. It is here that the decisions on how to represent the lexical entities in the AST specification are made. Here is a guide to what is (publically) available: M3CId Reveals an M3AST_LX.Symbol_rep, and provides procedures for TEXT <-> M3AST_LX.Symbol_rep mappings. M3CLiteral Reveals an M3AST_LX.Literal_rep, and provides procedures for TEXT <-> M3AST_LX.Literal_rep mappings. M3CParse The parser interface M3CPragma An interface to the pragmas associated with an AST, i.e. M3AST_LX.PragmaStore. M3CSrcPos Operations on M3AST_LX.SrcPos values. m3tk-toolmisc.2 package -- created Thu Apr 2 17:07:06 PST 1992 by mjordan current owner mjordan This package contains a set of miscellaneous interfaces that are useful to AST-based tools. M3CUnit Operations on compilation units. M3CUnit_priv Reveals an M3AST_FE.Unit_uid M3Context Collections of ASTs M3ContextRemove Removing ASTs (and dependents) from a collection M3Error Error reporting M3Conventions Standard conventions and support procedures m3tk-sem.2 package -- created Thu Apr 2 16:48:23 PST 1992 by mjordan current owner mjordan This package contains the Modula-3 toolkit semantic analyser. As well as checking the static semantics, it also computes the semantic AST attributes specified in the M3AST_SM interface (in the m3tk-ast) package. Most of this package is private, but some interfaces provide utility code that is needed by many AST clients, vis: M3ASTNext Provides some iterators to "smooth out" the structure of the AST. E.g the sequence of "Used_interface_id" nodes from all of the "IMPORT", "FROM I IMPORT" nodes. M3CTypesMisc Useful operations on M3TYPE, TYPE_SPEC classes. M3CStdProcs Support for the "standard" procedures/functions M3CStdTypes Support for the built-in types, e.g. "BOOLEAN". M3CBackEnd Defines the interface between the front-end and the back end, in terms of a set of procedures that must be implemented. ------------------------------------------------------------------------------- m3tk-astpickle.2 package This package suggests that it might provide AST pickes. In fact, this is merely a stub version that fails if it is called. (Once there was a stub-based implementation that worked, and it should be easy to use the Pkl package, but there is no demand at the moment). ------------------------------------------------------------------------------- m3tk-fe.2 package This package provides the compiler front-end of the Modula-3 toolkit. The interfaces are not usually invoked directly, see "M3ToolFrame". M3CFETool Compiler front-end tool, i.e. with user interface M3CGoList Compile a set of units together M3CGo Compile a single unit. Provides an extension facility. m3tk-target.2 package -- created Thu Apr 2 17:22:13 PST 1992 by mjordan current owner mjordan This package implements the M3CBackEnd interface of the Modula-3 toolkit compiler front-end. It claims to match the SRC Modula-3 implementation, e.g. it computes the same value of BYTESIZE(T) as the SRC compiler. It is parameterised by machine type (actually C compiler) and it is possible to change this default at compile time. Some interfaces may be useful to other AST tools, vis: M3CBackEnd_C Reveals an M3AST_SM.Exp_value M3CBE_C_Tool Handles the decoding of the machine type setting ------------------------------------------------------------------------------- m3tk-toolframe.2 package This package provides the standard framework in which a Modula-3 toolkit tool sits. The "M3ToolFrame" interface provides standard set of sub-tools, and provides a standard way for the compiler front-end to be invoked, resulting an in set of ASTs that are (presumably) processed by the tool. M3ToolFrame Standard way to invoke the compiler M3ASTCacheTool Storage manager control M3DPathTool Explicit search path tool m3tk-astdisplay.2 package -- created Fri Apr 3 09:47:45 PST 1992 by mjordan current owner mjordan This package provides an implementation of the "display" method of an AST.NODE for all M3AST_AS nodes. It pretty prints the output, but loses all comments and pragmas, other then EXTERNAL and INLINE. A version which reproduces the input exactly is planned. The client interface is via M3ASTDisplay. M3ASTDisplay Display a subtree to a given IO.Stream. ------------------------------------------------------------------------------- m3tk-pl.2 package This package contains the pre-linker tool of the Modula-3 toolkit. The pre-linker is based on ASTs and computes some additional attributes defined in the M3AST_PL interface. A tool that wants to operate on complete programs will find this package indispensible. M3LTool The pre-linker tool M3LBackEnd Interface to an (imaginary) linker back end (e.g. ld) M3LDepends Computes the "pl_depends_on" attribute M3LExports Checks all procedures implemented and opaque types revealed M3LInitOrder Computes initialisation order based on "pl_depends_on" M3LMain Finds "Main" module(s) in a context M3LMethodTable Computes the "pl_method_table" attribute for object types M3LOpaque Causes the "current revelation" attribute to be the same as the "concrete" revelation M3LProgContext Creates a program context from another context M3LReveals Checks consistency of revelations M3LSubtype Computes the "pl_subtype_s" attribute M3LTypeCodes Computes the "tmp_type_code" attribute for TYPE_SPECs ------------------------------------------------------------------------------- m3tk-warn.2 package This package provides a set of AST tree walks that warn the user of possible problems, e.g. unused variables. The set is pulled together under the auspices of a single tool that registers itself as a compiler front-end extension. Much more could be done here, of course. M3CWarnTool Warning tool M3CChkNarrow Check for implicit NARROW M3CChkRaises Check for uncaught exceptions (doesnt handle <*FATAL*> M3CChkUses Check unused declarations M3CChkReturn Check missing RETURNs ------------------------------------------------------------------------------- m3tk-dep.2 package This package contains the guts of the "m3check" tool. It started life as a simple "dependency analyser", hence the term "dep" but has evolved into providing support for the compilation of large systems. In general, if you want to write a tool that is going to access entire programs or packages as AST collections, you will find this package useful. M3DepDATool User interface to M3DepCompile M3DepCompile Large system compilation tool M3DepM3Path Access to Modula-3 files (in a set of directories) with support for detecting additions/deletions/ modifications. ------------------------------------------------------------------------------- m3tk-env.2 package This package provides environment information for the Modula-3 toolkit. E.g. where are the standard interfaces stored. M3Env Procedures returning TEXTs defining LIB and PUB. m3tk-astall.2 package -- created Fri Apr 3 15:42:26 PST 1992 by mjordan current owner mjordan This package contains but one interface, M3AST_all, which defines the standard set of concrete revelations for AST nodes. This set supports all of the essential tools, down to the pre-linker. You must import M3AST_all into the main program module of any toolkit tool. ------------------------------------------------------------------------------- m3tk-asttrans.2 package This package contains some miscellaneous transformations on ASTs. It also includes a tool to display generic instantiations. M3CImportASTrans Tranform to remove "IMPORT A AS B" M3ExpandCalls Transform calls to include defaults and remove keywords M3QualNames Transform to remove all "FROM I IMPORT N" and replaace N by I.N. M3GTool See generic instantiations tool