From 872864bf81f6450680adb2e27349dc01de56e2c9 Mon Sep 17 00:00:00 2001 From: Neil Brown Date: Tue, 7 Aug 2007 16:18:01 +0000 Subject: [PATCH] Added documentation to the AST --- AST.hs | 78 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 77 insertions(+), 1 deletion(-) diff --git a/AST.hs b/AST.hs index 7ad16d2..92eb73b 100644 --- a/AST.hs +++ b/AST.hs @@ -11,9 +11,13 @@ data NameType = | ProcName | ProtocolName | RecordName | TagName | TimerName | VariableName deriving (Show, Eq, Typeable, Data) +-- | A name structure for variable names in the AST. data Name = Name { + -- | The meta tag that indicates the location of this instance (use) of the name nameMeta :: Meta, + -- | The type of the thing referred to by this Name nameType :: NameType, + -- | The resolved name nameName :: String } deriving (Typeable, Data) @@ -24,13 +28,21 @@ instance Show Name where instance Eq Name where (==) a b = nameName a == nameName b +-- | A structure for holding information about the definition of a name data NameDef = NameDef { + -- | The meta tag that indicates the location of the definition ndMeta :: Meta, + -- | The resolved name ndName :: String, + -- | The original (raw, unresolved) name ndOrigName :: String, + -- | The type of the thing being named ndNameType :: NameType, + -- | The specification type (e.g. declaration, IS, RETYPES) ndType :: SpecType, + -- | The abbreviation mode (e.g. VAL abbreviation) ndAbbrevMode :: AbbrevMode, + -- | The placement of the variable (e.g. PLACE AT) ndPlacement :: Placement } deriving (Show, Eq, Typeable, Data) @@ -40,6 +52,7 @@ data Type = | Byte | Int | Int16 | Int32 | Int64 | Real32 | Real64 + -- | For N-dimensional arrays, the [Dimension] list will be of length N | Array [Dimension] Type | UserDataType Name | Record Name @@ -74,6 +87,7 @@ instance Show Type where show Timer = "TIMER" show (Port t) = "PORT OF " ++ show t +-- | occam arrays are permitted to have empty unknown dimensions, hence Dimension is not simply an integer data Dimension = Dimension Int | UnknownDimension @@ -92,11 +106,19 @@ data ConversionMode = | Trunc deriving (Show, Eq, Typeable, Data) +-- | Various different subscripts that can be used in occams data Subscript = + -- | A single array subscript Subscript Meta Expression + -- | A subscript that names a field of a record type | SubscriptField Meta Name + -- | A subscript pair that creates an array slice. + -- The first Expression is the FROM; the initial value to begin at, inclusive + -- The second Expression is the FOR; the count of items to include in the slice. | SubscriptFromFor Meta Expression Expression + -- | Like SubscriptFromFor, but without a FOR; it goes to the end of the array | SubscriptFrom Meta Expression + -- | Like SubscriptFromFor, but without a FROM; it starts from the beginning of the array | SubscriptFor Meta Expression deriving (Show, Eq, Typeable, Data) @@ -117,18 +139,27 @@ data ArrayElem = | ArrayElemExpr Expression deriving (Show, Eq, Typeable, Data) +-- | A variable can either be plain (e.g. "c") or subscripted (e.g. "c[0]" or "person[name]" data Variable = Variable Meta Name | SubscriptedVariable Meta Subscript Variable deriving (Show, Eq, Typeable, Data) data Expression = + -- | A monadic/unary operator Monadic Meta MonadicOp Expression + -- | A dyadic/binary operator | Dyadic Meta DyadicOp Expression Expression + -- | The most positive value of a given type | MostPos Meta Type + -- | The most negative value of a given type | MostNeg Meta Type + -- | The size of a given array type, see SizeExpr | SizeType Meta Type + -- | The size of a given array in number of sub-components. + -- As the occam 2 reference manual explains, given [8][4]INT a:, SIZE a is 8 and SIZE a[0] is 4 | SizeExpr Meta Expression + -- | See SizeExpr | SizeVariable Meta Variable | Conversion Meta ConversionMode Type Expression | ExprVariable Meta Variable @@ -164,37 +195,54 @@ data DyadicOp = | After deriving (Show, Eq, Typeable, Data) +-- | Input items in occam can either be counted arrays, or single variables data InputItem = + -- | The first variable is the count, the second is the array InCounted Meta Variable Variable | InVariable Meta Variable deriving (Show, Eq, Typeable, Data) +-- | Output items in occam can either be counted arrays, or single variables data OutputItem = + -- | The first expression is the count, the second is the array OutCounted Meta Expression Expression | OutExpression Meta Expression deriving (Show, Eq, Typeable, Data) +-- | The Name names the replicator index, the first expression is the base and the second expression is the FOR data Replicator = For Meta Name Expression Expression deriving (Show, Eq, Typeable, Data) +-- | A choice in an IF statement data Choice = Choice Meta Expression Process deriving (Show, Eq, Typeable, Data) +-- | A guard in an ALT data Alternative = + -- | A plain guard. The channel/timer is the Variable, and the destination (or AFTER clause) is inside the InputMode. + -- The process is the body of the guard Alternative Meta Variable InputMode Process + -- | A conditional guard. The Expression is the pre-condition, everything else is as Alternative above | AlternativeCond Meta Expression Variable InputMode Process + -- | A skip guard (always ready). The Expression is the pre-condition. | AlternativeSkip Meta Expression Process deriving (Show, Eq, Typeable, Data) +-- | An option in a CASE statement data Option = + -- | A single CASE option can have multiple expressions to match against Option Meta [Expression] Process + -- | The else guard is picked if no other options match. It does not have to be the last option. | Else Meta Process deriving (Show, Eq, Typeable, Data) +-- | An option in an "? CASE" (input-case) statement +-- The name is the protocol tag, followed by zero or more input items, followed by the process to be +-- executed if that option is matched data Variant = Variant Meta Name [InputItem] Process deriving (Show, Eq, Typeable, Data) --- This represents something that can contain local replicators and specifications. +-- |This represents something that can contain local replicators and specifications. -- (This ought to be a parametric type, "Structured Variant" etc., but doing so -- makes using generic functions across it hard.) data Structured = @@ -216,29 +264,52 @@ data InputMode = | InputAfter Meta Expression deriving (Show, Eq, Typeable, Data) +-- | Abbreviation mode. data AbbrevMode = + -- | No abbreviation Original + -- | An abbreviation (by reference) | Abbrev + -- | An abbreviation (by value) | ValAbbrev deriving (Show, Eq, Typeable, Data) +-- | Used for introducing specifications (process/function declarations, variables, type definitions, abbreviations, etc) data Specification = Specification Meta Name SpecType deriving (Show, Eq, Typeable, Data) +-- | Used when declaring a Specification data SpecType = + -- | Places a variable at a given memory location Place Meta Expression + -- | Declares a variable of the given type | Declaration Meta Type + -- | Declares an abbreviation | Is Meta AbbrevMode Type Variable + -- | Declares a constant to be a particular expression | IsExpr Meta AbbrevMode Type Expression + -- | Declares an array that abbreviates some channels (the list of Variable). | IsChannelArray Meta Type [Variable] + -- | Declares a data type (like a typedef) | DataType Meta Type + -- | Declares a new record type. The Bool is True if the record is PACKED, False otherwise. + -- The list of (Name,Type) are the members of the record | RecordType Meta Bool [(Name, Type)] + -- | Declares a simple (sequential) protocol that has the type-list in order as its data items. | Protocol Meta [Type] + -- | Declares a protocol with choice. Each (Name, [Type]) is a tag name, + -- followed by various data items (as per simple sequential protocols). | ProtocolCase Meta [(Name, [Type])] + -- | Declares a procedure. SpecMode is inline or plain. + -- The list of Formal are the parameters to the procedure, and the Process + -- is the actual body of the procedure. | Proc Meta SpecMode [Formal] Process + -- | Declares a function. Much the same as Proc, but the list of Type is the return type. | Function Meta SpecMode [Type] [Formal] Structured + -- | Declares a retyping abbreviation. Type is the new type. Variable is the variable being retyped | Retypes Meta AbbrevMode Type Variable + -- | Declares a retyping abbreviation. Type is the new type. Expression is the expression being retyped | RetypesExpr Meta AbbrevMode Type Expression deriving (Show, Eq, Typeable, Data) @@ -246,12 +317,17 @@ data SpecMode = PlainSpec | InlineSpec deriving (Show, Eq, Typeable, Data) +-- | Formal parameters, as in procedure parameter definitions data Formal = Formal AbbrevMode Type Name deriving (Show, Eq, Typeable, Data) +-- | Actual parameters to calls of functions/procedures data Actual = + -- | A variable used as a parameter. + -- I believe AbbrevMode here is included only for convenience - and the same for Type ActualVariable AbbrevMode Type Variable + -- | An expression used as a parameter | ActualExpression Type Expression deriving (Show, Eq, Typeable, Data)