Jump to: navigation, search

Difference between revisions of "FAQ How do I implement a DOM for my language?"

 
(wikify)
 
Line 1: Line 1:
A DOM represents the structure of your programming
+
A DOM represents the structure of your programming language. Its design and implementation are dependent of the target language and follow a few simple guidelines:
language. Its design and implementation are dependent of the target language
+
and follow a few simple guidelines:
+
 
+
* The DOM is hierarchical in nature and  directly represents concrete elements in the
+
program it represents
+
(such as the program itself and its functions, declarations, and statements).
+
</li>
+
 
+
* A DOM is used for defining context for Content Assist
+
(see[[FAQ_How_do_I_add_Content_Assist_to_my_language_editor%3F]].
+
</li>
+
 
+
* A DOM is useful for generating text hovers
+
(see[[FAQ_How_do_I_add_hover_support_to_my_text_editor%3F]].
+
</li>
+
 
+
* Creating outline views without a DOM is difficult
+
(see[[FAQ_How_do_I_create_an_Outline_view_for_my_own_language_editor%3F]].
+
</li>
+
 
+
* A DOM is essential in architecting and implementing support for refactoring
+
(see[[FAQ_How_do_I_support_refactoring_for_my_own_language%3F]].
+
</li>
+
 
+
* A program may be represented with various DOMs. In the case of eScript we have
+
a DOM for describing the program structure and a second DOM for the method bodies.
+
</li>
+
 
+
* A DOM is implemented as a data structure with access API. In the case of eScript, we
+
move Content Assist and text-hover support into the DOM nodes. This makes handling those
+
in the editor very easy.
+
</li>
+
  
 +
* The DOM is hierarchical in nature and  directly represents concrete elements in the program it represents (such as the program itself and its functions, declarations, and statements).
 +
* A DOM is used for defining context for Content Assist (see [[FAQ How do I add Content Assist to my language editor?]].
 +
* A DOM is useful for generating text hovers (see [[FAQ How do I add hover support to my text editor?]].
 +
* Creating outline views without a DOM is difficult (see [[FAQ How do I create an Outline view for my own language editor?]].
 +
* A DOM is essential in architecting and implementing support for refactoring (see [[FAQ How do I support refactoring for my own language?]].
 +
* A program may be represented with various DOMs. In the case of eScript we have a DOM for describing the program structure and a second DOM for the method bodies.
 +
* A DOM is implemented as a data structure with access API. In the case of eScript, we move Content Assist and text-hover support into the DOM nodes. This makes handling those in the editor very easy.
 
* A DOM can be generated in two modes:
 
* A DOM can be generated in two modes:
<P>
+
** The same compiler that also compiles source code can save its abstract syntax tree (AST) and expose it for use by the editor. Using an AST is a pretty standard way to implement a computer language, and piggybacking on that infrastructure makes life a lot easier when writing your editor. This is the way the eScript editor works.
+
** If the underlying AST is not accessible or is to too fine-grained for use in an editor, you may decide to implement a lightweight parser and generate a DOM more efficiently. This is the way the JDT implements its Java model.
+
* The same compiler that also compiles source code can save its abstract syntax tree
+
(AST) and expose it for use by the editor. Using an AST is a pretty standard
+
way to implement a computer language, and piggybacking on that infrastructure
+
makes life a lot easier when writing your editor. This is the way the
+
eScript editor works.
+
</li>
+
 
+
+
* If the underlying AST is not accessible or is to too fine-grained for use in an  
+
editor, you may decide to implement a lightweight parser and generate a DOM more
+
efficiently. This is the way the JDT implements its Java model.
+
+
  
Figure 19.2 shows the inheritance hierarchy for the DOM that was develloped for the eScript&#146;s language.
+
Figure 19.2 shows the inheritance hierarchy for the DOM that was developed for the eScript's language.
 
As you can see, each node in the DOM extends <tt>Element</tt>. It defines  
 
As you can see, each node in the DOM extends <tt>Element</tt>. It defines  
 
the following fields:
 
the following fields:
Line 72: Line 34:
  
 
 
&nbsp;&nbsp;&nbsp;&nbsp;<img src=../images/dom-escript.png>
+
[[Image:dom-escript.png|left|'''Figure 19.2''' Inheritance hierarchy for eScript's DOM]]
 
+
&nbsp;&nbsp;&nbsp;&nbsp;'''Figure 19.2'''&nbsp;&nbsp;
+
Inheritance hierarchy for eScript&#146;s DOM
+
 
 
  
Line 81: Line 40:
 
== See Also: ==
 
== See Also: ==
  
[[FAQ_How_can_I_ensure_that_my_model_is_scalable%3F]]
+
[[FAQ How can I ensure that my model is scalable?]]
  
<hr><font size=-2>This FAQ was originally published in [http://www.eclipsefaq.org Official Eclipse 3.0 FAQs]. Copyright 2004, Pearson Education, Inc. All rights reserved. This text is made available here under the terms of the [http://www.eclipse.org/legal/epl-v10.html Eclipse Public License v1.0].</font>
+
{{FAQ Tagline}}

Latest revision as of 10:30, 19 February 2007

A DOM represents the structure of your programming language. Its design and implementation are dependent of the target language and follow a few simple guidelines:

  • The DOM is hierarchical in nature and directly represents concrete elements in the program it represents (such as the program itself and its functions, declarations, and statements).
  • A DOM is used for defining context for Content Assist (see FAQ How do I add Content Assist to my language editor?.
  • A DOM is useful for generating text hovers (see FAQ How do I add hover support to my text editor?.
  • Creating outline views without a DOM is difficult (see FAQ How do I create an Outline view for my own language editor?.
  • A DOM is essential in architecting and implementing support for refactoring (see FAQ How do I support refactoring for my own language?.
  • A program may be represented with various DOMs. In the case of eScript we have a DOM for describing the program structure and a second DOM for the method bodies.
  • A DOM is implemented as a data structure with access API. In the case of eScript, we move Content Assist and text-hover support into the DOM nodes. This makes handling those in the editor very easy.
  • A DOM can be generated in two modes:
    • The same compiler that also compiles source code can save its abstract syntax tree (AST) and expose it for use by the editor. Using an AST is a pretty standard way to implement a computer language, and piggybacking on that infrastructure makes life a lot easier when writing your editor. This is the way the eScript editor works.
    • If the underlying AST is not accessible or is to too fine-grained for use in an editor, you may decide to implement a lightweight parser and generate a DOM more efficiently. This is the way the JDT implements its Java model.

Figure 19.2 shows the inheritance hierarchy for the DOM that was developed for the eScript's language. As you can see, each node in the DOM extends Element. It defines the following fields:

   int startOffset, endOffset; // source positions
   Hashtable attributes;       // things like ID, label, ...
   ArrayList children;         // children of this element
   Element parent;             // the owner of this element
   String hoverHelp;           // cached value of hover help
   ...more fields....

The subclasses of Element implement useful methods:

   public String getAttributeValue(String name)
   public String getHoverHelp()
   public void getContentProposals(...., ArrayList result)   

For instance, the getHoverHelp method easily allows us to use the DOM to find the element at a given offset and then ask it for what hover help is appropriate.



See Also:

FAQ How can I ensure that my model is scalable?


This FAQ was originally published in Official Eclipse 3.0 FAQs. Copyright 2004, Pearson Education, Inc. All rights reserved. This text is made available here under the terms of the Eclipse Public License v1.0.