% XYZ Language Plug-in README

The org.eclipse.photran.xyzsamplelang project demonstrates
how to use the \texttt{AdditionalLanguages} extension point.
It is just the sample XML editor plug-in that gets created when you choose
to create a new plug-in project and select the ``plug-in with an editor''
template.  However, it has been modified to integrate with the CDT.
Here is the README from that project, which is a cursory description of
how the CDT was modified and how the XYZ language was integrated.  The
specific changes to the editor are documented in its code, so be sure
to read that too!

\begin{verbatim}
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *


   HOW TO TIE A NEW SOURCE FILE TYPE, PARSER, AND MODEL BUILDER INTO THE CDT
                     (AND HOW TO MAKE THE CDT ALLOW IT)


* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *

If you create your own editor, model builder, and ICElement-derived elements,
some simple changes to the CDT source code will make the CDT
integrate your parser and the elements it produces into its model.

We add an AdditionalLanguages extension point to the CDT Core and change a
couple of methods to make use of it.

* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *

NOTE ON INCLUDED SOURCE CODE:

All files in the CDT Integration Proof-of-Concept - Phase 1 source folder were
generated by the New Plug-In wizard EXCEPT:

- Several changes were made to the editor's main class (XyzLanguageEditor) and
  are commented there
- I added FortranContentOutlinePage
- I added the ToyElement and ToyModelBuilder classes (based on Photran's
  FortranElement hierarchy and its (hidden) ToyModelBuilder)
- I added XyzLanguagePerspective, which gives us our own perspective and adds
  a shortcut for our new file wizard to the New File menu

* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *

This is NOT well-written, and it is NOT a tutorial.  It assumes you have some
idea of how the CDT works (e.g., what the Model is), and it assumes that you
will look at my code to see all the details.

The XYZ Sample Language code is documented, so that should be read in addition
to this README.

* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *

First, I checked out the CDT source (most of it, anyway) from CVS.

I created a basic editor and a New wizard to complement it
using the New Plugin wizard.  I just called it XyzLanguageEditor
rather than XMLEditor or whatever the default is.  The filename extension
is .xyz.

I added the CDT Core and UI plugins as dependencies of my new plugin.

After the wizard finished, I declared an xyzSource content type (text) to
match the .xyz filename extension that the editor uses.

(I also created an XYZ Language perspective by subclassing CPerspective, although
that has only cosmetic value and isn't necessary for what I describe below.)

-----

Before we can add additional languages to the CDT, we must make the following
changes to the CDT itself:

Add an AdditionalLanguages extension point to the Core's plugin.xml
Add AdditionalLanguages.exsd to the Core's schema folder
Add org.eclipse.cdt.core.addl_langs package to the Core's src folder, containing:
	IAdditionalLanguage -- Each extension language must implement this
	AdditionalLanguagesExtension.java -- Provides access to extension point; iterable
	AdditionalLanguagesIterator.java -- Iterates through contributed IAdditionalLanguages
	IAdditionalLanguageCallback -- For performing an action on each contributed language
	IModelBuilder -- Extension languages provide their model builder this way
	IAdditionalLanguageElement -- ICElement extensions must implement this

Now we need to make the CDT recognize our additional content types as 
valid TranslationUnits in its model.

These changes make sure CoreModel#getRegistedContentTypeId works for
additional content types.  This function is called by CContainer
and, if it returns a valid (registerd-with-the-CDT) content type,
makes a TranslationUnit out of the file being processed.

Essentially, we just add a line or two to each of the following which asks the
AdditionalLanguagesExtension to check whether some extension plug-in (like our
XYZ Language Plug-in) supports a given content type.

	1.	CoreModel#getRegistedContentTypeIds
	2.	CCorePlugin#getContentType
	3.	TranslationUnit#isSourceUnit
	4.	CoreModel#isValidSourceUnitName
	5.	CoreModel#isValidTranslationUnitName

	NOTE:
	The following are places where the CCorePlugin.CONTENT_TYPE_CSOURCE
	content type is checked for but I elected not to check for
	extension content types:
		TranslationUnit#isCLanguage
		CoreModel#isValidCSourceUnitName
		AbstractIndexerRunner#shouldIndex
			...the following two methods are identical...
		DOMSearchUtil#getLanguage
		InternalASTServiceProvider#getLanguage

Next, we want to allow additional languages to be parsed by their own parser,
and they should be able to build their own models for the Outline and Make
Projects views.

The CModelBuilder is called by TranslationUnit#parse.  We will make
TranslationUnit#parse call our own model builder (ToyModelBuilder), which
will use some special ICElements (base class ToyElement) to extend the C Model.
Again, this is done through the extension point, so it can apply to any language.

- CModelBuilder changed to implement IModelBuilder
- Added extension point checking to TranslationUnit#parse
- Made CElementInfo public (rather than default)
- Made CElementInfo#setIsStructureKnown public (rather than protected)
- Added extension point checking to CElementImageProvider#getBaseImageDescriptor

The last point is important.  Additional languages can reuse the CDT's model elements
(for functions, classes, etc. -- all the things that show up in the Outline), or
they can create their own (e.g., Fortran has Modules and Block Data, neither of
which have direct analogs in C/C++).  These new elements can be created by implementing
IAdditionalLanguageElement.  IAdditionalLanguageElements must implement a
method getBaseImageDescriptor() which provides an Outline icon for that element.

-----

To integrate our XYZ language into the CDT...

First, we add the following to our plugin.xml:

   <extension point="org.eclipse.cdt.core.AdditionalLanguages">
      <language class="addl_langs.XYZLanguage"/>
   </extension>

We provide a class addl_langs.XYZLanguage which implements IAdditionalLanguage.
See the JavaDoc for IAdditionalLanguage.  Essentially, we claim to support
the XyzLanguagePlugIn.xyzSource content type, and we provide a ToyModelBuilder
which will provide a (static, and very boring) Outline of XYZ Language source files.

Next, I added Outline support to the editor by making a tiny subclass of
CContentOutlinePage.  See several relevant notes in XyzLanguageEditor.java.
See also FortranContentOutlinePage.  We are telling CContentOutlinePage
its editor is null, since it doesn't do anything useful with it.
\end{verbatim}