Quick start

This guide explains how to set up a code generation project step-by step. If you haven't installed Yellicode yet, first check out installation section.

Yellicode is template-driven. At a minimum, your project has a Yellicode template (which is a TypeScript file) and a configuration file named codegenconfig.json which tells Yellicode which template(s) to use. There are several ways in which your template can generate code. You can combine these methods in a single setup.

  • I - without a model
  • II - with a JSON file as model
  • III - with a UML mode

I - A basic Yellicode template (without a model)

In this step, you will learn how to create and run the most basic Yellicode template. The template only creates a simple text file and does not use any model as input.

  1. Create a new directory with the name yellicode-quickstart.
  2. Open a command prompt in this directory and create a package.json file by entering:
    npm init -y
  3. Then, install the Yellicode Templating NPM package as a development dependency:
    npm install @yellicode/templating --save-dev
  4. Now, using your favorite IDE or text editor, create a new TypeScript file named quickstart.template.ts and insert the following lines:
    import { Generator, TextWriter } from '@yellicode/templating';
    
    Generator.generate({outputFile: './quickstart-output.txt'}, (writer: TextWriter) => {
        writer.writeLine(`File generated by Yellicode at ${new Date().toISOString()}`);
    });    
    

    Did you notice the enclosing backticks (` `) in our writeLine call? These create a so called template literal. As the name already suggests, they are very useful Javascript concept that keep your templates readable. You will find them a lot in Yellicode templates.

  5. Then, in the same directory, create a file named codegenconfig.json and insert the following JSON code:
    {
        "templates": [
            {
                "templateFile": "./quickstart.template.ts"
            }
        ],
        "compileTypeScript": true
    }
    
  6. Now let's run the template using the Yellicode CLI. Open your command prompt in the same directory and enter the following command:
    yellicode --watch

That's it. You should now have a new file named quickstart-output.txt. Thanks to the --watch argument, any changes you make to the template will be visible in the output as soon as you save them.

If you have some TypeScript experience, you may have noticed that we created a TypeScript file but haven’t created any tsconfig.json file. This is because Yellicode compiles TypeScript using an internal configuration. Generally, you don’t need to worry about this. If you want to disable this or need a custom configuration, see configuring TypeScript compilation.

II - Generate code from a JSON file (OpenAPI)

Let's create something with more potential. Say that you've received a JSON file according to the OpenAPI specification and you need to turn that file into code (or, into API documentation, for that matter). The following template does just that (well, it's oversimplified and generates a .txt file, but you get the point). It uses this petstore example file as model.

import { Generator, TextWriter } from '@yellicode/templating';  
          
Generator.generateFromModel({ outputFile: './openapi.template-output.txt' }, (writer: TextWriter, model: any) => {
    writer.writeLine(`API description of '${model.host}', generated from 'petstore-minimal.json' at ${new Date().toISOString()}.`);      
    // List GET paths
    writer.writeLine();
    writer.writeLine('Paths:');
    for (const path in model.paths) {
        const value = model.paths[path];
        if ('get' in value) {
            const get = value['get'];
            writer.writeLineIndented(`GET '${path}' (${get.produces})`);
            writer.writeLineIndented(get.description);
        }
    } 
    // List definitions
    writer.writeLine();
    writer.writeLine('Definitions:');
    for (const definition in model.definitions) {
        const value = model.definitions[definition];
        writer.writeLineIndented(`${definition} (${value.type})`);        
        if ('properties' in value) {
            const properties = value['properties'];
            for (const prop in properties) {
                writer.writeLineIndented(`- ${prop} (${properties[prop].type})`);
            }
        }
    } 
});        

For using the example file, the codegenconfig.json file should look as follows:

{
    "compileTypeScript": true,
    "templates": [
        {
            "modelFile": "petstore-minimal.json",
            "templateFile": "openapi.template.ts"
        }
    ]
}    

III - Adding a simple class model

Now, let's extend our basic template from section I a bit so that it works with an actual class model. To do so, we will create a new UML model and add a class to it. If you haven't yet, you will need to install Yellicode Modeler first.

  1. Open Yellicode Modeler.
  2. Choose File -> New.
  3. In the explorer pane, right click and choose New Element -> Class.
  4. In the Name input, enter TodoItem (we won't use Visibility for now).
  5. The TodoItem opens. In the Attributes list, click the + sign to add a new attribute.
  6. In the Name input, enter "Title".
  7. The Title properties pane opens. In the Type input, select string.
  8. Choose File->Save and save the file as quickstart-model.ymn in yellicode-quickstart directory.

Now you've got a model, let's extend the template to work with it. In the command prompt, enter:

npm install @yellicode/elements --save-dev

Then open quickstart.template.ts and replace its contents with the following:

import { Generator, TextWriter } from '@yellicode/templating';
import * as elements from '@yellicode/elements';

Generator.generateFromModel({outputFile: './quickstart-output.txt'}, (writer: TextWriter, model: elements.Model) => {
    writer.writeLine('File generated by Yellicode at '+new Date().toISOString());
    model.getAllClasses().forEach((c) => {
        writer.writeLine(`Class: ${c.name} has the following attributes:`);
        writer.increaseIndent();
        c.ownedAttributes.forEach(att => {
            writer.writeLine(`${att.name} (${att.getTypeName()})`);
        });
        writer.decreaseIndent();
    })
});     

As the last step, extend codegenconfig.json with the new model as follows:

{
    "templates": [
        {
            "templateFile": "./quickstart.template.ts",
            "modelFile" : "./quickstart-model"
        }
    ],
    "compileTypeScript": true
}    

Now run the yellicode command again:

yellicode --watch

This will run the template with our new model and update quickstart-output.txt with some information about the TodoItem class.

In this documentation, we end each template name with .template.ts. This is a convention that you don't need to follow, but it will come in handy if your project also contains other TypeScript code. For more info, see using Yellicode in a TypeScript project.

Of course, this isn't a real world example that generates any usable source code, but this is all you need to understand the basics. Next, you might want to have a look at the documentation section, or jump directly to tutorial for more advanced examples using C# and TypeScript.

Continue to the Tutorial »