SpecUI

Generators

Generators serve as the core engine in SpecUI's code generation lifecycle, acting as the conduit between Specifications, Templates, and Engines. Generators are what make the magic happen—they turn your specs into functional code. This section is intended to guide you through the intricacies of Generators in SpecUI, helping you harness their full potential.

What Are Generators?

A Generator in SpecUI is essentially a configurable component that takes Specifications and processes them through Templates using selected Engines. The output is the code you defined, formatted and processed by any associated Processors.

Anatomy of a Generator

A Generator consists of:

  • Templates: Code templates defining the structure of the output.
  • Engines: The engine(s) used to interpret and process the Templates.
  • Processors: Post-generation components that handle tasks like formatting and analysis.

Configuring Generators

Setting up a Generator involves defining it in your SpecUI project's configuration files. Here’s a basic example to demonstrate:

export const ServiceSpecUI: IServiceSpecUI = (spec) => {
  return {
    ['README.md']: ReadmeGenerator({
      /* ... */
    }),
  };
};

In this example, the Generator is named "MyServiceGenerator" and uses a Handlebars template located in the ./templates directory. The Generator will use the Handlebars engine and post-process the output using a "CodeFormatter" Processor.

Built-in and Custom Generators

SpecUI provides a collection of built-in Generators designed for common tasks. If these do not meet your specific requirements, you have the option of creating custom Generators tailored to your project's needs.

Chain of Operations

Generators follow this sequence in the code generation process:

  1. Read the Specifications.
  2. Use the configured Engine to process a Template.
  3. Generate the code.
  4. Apply any configured Processors.

Best Practices

When using Generators, consider the following:

  • Modularity: Build Generators that focus on specific parts of your application. This makes it easier to manage and scale your code.
  • Up-to-Date Specifications: Always keep the Specifications up-to-date to ensure that the Generators produce the correct output.
  • Testing: Frequently test your Generators to ensure they are producing the expected code output.
  • Processor Synergy: Choose Processors that complement your Generator's output. For instance, if your Generator creates TypeScript code, configure a Processor that formats TypeScript code.

By making effective use of Generators, you're enabling SpecUI to serve as a powerful tool for automating and optimizing your codebase, ensuring it remains robust, consistent, and up-to-date.