Work with emhcl

After this page, you can:

run the edit loop: format, validate, read, fix, and render
read a diagnostic and find the line to fix
choose the validation profile for your situation
validate a model that lives in many files

Before you start

Install the command line tool first. The Get started page shows three ways. Then make sure that the tool runs:

emhcl version

A model for specification v0.8.0 needs emhcl v0.17.0 or newer.

The edit loop

You work on a model in a loop. Repeat these steps after each change:

Edit the .em.hcl file.
Format the file with emhcl fmt -w model.em.hcl.
Validate the file with emhcl validate model.em.hcl.
Read each diagnostic and fix its cause.
Render the model with emhcl diagram model.em.hcl -o model.html. Open model.html in a browser.

To render after every save, run emhcl serve model.em.hcl and open the URL that it prints. The server listens on 127.0.0.1:8080 by default. Add --port 0 to let the tool pick a free port.

Each command ends with an exit code:

Exit code	Meaning
0	Success.
1	The model has problems.
2	The tool cannot read the command line.

A valid model prints the path and the word valid, for example model.em.hcl valid.

Read a diagnostic

The tool reports each problem on one line in this form:

file:line:column: Severity EMxxx: message

Here is a diagnostic from an example on the Language page. A Command points back to its Screen with from:

reverse-flow.em.hcl:16:13: Error EM201: Invalid flow reference: command.from has no canonical flow targets in a state_change workflow. You referenced: screen.form.

Read it from left to right:

The file is reverse-flow.em.hcl. Look at line 16, column 13.
The severity is Error. The file does not validate.
The code is EM201. The first digit after EM tells the family.
The message says that from is not a canonical flow target in a state_change.

The fix: delete from on the Command. The Screen already has to = [command.create], and that is the canonical edge. A workflow-local source writes its own to.

The code families help you find the cause fast:

Family	What it reports
`EM0xx`	Structure: syntax, identities, the board, field types.
`EM1xx`	References that do not resolve.
`EM2xx`	Flow: edges in the wrong direction or place.
`EM3xx`	Scenarios.
`EM4xx`	Modeling judgment: warnings to review.

Try first: the tool prints EM301. Which family is it, and where do you look?

Show the answer

It is in the EM3xx family, so it reports a scenario. Look at the scenario named in the message.

Choose a profile

A profile sets how strict the tool is about modeling judgment. Core errors, such as a broken reference, are errors in every profile. Only the codes EM401 to EM406 change.

Profile	Four shapes (EM401, EM402, EM403, EM405)	EM404 and EM406
`workshop`	Information	Information
`valid` (the default)	Warning	Warning
`strict`	Warning	Error

Use workshop while you explore with the team. Use the default for daily work. Use strict before you call a model ready for implementation:

emhcl validate --profile strict model.em.hcl

The strict profile turns two things into errors. The first is a Command with no reason, which is EM404. The second is an open hotspot, which is EM406. A profile does not hide the model. A tool can still render a model that only a profile rejects. Page 7 explains each code.

A model in many files

Split a model into a folder when one file is too long to read. The folder is still one model. The tool reads every .em.hcl file directly in the folder. It ignores subfolders and file names that start with a dot.

Two facts make folders safe:

File names and the order of blocks have no meaning. Moving a block to another file does not change the model.
A block does not span two files. Move each block whole.

To split a file, follow these steps:

Make a new folder for the model.
Move the board and the catalog blocks into one file, for example 00-catalog.em.hcl.
Move the chapter blocks into another file, for example 01-chapters.em.hcl.
Move each workflow into its own file, for example 10-register-pet.em.hcl.
Move other blocks, such as hotspot, into any file.
Run emhcl validate on the folder and fix each error.

The number prefix is not part of the language. It keeps the files in reading order for people. Most commands accept a folder path in place of a file path:

emhcl validate examples/pet-clinic emhcl serve examples/pet-clinic

Each diagnostic names the member file that needs attention.

See what changed

The command diff compares two models. It lists each declaration that a change added, removed, or changed:

emhcl diff base/model head/model

A line looks like changed workflow.register_pet. A changed workflow lists its changed elements and scenarios below it. The tool compares the typed models, so a block that moves to another file gives no line.

Use the tool in scripts and CI

Scripts and agents can read the results as data. Add --format json to validate:

emhcl validate --profile strict --format json model.em.hcl

The tool writes one JSON object. Its keys are path, profile, has_errors, has_core_errors, and diagnostics. Each diagnostic has code, severity, summary, detail, line, column, judgment, and file. The value of judgment is true for the codes EM401 to EM406.

Two more commands help in CI:

emhcl fmt --check model.em.hcl emhcl diagram --title "shop main @ 1a2b3c4" -o model.html model.em.hcl

The command fmt --check writes no file. It lists each file whose layout differs and exits with code 1. The option --title sets the title in the page header and the browser tab.

Move models in and out

The commands export and import convert between a native model and slice-based Event Modeling JSON. The JSON form is a projection that the tool warns about. It is not a copy of the canvas.

The command migrate converts a model that was written for specification v0.4.0. It adds a board, writes explicit types, and writes explicit titles. Use -w to rewrite the file:

emhcl migrate -w old.em.hcl

Validate the result after you migrate.

Check yourself

1

The tool prints Warning EM404 and then valid. Is the model valid?

Answer

Yes, under the default profile. A warning does not stop validation. Under --profile strict, the same diagnostic is an error.

2

You move a workflow to another file in the folder. Does the model change?

Answer

No. File names and the position of blocks have no meaning. The model stays the same.

3

Which command checks the format in CI without changing a file?

Answer

emhcl fmt --check. It exits with code 1 if a file differs from the formatted output.

4

A command ends with exit code 2. What does that mean?

Answer

The tool cannot read the command line. The model is not the cause. Check the options and the path.

Remember:

The loop is: format, validate, read, fix, render.
A diagnostic names the file, the line, the severity, and a code. The code family tells the area.
The profile changes only the codes EM401 to EM406.
A folder of .em.hcl files is one model. File names and block order have no meaning.