mason 0.0.1-dev.53

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

# 🎯 Activate from https://pub.dev
$ dart pub global activate mason

# 🍺 Or install from https://brew.sh
$ brew tap felangel/mason
$ brew install mason

# 🚀 Initialize mason
$ mason init

# 🧱 Use your first brick
$ mason make hello

---

Table Of Contents

• Overview
  • Installation
  • Initializing
  • Command Line Variables
  • Variable Prompts
  • Config File for Input Variables
  • Custom Output Directory
  • File Conflict Resolution
• Creating New Bricks
  • Brick YAML
  • Brick Template
    • Nested Templates (partials)
    • File Resolution
    • Built-in Lambdas
• Adding Bricks
  • Add Usage
• Removing Bricks
  • Remove Usage
• List all available Brick Templates
  • List Usage
• Bundling
  • Bundle Usage
• Complete Usage
• Video Tutorial

Overview

Installation

# 🎯 Activate from https://pub.dev
$ dart pub global activate mason

# 🍺 Or install from https://brew.sh
$ 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 Yyna:

y - yes, overwrite (default)
Y - yes, overwrite this and all others
n - no, do not overwrite
a - append to existing file

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

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

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.

Built-in Lambdas

Mason supports a handful of built-in lambdas that can help with customizing generated code:

Name	Example	Usage
camelCase	helloWorld	{{#camelCase}}{{variable}}{{/camelCase}}
constantCase	HELLO_WORLD	{{#constantCase}}{{variable}}{{/constantCase}}
dotCase	hello.world	{{#dotCase}}{{variable}}{{/dotCase}}
headerCase	Hello-World	{{#headerCase}}{{variable}}{{/headerCase}}
lowerCase	hello world	{{#lowerCase}}{{variable}}{{/lowerCase}}
pascalCase	HelloWorld	{{#pascalCase}}{{variable}}{{/pascalCase}}
paramCase	hello-world	{{#paramCase}}{{variable}}{{/paramCase}}
pathCase	hello/world	{{#pathCase}}{{variable}}{{/pathCase}}
sentenceCase	Hello world	{{#sentenceCase}}{{variable}}{{/sentenceCase}}
snakeCase	hello_world	{{#snakeCase}}{{variable}}{{/snakeCase}}
titleCase	Hello World	{{#titleCase}}{{variable}}{{/titleCase}}
upperCase	HELLO WORLD	{{#upperCase}}{{variable}}{{/upperCase}}

Example Usage

Given the following example brick:

__brick__
  ├── {{#snakeCase}}{{name}}{{/snakeCase}}.md
  └── {{#pascalCase}}{{name}}{{/pascalCase}}.java

brick.yaml:

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

We can generate code via:

$ mason make example --name my-name

The output will be:

├── my_name.md
└── MyName.java

Adding Bricks

The add command allows developers to add brick templates locally or globally on their machines from either a local path or git url. By default mason add will add the template locally but bricks can be added globally by providing the --global (-g) flag.

Add Usage

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

# add from path (global)
$ mason add --global --source path ./path/to/brick

# add from path shorthand syntax
$ mason add ./path/to/brick

# add from path shorthand syntax (global)
$ mason add -g ./path/to/brick

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

# add from git url (global)
$ mason add -g --source git https://github.com/user/repo

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

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

Once a brick is added it can be used via the mason make command:

$ mason make <BRICK_NAME>

Removing Bricks

Bricks can be removed by using the remove command. Use the --global (-g) flag to remove global bricks.

Remove Usage

# remove brick
$ mason remove <BRICK_NAME>

# remove brick (global)
$ mason remove -g <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 Usage

# 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

Bundle Usage

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 programmatically:

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

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

Complete 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:
  add         Adds a brick from a local or remote source.
  bundle      Generates a bundle from a brick template.
  cache       Interact with mason cache.
  get         Gets all bricks in the nearest mason.yaml.
  init        Initialize mason in the current directory.
  list        Lists all available bricks.
  make        Generate code using an existing brick template.
  new         Creates a new brick template.
  remove      Removes a brick.

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