Hatching Specs

Hatching Specs#

Fandango provides an include() function that you can use to include existing Fandango content. This allows you to distribute specifications over multiple files, defining base specs whose definitions can be further refined in specs that use them.

Including Specs with include()#

Specifically, in a .fan file, a call to include(FILE)

  1. Finds and loads FILE (typically in the same location as the including file)

  2. Executes the code in FILE

  3. Parses and adds the grammar in FILE

  4. Parses and adds the constraints in FILE.

The include() function allows for incremental refinement of Fandango specifications - you can create some base base.fan spec, and then have more specialized specifications that alter grammar rules, add more constraints, or refine the code.

Incremental Refinement#

Let us assume you have a base spec for a particular format, say, base.fan. Then, in a refined spec (say, refined.fan) that includes base.fan, you can

  • override grammar definitions, by redefining rules;

  • override function and constant definitions, by redefining them; and

  • add additional constraints.

As an example, consider our persons.fan definition of a name database. We can create a more specialized version persons50.fan by including persons.fan and adding a constraint:

include('persons.fan')
where int(<age>) < 50

Likewise, we can create a specialized version persons-faker.fan that uses fakers by overriding the <first_name> and <last_name> definitions:

from faker import Faker
fake = Faker()

include('persons.fan')

<first_name> ::= <name> := fake.first_name()
<last_name> ::= <name> := fake.last_name()

The include mechanism thus allows us to split responsibilities across multiple files:

  • We can have one spec #1 with basic definitions of individual elements

  • We can have a spec #2 that uses (includes) these basic definitions from spec #1 to define a syntax

  • We can have a spec #3 that refines spec #2 to define a specific format for a particular program or device

  • We can have a spec #4 that refines spec #3 towards a particular testing goal.

These mechanisms are akin to inheritance and specialization in object-oriented programming.

Tip

Generally, Fandango will warn about unused symbols, but not in an included .fan file.

Crafting a Library#

If you create multiple specifications, you may wonder where best to store them. The rules for where Fandango searches for included files are complex, but they boil down to two simple rules:

Tip

Store your included Fandango specs either

  • in the directory where the including specs are, or

  • in $HOME/.local/share/fandango (or $HOME/Library/Fandango on a Mac).

include() vs. import#

Python provides its own import mechanism for referring to existing features. In general, you should use

  • import whenever you want to make use of Python functions; and

  • include() only if you want to make use of Fandango features.

Warning

Using include for pure Python code, as in include('code.py') is not recommended. Most importantly, the current Fandango implementation will process “included” Python code only after all code in the “including” spec has been run. In contrast, the effects of import are immediate.

Contents