dartrix 0.1.22-alpha

An Extensible Template Engine for Dart. Comes with a set of builtin templates, and supports extension by "plugin" template libraries.

Dartrix - ALPHA version

An extensible template and tools command-line tool. Dartrix comes with a set of builtin templates to generate scripts, apps, libraries, etc. in multiple languages. It also supports third-party template libraries as "plugins". A sample plugin is available at hello_dartrix.

WARNING: This is an alpha version. A beta version will be available soon.

Table of Contents

• Getting Started
• Dartrix commands
• Plugins
  • Third-Party
  • Local
• Developing Templates and Template Libraries

Getting Started

$ pub global activate dartrix
$ pub global run dartrix:list
$ pub global run dartrix:list dartrix
$ pub global run dartrix:man dartrix -t bashrc
$ pub global run dartrix:new -t bashrc -h
$ pub global run dartrix:new --dry-run -t bashrc
$ pub global run dartrix:new -t bashrc
$ cat ~/.dartrix

Aliases for pub global run dartix:foo are dxfoo, e.g. dxlist.

To use a different alias, create a .dartrix rc file with bash aliases and source it from ~/.bashrc:

$ dxnew dartrix bashrc -h
$ dxnew dartrix bashrc --prefix t

This will create ~/.dartrix containing alias tlist="pub global run dartrix:list $@" etc.

Dartrix Commands

• list - print lists of template libraries and templates
• man - print manpages
• new - generate files from parameterized templates

For template development:

• lint - verifies that all the standard bits are in place, paths are legal, etc.
• update - generate missing docstring files, manpages, and template handlers.

Listings

The list command lists available template libraries and templates.

Sample output for $ pub global run dartrix:list --pubdev:

dartrix:list, version 0.1.0

Usage: dartrix:list [-h] <library>

-p, --[no-]pubdev     Search pub.dev. Default: false
-h, --[no-]help       Print this help message.
-v, --[no-]verbose

Available template libraries:

   Library      Version       Description
   dartrix      0.1.19-alpha  builtin templates
    flutter     0.1.0         Templates for Flutter programs, libraries, etc.
                              path: /Users/joe/dartrixdev/flutter_dartrix
    hello       0.3.0         Templates for Hello World programs in various languages.
                              path: /Users/joe/dartrixdev/hello_dartrix
   *hello       0.1.0         Templates for Hello World programs in various languages.
  **hello       0.2.0         Dartrix template plugin package.  Contains templates for "Hello World" in various programming languages.

*  Installed in local syscache (~/.pub-cache) * Available on pub.dev
** Available on pub.dev

In this example, package hello is listed three times:

• Version 0.1.0 was installed locally
• Subsequently, version 0.2.0 was uploaded to pub.dev
• You are developing version 0.3.0 on your local machine, in $HOME/dartrixdev/hello_dartrix.

Plugins - Template Libraries

You can use third-party template libraries or create your own by adding them as a dependencies in a project pubspec.yaml file.

The drawback of this is that you can only use such tools in the projects where they are explicitly listed. This is the way Dart/Pub tooling works.

Dartrix was written in part to address this issue of the project-dependency of tooling. You can use Dartrix templates anywhere; they have no dependency on project pubspec files. Dartrix uses the standard practice of using a user-specific configuration file stored as a dotfile in the $HOME directory.

Third-Party

Steps to install a template library, say foobar_dartrix:

1. Create ~/.dart.d/pubspec.yaml
2. Add a dependency to the library in the pubspec file.
3. Run $ pub get in ~/.dart.d

The library should now be available to Dartrix tools. Verify this by running dartrix:list; you should see the installed library in the list of available libraries.

Local

You can easily develop and use plugins locally. Just follow the above procedure, but list your local plugins using path: syntax. E.g.

dependencies:
  mytemplates_dartrix:
    path:../mytemplates_dartrix

Developing Templates and Template Libraries

Start by using the builtin template_library template to create a Dartrix template library package.

Detailed instructions for template development are provided in the manpages. The basic rules are:

• The package, the root directory of the package, and the main dart file must be named by the package name suffixed by "_dartrix". For example, a library foobar should look like this:

foobar_dartrix/
    lib/foobar_dartrix.dart
    pubspec.yaml   # with "name: foobar_dartrix

• The file lib/foobar_dartrix.dart must contain a main entry point that handles template requests.
• Template files are written in the {{mustache}} syntax, have a .mustache extension, and are stored in templates/, under the appropriate
• Optional but strongly recommended
  • Template handlers construct the data map and pass it back to Dartrix for merging with the template. Template handler code should go in lib/src and be organized by template, e.g. the handler for template foo should be in lib/src/foo.dart. It would be called from the main routine in lib/foobar_dartrix.dart.
  • Docstrings, stored in templates/ in files with the same name as the template but with suffix .docstring. A docstring file should contain a brief description of the template it documents, suitable for display by the dartrix:list command.
  • Manpages, stored in man/. A manpage should be provided for the library itself and for each template it contains, with corresponding names suffixed by .1. Manpages should provide detailed documentation.

Dartrix contains builtin templates and manpages for each of these artifact types. The dartrix:update command will inspect the list of templates in a project and generate missing docstring files, manpages, and handler code.

For example, if library foobar_dartrix contains templates foo and bar, it will look like this:

foobar_dartrix/
  lib/foobar_dartrix.dart
  lib/src/foo.dart
  lib/src/bar.dart
  man/foo.1
  man/bar.1
  templates/foo/   # contains foo templates and assets
  templates/foo.docstring
  templates/bar/   # contains bar templates and assets
  templates/bar.docstring
  pubspec.yaml

The mechanism is simple: when the user asks for a plugin, Dartrix will search the list of installed plugins (in ~/.dart.d/.packages, which is generated by pub get from pubspec.yaml), and then spawn the selected package, passing the user's args to its main routine. The plugin's job is to construct a data map providing values for the template and pass it back to Dartrix. Dartrix will then instantiate the template.