mask

mask-parser is a library designed to parse files written in the maskfile.md format.

Note: This library is currently unstable and its API is subject to change.

Arguments are injected into the script's scope as environment variables.

• Required Positional Arguments: Defined using (name) next to the command heading. These must be supplied for the command to run.
• Optional Arguments: Defined using [name] next to the command heading.

Example (Required):

## test (file) (test_case)

> Run tests

```bash
echo "Testing $test_case in $file"
```

Example (Optional):

## test [test_file]

> Run tests

```bash
if [[ -n "$test_file" ]]; then
    echo "Run tests in $test_file..."
else
    echo "Running all tests...."
fi
```

When mask executes a script, it injects two environment variables that help with location-agnostic execution and file referencing:

• $MASK: The path to the mask binary. This is useful for calling mask from within a script (e.g., $MASK command) without needing to know the exact path or use mask --maskfile <path> command. This is particularly helpful for global maskfiles.
• $MASKFILE_DIR: The absolute path to the directory containing the maskfile. Use this to load external files relative to the maskfile itself.

Subcommands are created by nesting Markdown headings. Top-level commands use H2 (##), and subcommands use subsequent levels (H3 ###, etc.).

Example:

## services

> Commands related to starting and stopping services

### start (service_name)

> Start a service.

```bash
echo "Starting service $service_name"
```

### stop (service_name)

> Stop a service.

```bash
echo "Stopping service $service_name"
```

To run these, use the hierarchy: mask services start <name>.

Use the format task to ensure source code adheres to the project's formatting standards.

Options:

• --check or -c: Instead of applying formatting, this flag checks if files are correctly formatted and reports any discrepancies.

cargo fmt

Project specific tasks

Replace unwieldy Makefiles or scattered development scripts with a single, readable maskfile.md that your team can easily modify.

Global system utility

You can create a global CLI for system tasks (like backups or file renaming) by using a central maskfile and creating a bash alias:

# Create an alias for a global maskfile
alias wask="mask --maskfile ~/my-global-maskfile.md"

# Use it from anywhere
wask <subcommand>

To test changes made to the mask source code, you can use the run task. This command uses cargo run to build and execute mask in development mode. You must have a maskfile in your current directory and provide a valid command (maskfile_command) defined within that file.

Example: mask run "test -h" — this outputs the help information for the test command defined in the maskfile.

Options:

• --watch or -w: Rebuild the project automatically whenever a .rs file changes using watchexec.

mask is a CLI task runner that uses a maskfile.md located in your current directory to define commands. The maskfile.md serves as both human-readable documentation and a command definition file.

Command Structure

• Command Name: Defined by a Markdown heading (e.g., ## build).
• Description: Defined by a Markdown blockquote (e.g., > Builds my project).
• Script: Defined by a fenced code block (e.g., ```sh ... ```).

Running Commands

Once your maskfile.md is defined, run commands using the mask CLI:

mask build
mask test

# Tasks For My Project

## build

> Builds my project

```sh
echo "building project..."
```

## test

> Tests my project

```js
console.log("running tests...")
```

Execute the project's test suite using the test task. By default, this runs all tests.

Options:

• --file or -f <string>: Run tests from a specific integration test filename only.

Verbose Mode: If the verbose environment variable is set to true, tests will run linearly (one thread at a time) and capture/output logs directly to the console using --nocapture and --test-threads=1.

If you want to test your local development version of mask as if it were the system-installed version, use the link task. This installs the version located in the ./mask directory to your cargo bin path, forcing an overwrite of any existing installation.

cargo install --force --path ./mask

To create an optimized release build of the mask binary, use the build task which invokes Cargo's release build command.

cargo build --release