Generator

This holds for revision 1129. Revision 12xx changed names of files and the way generation works. -- GerboEngels - 11 Mar 2008

The Generator

The generator ($root/generator/ and $root/proxima/bin/generator) generates a couple of *_Generated{.hs/.ag} files from the DocumentTypeDefinition.prx definition.

Data type X stands for a data type (except EnrichedDoc) in DocumentTypeDefinition.prx, C stands for a constructor of a data type X, and F stands for a field of data type X

Generated file	Generated by	What is generated
DocTypes_Generated.hs	GenTypes? .hs	Data type definitions
DocumentEdit_Generated.hs	GenEditable? .hs	instance declarations, mainly for class Editable, defining how to deal with editing (copy/paste/selecting) documents
DocUtils_Generated.hs	GenDocUtils? .hs	Utility functions, like XML parsers
PresentationAG_Generated.ag	GenAG? .hs	AG related things
ProxParser_Generated.hs	GenProxParser? .hs	Provides some helper functions to build default values and to reuse tokens

The generated files also contain hand written code: the beginning of the file (including the import statements) until the delimiting line

----- GENERATED PART STARTS HERE. DO NOT EDIT ON OR BEYOND THIS LINE -----

All lines before this line are copied and pasted in front of the newly generated file, and most files often require the editor implementor to write additional data types, special behaviour and utility functions there.

DocTypes? _Generated.hs

Generated are the data types from DocumentTypeDefinition.prx that appear in the right-hand side of data definition and have an own data type definition. E.g, if this is your DocumentTypeDefinition.prx:

data Top = T Foo
data Foo = F Bar Baz
data Bar = B Int

then definitions for Top, Foo and Bar will be generated. X consists of Top, Foo and Bar, C consists of T, F and B, and F consists of Foo, Bar, Baz and Int.

The generated data types look as follows:

data X = C1 IDP ... IDP F1 ... Fn
       | C2 IDP ... IDP F1 ... Fn
       | ...
       | HoleX
       | ParseErrX (Presentation Document Node ClipDoc UserToken)
          deriving show

The Document and UserToken data type definitions are not in DocumentTypeDefinition.prx, but they have to be present in DocType_Generated.hs. Therefore the editor implementor has to write these data types. Document has the form shown above, without the IDP parts. UserToken (deriving (Show, Eq, Ord)) is a data type that should define the tokens used in ScannerSheet.x

data ClipDoc? (with constructors Clip_F F) and data Node (with constructors CNode X Path and HoleXNode X Path) are generated. ClipDoc is used as the clipboard for copying a document. A Node is a node in the parse tree, with a Path (::[Int]) that encodes how to get there.

The data types from DocumentTypeDefinition.prx are extended by the generator with HoleX and ParseErrX (Presentation Document Node CLipDoc? UserToken? ). The data constructors are also extended with an IDP (Presentation IDentities) for each token that is needed to present that data constructor. These IDP s can be used to store the whitespace information of the tokens.

[X] is converted to List_X

This makes that the DocumentTypeDefinition.prx definition of

data Exp = PlusExp exp1:Exp exp2:Exp { idP0:IDP }
         | LetExp [Decl] Exp         { idP0:IDP, idP1:IDP }
         | ...

is translated to

data Exp = PlusExp IDP Exp Exp
         | LetExp IDP IDP List_Decl Exp
         | ...
         | HoleExp
         | ParseErrExp (Presentation Document Node ClipDoc UserToken)
            deriving Show

According to $root/generator/src/Main.hs, "Hole and ParseErr? are still a bit hacky. Rather than being added to the datatype, they are added as strings by each of the generator modules. A change on them is therefore hard to realize"

The user defines:

Imports

data Document, data UserToken? , and all data types that appear in a right-hand side in DocumentTypeDefinition.prx (F), but have no data type definition (nor a standard definition, like Int has).

DocumentEdit? _Generated.hs

DocumentEdit? _Generated.hs provides instance definitions for Clip and Editable, dealing with editing (selecting, pasting, placing holes) documents. Also a number of list functions is provided to deal with list fields in the data constructors.

Generated are:

instance Clip ClipDoc? , with definitions for

• arityClip
• alternativesClip
• holeClip
• isListClip
• insertListClip
• removeListClip

instance Editable X Document Node ClipDoc? UserToken? , with definitions for

• select :: PathD? -> X -> ClipDoc?
• paste :: PathD? -> ClipDoc? -> X -> X
• alternatives :: X -> [(String, ClipDoc? )]: alternatives in the context menu to change the current node to (used for empty nodes)
• arity :: X -> Int: number of fields in DocumentTypeDefinition.prx
• parseErr :: Presentation Document Node ClipDoc? , UserToken? -> X
• hole :: X
• isList :: X -> Bool
• insertList :: Int -> ClipDoc? -> X -> ClipDoc?
• removeList :: Int -> X -> ClipDoc?

The user defines:

Imports

instance Editable F Document Node ClipDoc? UserToken? , for a F that has no definition in DocumentTypeDefinition.prx (including Bool, String and Int).

DocUtils? _Generated.hs

Generated are:

XML parsers (:: Parser X):

• parseXML_X for data type X
• parseXMLCns_C for data constructor C

toXMLX :: X -> XML
rankNode :: Node -> Int, used for comparing Nodes
pathNode :: Node -> PathDoc? definitions for instance HasPath? Node, gives the path of that node

For lists of X ([X]) in right-hand sides in DocumentTypeDefinition.prx

• convert [X] to (Cons)List_X, or vice versa
  • {to/from}List_X
  • {to/from}ConsList_X
• replace/insert/remove the nth element in a list
  • replaceList_X
  • insertList_X
  • removeList_X

The user defines:

Imports

instance Doc Document, toXMLF and parserXML_F for all F that have no definition in DocumentTypeDefinition.prx (including Bool, String and Int, but can't these primitives be generated?).

instance DocNode? Node, instance Eq Node, instance Ord Node

• It appears that these can be generated, as all current editors define them the same

Other utility functions, when needed.

PresentationAG? _Generated.ag

Generated is an UUAG file (.ag) that contains the AG DATA type definitions from DocumentTypeDefinition.prx, extended with Hole and ParseErr:

DATA X | C namedID1:IDP ... namedID1:IDP    namedField1:F1 ... namedFieldn:Fn
       | ...
       | HoleX
       | ParseErrX presentation:Presentation_Doc_Node_Clip_Token

SEM and ATTR code is generated to:

• manage the identities for tokens (pIdC : Int).
• compute the path of a node (path : [Int]).
• give a default XML or Tree presentation (pres : Presentation_Doc_Node_Clip_Token, for lists press : [Presentation_Doc_Node_Clip_Token]).
• keep track of the position of the focus (focusD :: FocusDoc? , type FocusDoc? = PathDoc? )

The user defines:

Imports

SEM EnrichedDoc? | F f.path = []

SEM EnrichedDoc? for HoleEnrichedDoc and ParseEnrichedDoc

• Deliberately excluded from SEM generation, but could be generated (when only @lhs.path is replaced by []).

type Presentation_Doc_Node_Clip_Token = Presentation Document Node ClipDoc? UserToken?

• This is used hardcoded, could be generated

presentElement{XML/Tree}

• This is used hardcoded, could be generated. But one might want an alternative representation

presentPrim{XML/Tree}Bool/Int/String

• idem

Functions usually defined in PresentationAG? .ag, but needed by the generated file:

• presHole :: FocusDoc? -> String -> node -> PathD? -> Presentation doc node clip token
• presParseErr :: Xprez doc Node clip token -> Presentation doc Node clip token
• presentFocus :: PathDoc? -> PathD? -> Xprez doc node clip token -> Xprex doc node clip token

ProxParser? _Generated.hs

Usually no manual additions

• reuseC :: [ Token _ Node _ _ ] -> Maybe F1 -> Maybe ... -> Maybe Fn -> X, with the Maybe Fi as the fields in the constructor. It returns a C that contains the Fi if that is a Just, or a value extracted from the Token list if it is a Nothing
  It reuses the old token list to construct a new value.
• extractC :: Maybe Node -> Maybe X, extracts the constructor from a Node
• defaultC :: X, returns a default value for constructor C (a constructor filled with hole s)

The user defines:

Nothing, except the imports

-- GerboEngels - started 18 Feb 2008, ongoing