widl-template: WIDL Handlebars Templater

This library and CLI utility allows you to pass serialized WIDL to a Handlebars template for code generation, automatic documentation, linking, etc.

Installation

$ npm install widl-template

Usage

On the command line:

$ widl-template

In JavaScript

const { render } = require('widl-template');

const widlSrc = // string of WIDL
const templateSrc = // string of Handlebars template source

const renderedTemplate = render(widlSrc, templateSrc);

console.log(renderedTemplate);

Data format

Use the WIDL validator's AST view to visualize the structure of the WIDL data.

Notes: Minor AST changes

This utility uplevels the first namespace and interface it finds to the tree's root so you can more easily access them in your templates.

Partials

Register all .hbs files in a directory as partials by using the registerPartials() function or by passing a directory to the CLI via -p or --partials

import { registerPartials } from 'widl-template';

await registerPartials('partialsdir');

Helpers

This library includes two helpers to help templating from the command line:

isKind

A conditional block that tests the kind of WIDL node

{{#isKind 'TypeDefinition'}}
  # Type:
  {{name.value}}
{{/isKind}}

join

The join maps over ever element with the passed block and joins them with the supplied separator.

({{#join parameters ', '}}{{name}}:{{type}}{{/join}})

Given parameters of [{name: 'someName', type:'someValue'},{name: 'someName2', type:'someValue2'}], the join above would output:

(someName: someValue, someName2: someValue2)

camelCase

capitalCase

constantCase

dotCase

headerCase

noCase

paramCase

pascalCase

pathCase

sentenceCase

snakeCase

Case-related helpers that expose functions from change-case-all e.g.

{{pascalCase context}}

upperCase

lowerCase

Uppercase & lowercase helpers that transform an entire string

{{upperCase context}}

import block

Import another widl file

{{#import 'other/file.widl'}}
  # Hello from
  {{namespace.name.value}}
{{/import}}

dirname

Exposes Node.js's path.dirname.

{{dirname value}}

basename

Exposes Node.js's path.basename.

{{basename value}}

replace

Simple string replacement helper.

{{replace original '.js' ''}}

switch/case/default

An implementation of switch/case statements as handlebars helpers.

{{#switch kind}}
  {{#case 'A'}}
    First block
  {{/case}}
  {{#case 'B'}}
    Second block
  {{/case}}
  {{#default}}
    Default block
  {{/default}}
{{/switch}}

eachWithName

A block that iterates over every object in a passed list that has a name property equal to the passed name. Used to iterate over fields or definitions to find a specific name

{{#eachWithName definitions 'MyType'}}
  Some description specific to MyType
{{/eachWithName}}

codegen-type

This is a partial code generator that turns a WIDL type node (i.e. from a field or argument, not a TypeDefinition) back into a WIDL string.

{{#each fields}}
  {{name.value}} : {{codegen-type type}}
{{/each}}