Brick Oven

Easily create & format brick templates with the brick_oven cli generator for mason

Brick Oven is essentially a "Search & Replace" tool on steroids. It is for cooking (generating) and formatting brick templates for mason.

Quick Start

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

# 🔨 Create & configure the `brick_oven.yaml` file

# 🎛 cook your bricks 🧱
brick_oven cook all

Cook'n Bricks! 👨‍🍳

Cook up a brick template for each configured brick within the brick_oven.yaml file.

There are two main commands to cook your bricks:

# Cooks all bricks
brick_oven cook all

# Cooks a specific brick
brick_oven cook <BRICK_NAME>

Setup the oven 🎛

Use the JSON Schema to help with intellisense and validation

The link to the schema is https://raw.githubusercontent.com/mrgnhnt96/brick_oven/master/schema/brick_oven.yaml.schema.json

If you're using vscode, you can update your project's settings.json to include the schema

{
  "yaml.schemas": {
    "https://raw.githubusercontent.com/mrgnhnt96/brick_oven/master/schema/brick_oven.yaml.schema.json": "brick_oven.yaml"
  }
}

To see some examples of the brick_oven.yaml usage, check out the test/e2e/sources folders

Note for formats and subdirectory variables: When a variable is used as a directory name and it is formatted, the directory slash will be replaced with the format's delimiter.

-- generated by brick_oven --
{{#snakeCase}}{{{path}}}{{/snakeCase}}

-- set the variable `path` to `some/path/to/dir` --

-- Result, generated by mason --
some_path_to_dir

Content Configuration

This is where brick_oven really shines! Because it is a "Search & Replace" tool, you're able to format the "placeholders" within the contents of a file however you'd like.

Note for output directory: The default output directory is bricks, this value can be manipulated with the output argument. The generated content will be placed under BRICK_NAME/__brick__/, this value cannot be changed.

Note for variable names: Because brick_oven is a "Search & Replace" tool, it will replace ALL found occurrences. The var name is found in rename, name, something_name. To avoid this, its recommended to set up your placeholders with a prefix and/or suffix (such as "_") and some sort of case formatting (such as CONSTANT_CASE). Example: _NAME_.

Note for variable ordering: The order of replacing placeholders with their mustache syntax formatted values is: sections, vars, followed by partials. To avoid unintentionally replacing a placeholder with a sub-name (e.g. NAME found in NAMES or _NAME_ found in _MY_NAME_), try using multiple placeholders for the same variable, and ordering the variables in the brick_oven.yaml by length (largest to smallest).

Partials

Partials are a way to reuse a template. brick_oven supports partials nested within folders, however, mason does not yet. brick_oven handles this by re-locating the partials to the root of the project. This means that all partials must have a unique file name.

Syntax Example Output
partials.* partials.hello_world {{> hello_world.dart}}

Accessing partials is by using dot annotation. For example, if you have a partial named hello_world.dart, you can access it by using partials.hello_world (extension is optional)

URLs

URLs are empty text files with no file extension

Sections (Lambdas)

Syntax Example Output Description
section* section_FOO_ {{#_FOO_}} The start of a section
endSection* endSection_FOO_ {{/_FOO_}} The end of a section
invertSection* invertSection_FOO_ {{^_FOO_}} The start of an inverted section

Notes:

  • Sections consume the entire line (start to end, only 1 line). This is helpful if you want to comment out a section based on the language's syntax, or add a helpful description after/before the section
  • Sections do not get formatted. So don't try to format them...
  • Sections are not case sensitive

Built in Variables

There are some keywords to help get the value at the index when iterating over a list

  • _INDEX_VALUE_
  • . (a single period)

Both have the same output of
{{#_FOO_}}{{.}}{{/_FOO_}}

Conditional Sections

Syntax Example Output Description
*if _FOO_if {{#_FOO_}} Start of an if statement
*ifNot _FOO_ifNot {{^_FOO_}} Inverts the if statement
*endIf _FOO_endIf {{/_FOO_}} End of the if statement

Note: Conditional sections not case sensitive

Case Formatting

Available formats, Case formatting syntax is not case sensitive

Syntax Example Output
*snake, *snakecase _FOO_snake, _FOO_snakecase {{#snakeCase}}{{_FOO_}}{{/snakeCase}}

Note: You can NOT format a variable and use it as a section/if statement.

Libraries

brick_oven
domain/brick_oven_yaml
domain/config/brick_config
domain/config/brick_config_entry
domain/config/brick_config_reference
domain/config/brick_oven_config
domain/config/directory_config
domain/config/file_config
domain/config/include_config
domain/config/mason_brick_config
domain/config/name_config
domain/config/partial_config
domain/config/section_config
domain/config/string_or_entry
domain/config/url_config
domain/content_replacement
domain/file_write_result
domain/implementations/brick_impl
domain/implementations/directory_impl
domain/implementations/include_impl
domain/implementations/mason_brick_impl
domain/implementations/name_impl
domain/implementations/partial_impl
domain/implementations/source_impl
domain/implementations/target_file_impl
domain/implementations/url_impl
domain/implementations/variable_impl
domain/interfaces/brick
domain/interfaces/directory
domain/interfaces/include
domain/interfaces/mason_brick
domain/interfaces/name
domain/interfaces/partial
domain/interfaces/source
domain/interfaces/target_file
domain/interfaces/url
domain/interfaces/variable
domain/source_watcher
enums/mustache_section
enums/mustache_tag
utils/brick_cooker
utils/config_watcher_mixin
utils/constants
utils/dependency_injection
utils/extensions/arg_parser_extensions
utils/extensions/brick_oven_runner_extensions
utils/extensions/datetime_extensions
utils/extensions/logger_extensions
utils/file_replacements
utils/oven_mixin
utils/patterns
utils/should_exclude_path
utils/variables_mixin
utils/vars_mixin
utils/yaml_to_json