Skip to content

Latest commit

 

History

History
67 lines (54 loc) · 4.3 KB

design.md

File metadata and controls

67 lines (54 loc) · 4.3 KB
Raw

Design Overview

Basic idea

The architecture around the Stubs Generator plugin has a modular character based on a general observation that any stub generator for an MPS language can be decomposed into the following three parts:

  • A part that constructs some specification of stubs that are to be created. This can be for example a human writing the specification manually or, more expectedly, a program exporting this information from non-MPS libraries.
  • A part that processes this specification, manages the order of generation of individual stubs and creates the MPS entities for the stubs.
  • A part that creates concrete stubs, instances of concepts, based on a specification chunk, which describes the details of the stub to be created.

The second listed part is language-independent whereas the first and the third parts are language-specific. The Stubs Generator encapsulates this second listed part providing as much universal support as possible to the two other parts. These other parts can be viewed as adapters of Stub Generator to a given language and will be further referenced as specification-side adapter (the first part) and language-side adapter (the third part).

Processing overview

The specification-side adapter is expected to produce an XML describing the library entities in a structured form. Although it is not required, the expected design is that each library entity corresponds to a single XML element and these elements are nested in the same way as in the library. E.g. a method is a nested element inside a class element which is a nested element inside a namespace element. Elements are expected to have attributes which describe the properties of the library entity such as names, modifier flags or similar.

Stubs Generator processes this XML and creates a custom in-memory specification model structured as a tree corresponding to the XML tree. Nodes of this tree are instances of a class MpsEntitySpec. Each of this instance is basically a map of properties of the corresponding library entity where the keys are names of these properties (e.g. an XML attribute name) and they map to the values of the properties (e.g. the value of that XML attribute).

Stubs Generator expects to recieve an XML file from the specification-side adapter which describes the stubs which should be created. There are only few requirements for the XML structure:

  • It must contain a DTD.
  • Each element (possibly except special cases agreed by developers of the adapters) must have a mandatory attribute stubId whose value uniquely identifies the stub. For example, a stub for a class java.util.List could have a string java.util.List as a value of this attribute.

Nothing else is required. The details of the structure are important to the language-side adapter and the specification-side adapter but not to Stubs Generator. This is the key power of Stubs Generator: it is universal.

When Stubs Generator recieves the XML file, it parses it to a tree of stub specification structures (MpsEntitySpec class) which are interconnected in the same way as the elements in the XML file. Each MpsEntitySpec corresponds to one element of the original XML.

Then Stubs Generator traverses the tree from the bottom to the top. The reason for this direction is that the parent stubs typically depend on the child stubs. This way the dependencies are efficiently satisfied. It also supports requests of out-of-order generation of a stub, which is used when the language-side adapter needs a stub before it is generated by Stubs Generator.

Each MpsEntitySpec node of the tree is passed to the language-side adapter that is expected to process this particular node and generate a stub for it. It should not generate any other stubs. If it needs references to some other stubs, it should ask the Stubs Generator (specifically, the class MpsEntityCollectionGenerator) for it. It is transparent to the language-side adapter whether the requested stub has or has not been generated yet (this is when the out-of-order generation mentioned before takes place).

All-in-all Stubs Generator provides a helpful support of implementing the core of stubs generation common to all languages. Language-side adapter and specification-side adapter do not have to deal with non-language-specific code which makes them easier to develop.