Jedi Research

1
Jedi Research

• Roberto E. Lopez-Herrejon
• February 27, 2003

2
Overview

• General Problem
• Jedi in Particular

3
Domain Specific Languages

• DSL are
• Concrete and Simple
• Exploit domain specific knowledge
• Easier to maintain

4
Why DSL are not mainstream?

• Limited IDE tool support
• No debugger, document generators, etc
• Changes in DSL imply painful code update
• Implementation is hardwired

5
Approach

• Adding or modifying DSL grammars impact in
  regular ways the code that handles them
• Use of compositional software approach can
  alleviate the impact

6
General View
Tool2
Tool3
Tool4
Tool1
DSL1
DSL2
DSL3
DSL4
DSL5
7
Closer Look ?
DSL Tool
DSL Grammar
Concern2
Concern3
Rulea
Concern1
Ruleß
Rule?
8
So

• The challenge is in
• Identifying the relationships between grammar
  rules and concerns in the tools
• Abstracting such relationships
• Use them to facilitate the development of tools
  that support DSLs
• Automatic generation of concerns (or pieces)
• Limits the impact of grammar changes
• Eases the addition of new DSL

9
Jedi in Particular

• Exemplify the approach with Jedi
• Goals
• Architecture (a.k.a concerns)
• Grammar-Architecture relationships
• What are these?
• How can they be used?

10
Jedi Goals

• Goals of Jedi are to provide support for
• Different languages and DSL
• Currently Java (Jakarta) and Ahead DSL
• Different types of comment structures
• Currently only portions of Javadoc tags
• Generation of different types of documents
• Currently Classes, Interfaces, State Machines
• Different document formats
• Currently only HTML

11
Interacting Problems to Solve

• Structure Extraction
• Comment Extraction
• Document Composition
• Document Formatting

12
Jedi Architecture

• Each language feature extension have
• Parser
• Parses the corresponding language constructs
• Harvester
• Collects information spread across several nodes
• Comment Repository
• Comment information from particular structures
• Comment Harvester
• Parses a comment and stores info into repository
• Documents
• Declares what documents to create or refine

13
Diagram of Jedi Architecture
14
How Grammar Rules relate to Jedi Concerns

• Parser
• Generated from the grammar
• Harvester
• Rules capture important information that is
  spread along several nodes
• Docs
• Rules add contents to the documents that are
  generated

15
Example Grammar Rules
AST_FieldDecl ( ClassBodyDeclaration
) ClassBodyDeclaration Initializer
NestedClassDeclaration NestedInterfaceDeclarat
ion ConstructorDeclaration
MethodDeclaration FieldDeclaration
16
Harvester and Grammar Rules
AST_FieldDecl
Nodes are Method, Field, Constructor, Nested
Class, Nested Int
Harvesters can be generated
17
Jedi Annotations

• Extensions to the Bali grammar
• Add functionality to parse tree nodes
• Goals
• Collect information spread along multiple nodes
• Aggregate context for document generation
• Create structures for cross-referencing

18
Annotation Examples
AST_FieldDecl ( ClassBodyDeclaration is
NestedClassDeclaration -gt
NestedClassList NestedInterfaceDeclaration
-gt NestedInterfaceList
ConstructorDeclaration -gt ConstructorList
MethodDeclaration -gt
MethodList FieldDeclaration
-gt FieldList )
Meaning Aggregates lists for different class
body elements
19
Annotation Example
ImportDeclaration Value ltAST_QualifiedNamegt
ltDotTimegt
Meaning Concatenates two strings and assign it
to Value
20
Annotation Examples
AST_ParList Parameters.Elem.FormalParamenter
FormalParameter
(Parameters.Elem.FormalParameter
FormalParameter)
Meaning Create Parameters list of
FormalParameter objects
21
Jedi Annotations Manipulation
.b
Base Bali Grammar
Bali Composer
Jedi Annotation
.b
.b
Composite Grammar
jedi2?
Harvester
22
Grammar Rules and Documents
lthtmlgt Class MyClass fields summary
methods summary constructors summary
nested classes nested interfaces details
lt/htmlgt
AST_FieldDecl A Class Document
23
Grammar Rules and Documents

• How to express the relationship between a rule
  and a document ?

• Answer
• Document template

24
Important Distinctions

• Document
• Examples HTML file with info of a class
• Document template
• Unit of composition of documents
• Document static and dynamic contents
• Document equation
• Expresses how document templates form templates
  of documents

25
Key Ideas

• Idea Treat documents as refinements
• Document templates class refinements with
  methods that can be refined
• Document equations type equations

26
Document Templates Description

• A template requires
• Name
• Exported Type
• Typed Insertion Points what kinds of templates
  and where can be added
• Imports clauses define variables used to provide
  contents and the nodes in the parse tree from
  where to get them

27
Document Template Example
ltdocument name"ClassCore"gt ltexports
type"body"/gt ltimports var"class"
node"UnmodifiedClassDeclaration"/gt ltinsert
type"typemods"/gt lt!CDATA class.getName()
nbsp gt ltinsert type"class_head"/gt ltinsert
type"summary"/gt ltinsert type"details"/gt lt/docume
ntgt
28
Pictorial View
ClassCore
Insertion Points
Class . ClassCore .
29
Document Template Example
ltdocument name"FieldSummary"gt ltexports
type"summary"/gt ltimports var"ast_field"
node"AST_FieldDecl"/gt lt!CDATA set
(listFields ast_field.getFieldList()) some
html code here gt lt/documentgt
30
Pictorial View
ClassCore
Class . FieldSummary (ClassCore) .
31
Document Template Example
ltdocument name"FieldDetails"gt ltexports
typedetails"/gt ltimports var"ast_field"
node"AST_FieldDecl"/gt lt!CDATA set
(listFields ast_field.getFieldList()) some
html code goes here gt lt/documentgt
32
Pictorial View
ClassCore
Class FieldDetail( FieldSummary (ClassCore ))
33
Recap

• Each document template roughly corresponds to a
  class refinement
• Adds methods to be refined
• Each insertion point is analogous to a signature
  definition where refinements can be hooked
• But
• We are adding class refinements to methods ?

34
Document Equations
Java
Class.doceq
Interface.doceq
Sm
StateMachine.doceq
Class.doceq

Class.doceq
Java Sm
StateMachine.doceq
Interface.doceq
35
Document Equation Format

• term1 file1 qualifier1
• term2 file2 qualifier2
• .
• termn filen qualifiern

• Term
• names of document templates
• File
• File associated to a document (with path)
• Qualifier
• For composition where to put the term in relation
  with other terms
• Syntax
• before after term

DocumentName termn termn-1 term1
36
Document Templates Composition
Velocity Template
Document Equation
Bindings List
Doc Composer
Doc Templates
37
On the meaning of Composition

• Composition of documents is different from
  default standard composition of AHEAD
• Uses before and after
• A single unit can refine more that one insertion
  point
• Why? I think is due to the granularity we are
  dealing with

38
Mapping from Parse Tree to Document Template
Document Types
Parse Tree
39
Other issues

• Comment structure should be based also in a
  declarative spec and should be added in the
  equation
• The corresponding repository should be inferred
  from the same spec

40
To Do List

• Alignment to AHEAD model
• Build prototype of Document Composer
• With Jack discuss the annotations implementation
• Comment handling generated from a declarative
  spec
• Study Reform