mason 0.0.1-dev.46

A Dart template generator which helps teams generate files quickly and consistently.

---

Mason allows developers to create and consume reusable templates called bricks.

Quick Start

Installing

# Activate from pub.dev
$ dart pub global activate mason

# Or install using Homebrew
$ brew tap felangel/mason
$ brew install mason

Initializing

$ mason init

mason init initializes the Mason CLI in the current directory.

Running mason init generates a mason.yaml and an example brick so that you can get started immediately.

bricks:
  hello:
    path: bricks/hello

To get all bricks registered in mason.yaml run:

$ mason get

Then you can use mason make to generate your first file:

$ mason make hello

Command Line Variables

Any variables can be passed as command line args.

$ mason make hello --name Felix

Variable Prompts

Any variables which aren't specified as command line args will be prompted.

$ mason make hello
name: Felix

Config File for Input Variables

Any variables can be passed via a config file:

$ mason make hello -c config.json

where config.json is:

{
  "name": "Felix"
}

The above commands will all generate HELLO.md in the current directory with the following content:

Hello Felix!

Custom Output Directory

By default mason make will generate the template in the current working directory but a custom output directory can be specified via the -o option:

$ mason make hello --name Felix -o ./path/to/directory

File Conflict Resolution

By default, mason make will prompt on each file conflict and will allow users to specify how the conflict should be resolved via Yna:

Y - overwrite (default)
n - do not overwrite
a - overwrite this and all others

A custom file conflict resolution strategy can be specified via the --on-conflict option:

# Always prompt when there is a file conflict (default)
$ mason make hello --name Felix --on-conflict prompt

# Always overwrite when there is a file conflict
$ mason make hello --name Felix --on-conflict overwrite

# Always skip when there is a file conflict
$ mason make hello --name Felix --on-conflict skip

Creating New Bricks

Create a new brick using the mason new command.

$ mason new <BRICK_NAME>

The above command will generate a new brick in the bricks directory with a brick.yaml and __brick__ template directory.

Brick YAML

The brick.yaml contains metadata for a brick template.

name: example
description: An example brick
vars:
  - name

Brick Template

Write your brick template in the __brick__ directory using mustache templates. See the mustache manual for detailed usage information.

__brick__/example.md

# Hello {{name}}!

❗ Note: __brick__ can contain multiple files and subdirectories

❗ Note: use {{{variable}}} instead of {{variable}} when you want the value of variable to be unescaped

Nested Templates (partials)

It is possible to have templates nested within other templates. For example, given the follow structure:

├── HELLO.md
├── {{~ footer.md }}
└── {{~ header.md }}

The {{~ header.md }} and {{~ footer.md }} are partials (partial brick templates). Partials will not be generated but can be included as part of an existing template.

For example given the contents of {{~ header.md }} and {{~ footer.md }} respectively

# 🧱 {{name}}

_made with 💖 by mason_

we can include the partials as part of a template via {{> header.md }} and {{> footer.md }}.

In this example, given HELLO.md:

{{> header.md }}

Hello {{name}}!

{{> footer.md }}

We can use mason make hello --name Felix to generate HELLO.md:

# 🧱 Felix

Hello Felix!

_made with 💖 by mason_

❗ Note: Partials can contain variables just like regular templates

File Resolution

It is possible to resolve files based on path input variables using the {{% %}} tag.

For example, given the following brick.yaml:

name: app_icon
description: Create an app_icon file from a URL
vars:
  - url

And the following brick template:

__brick__/{{% url %}}

Running mason make app_icon --url path/to/icon.png will generate icon.png with the contents of path/to/icon.png where the path/to/icon.png can be either a local or remote path. Check out the app icon example brick to try it out.

Install Brick Templates Globally

The install command allows developers to install brick templates globally on their machines from either a local path or git url. Then developers can use globally installed brick templates anywhere (regardless of whether there is an existing mason.yaml).

Install Usage

# install from path
$ mason install --source path ./path/to/brick

# install from git url
$ mason install --source git https://github.com/user/repo

# install from git url with path
$ mason install --source git https://github.com/user/repo --path path/to/brick

# install from git url with path and ref
$ mason install --source git https://github.com/user/repo --path path/to/brick --ref tag-name

# use alias "i" instead of "install" for a shorthand syntax
# since git is the default source we don't need to specify a source.
$ mason i https://github.com/user/repo

Once a brick is installed globally it can be used from anywhere via the mason make command:

$ mason make <BRICK_NAME>

Uninstall Brick Templates

Bricks can be uninstalled by using the uninstall (un for short) command.

Uninstall Usage

# uninstall brick
$ mason uninstall <BRICK_NAME>

# use alias "un" instead of "uninstall" for a shorthand syntax
$ mason un <BRICK_NAME>

List all available Brick Templates

All available brick templates (local and global) can be seen via the list (ls for short) command.

# list all available bricks
$ mason list

# use alias "ls" instead of "list" for a shorthand syntax
$ mason ls

Bundling

You can use mason to generate a bundle for an existing template. Bundles are convenient for cases where you want to include your template as part of a standalone CLI. Very Good CLI is a great example.

There are currently two types of bundles:

1. Universal - a platform-agnostic bundle
2. Dart - a Dart specific bundle

To generate a bundle:

# Universal Bundle
mason bundle ./path/to/brick -o ./path/to/destination

# Dart Bundle
mason bundle ./path/to/brick -t dart -o ./path/to/destination

A bundle can then be used to generate code from a brick programatically:

// Create a MasonGenerator from the existing bundle.
final generator = MasonGenerator.fromBundle(...);

// Generate code based on the bundled brick.
await generator.generate(...);

Usage

$ mason
⛏️  mason • lay the foundation!

Usage: mason <command> [arguments]

Global options:
-h, --help       Print this usage information.
    --version    Print the current version.

Available commands:
  bundle      Generates a bundle from a brick template.
  cache       Interact with mason cache.
  get         Gets all bricks.
  init        Initialize mason in the current directory.
  install     Installs a brick globally.
  list        Lists all available bricks.
  make        Generate code using an existing brick template.
  new         Creates a new brick template.
  uninstall   Uninstalls a brick globally.

Run "mason help <command>" for more information about a command.

Video Tutorial

Say HI to Mason Package! - The Top Tier Code Generation Tool | Complete Tutorial by Flutterly