Skip to content

Writing Masterplans

Jump to bottom
Chris Hall edited this page Mar 8, 2019 · 11 revisions

.masterplan files use a minimal DSL to configure Mastermind and load plan files. For a fully annotated .masterplan see Mastermind's own configuration.

Short example:

at_project_root   # Specifies that this is the root of your project
has_plan_files    # Look for plan files in ./plans/
skip_confirmation # Don't confirm before plan execution.  Identical to -A

# These are functionally equivalent
configure some_value: 'foo'
configure :some_value, 'foo'	

# These are also functionally equivalent
configure(:lazy_load) { "some_value is #{some_value}" }
configure lazy_load: proc { "some value is #{some_value}" }	

define_alias 'short', 'some long command -- with arguments'	

see_also 'path/to/other/masterplan'

Masterplan DSL

project_root [directory]

Specifies the root of your project. Must be specified to prevent Mastermind from scanning more of your file system than it needs to. The easiest way to do this is to just specify at_project_root in a .masterplan file in the actual root of your project.

at_project_root

Syntactic sugar for specifying that the current .masterplan is in the root of your repository.

It's equivalent to project_root __dir__.

plan_files [directory]

Specifies that plan files exist in the given directory. Mastermind will search this directory for any files that end in a supported extension and mark them for loading. By default, Mastermind only supports files with a .plan extension.

has_plan_files

Syntactic sugar for specifying that plans can be found in a plans/ directory in this directory.

It's equivalent to plan_files File.join(__dir__, 'plans').

plan_file filename[, filename[, ...]]

Instructs Mastermind to load the planfiles located at the given filenames.

configure attribute [value] [&block]

Alias: set

This command has two forms that are otherwise identical:

  • configure attribute, value # attribute and value as separate arguments
  • configure attribute: value # attribute and value as key: value of a hash

Used to set arbitrary configuration options. When a configuration option is set in multiple .masterplan files, the "closest" one to your invocation wins. In other words, since Mastermind reads .masterplan files starting in your current directory and working it's way "up" the hierarchy, the first .masterplan that specifies a configuration option "wins".

When provided a block, the value is computed the first time the option is called for. The block runs in the context of the Configuration object built up by all the loaded .masterplan files, so it has access to all previously set configuration options.

The block is only executed once. After that, the value is cached so that it doesn't need to be recomputed.

If both a block and a value are given, the block is ignored and only the value is stored.

define_alias alias_name, alias_command

Defines an alias for a particular command. alias_command can be either an array of plan names or a space separated string of command names. Plan arguments can be included in an alias by placing a -- between the last plan name and the first plan argument (as in the example above).

For more information, see Alias Expansion.

see_also filename

Instructs Mastermind to also load the configuration specified in filename. This file does not have to be named .masterplan but does have to conform to the syntax outlined here.

skip_confirmation

Instructs Mastermind not to ask before executing plans. This setting is identical to passing the -A (--no-ask) flag suppresses confirmation regardless of command line flags. This is intended to be used by users and should not be used in project Masterplans.

Clone this wiki locally