Creating a Generator

A generator is a GitHub repository that, once registered with Codegen, can be used by anyone to generate text from models. It only needs to be published once, then it can be ran any number of times on the service. There is currently no support for private GitHub repos.

Writing a Generator

A valid generator requires only one file, an Ant build script named build.xml. The rest is up to the developer on how they want to implement generators in Epsilon.

Here is an example build file:

<project name="pacs-java-gen" default="main">
  <description>An XML-to-Java generator</description>
  <!-- #file -->
  <property name="model" value="" description="An XML model"/>

  <target name="loadModels">
    <epsilon.xml.loadModel name="Class" file="${model}" read="true" store="false"/>
  </target>

  <target name="main" depends="loadModels">
    <epsilon.egl src="class.egx" outputroot="${outputRoot}">
      <model ref="Class"/>
    </epsilon.egl>
  </target>
</project>

The format follows the Ant build file rules. Here are some points of interest:

• The project has a name attribute, this is the name of the generator. It also has a default attribute to tell Ant which target to execute first.
• It has a description node which can be used to give users of the generator information on what it does and how it operates.
• It has a property node which describes a parameter the generator user can give when running the generator. In this case, it's a file location for the model the generator uses. The value attribute acts as a default value, which the user can override.

Ant properties will only be taken as generator properties if they are annotated with a comment above them. The comment must contain its type (currently only file or string). It can also contain optional meaning it doesn't have to be specified by the user. Each field must start with a hash, for example:

<!-- #file -->
<property name="model" value="" description="The input EMF model"/>
<!-- #string #optional -->
<property name="mediaOnly" value="false" description="Only generate a page for media in the library"/>

file values must be a valid path on the user's computer so the file can uploaded to the service. string values can be any content.

You can see more generator examples on my GitHub.

Publishing a Generator

Generators are identified by their GitHub owner/name combination. When you're ready, you can publish the generator either via the CLI client, e.g:

> codegen publish robcrocombe/pacs-java-gen

or directly via the API:

POST /service/generators?owner=robcrocombe&repo=pacs-java-gen

If you need to update the generator, simply use the same command to overwrite the previous version.