On this page ...

Previous

 

Next

Get ready to use Freon by installing Node.js, which includes npm. You may also use Yarn or another package manager if you prefer.

We are typically using the latest versions of all, although older versions likely work just as well. You could also try other packages managers instead of npm.

The best way to create a Freon project is to use the command:

  npm create freon@latest

You will be asked to select any of the languages used in this documentation, or the StarterLanguage for an empty language project. The project will be located in the ./DSL-name directory , where DSL-name is the name of the language you have chosen. It will also install all required packages (npm install), and run the Freon generator, generating code in src/freon (npm run build):

To start working with the Freon editor, first start the file server (any parts of the model that are saved in the editor will be stored by the server in ~/modelstore):

  npm run server

Next, open another (bash) terminal, and start the generated editor from it:

  npm run prepare-app   # Generates the runtime CSS files. A single run will suffice.
  npm run dev           # Builds and serves the page with the Freon editor.

The last command shows a URL that you can open in your preferred browser. The web page contains the generated editor for the language in your project.

Now that everything is running, you can go to the src/defs folder, and change the Freon definition files. After changing the files in src/defs you need to re-run the generator, and you will see the newly generated files appearing in the ~/src/freon folder. The following command re-runs the generator, and compiles the newly generated files:

  npm run build

In order to speed up your development cycle the npm run dev command has the -watch flag set, so the webpage in the browser should be updated as well.

The code in a Freon project under ~/src is organised into the following sub-folders.

• defs: the language definition files.
• freon: the generated source code.
  • /commandline: code that provides command line access to models in the language.
  • /config: code that provides the coupling between all parts of the generated workbench. This folder contains one file that will not be overwritten at regeneration: FreonConfiguration.ts. Here you can configure any customization that you want the generated code to take into account.
  • /diagrams: a number of UML diagrams generated from the language structure including a UML class diagram of the AST, an overview of all inheritance in the language, and one diagram per .ast file. You’ll find all of them in both HTML and Markdown format. In the future we plan to make the generation customizable.
  • /editor: code for the editor. This folder contains two files that will not be overwritten at regeneration: CustomYourLanguageNameActions.ts and CustomYourLanguageNameProjection.ts. (YourLanguageName will be replaced by the name you have given your language in the .ast files.) These two files are the placeholders for any customization that you would like to do.
  • /interpreter: code that implements an interpreter interpreter for the language.
  • /language: code that implements the language structure.
  • /reader: a parser that is able to read model units from a text string or file.
  • /scoper: code for that determines which elements are visible for a certain element in the user’s model.
  • /stdlib: code that implements some standard elements of your language, for instance limited concepts.
  • /typer: code that that determines which type is associated with a certain element in the user’s model. The file CustomYourLanguageNameTyperPart.ts is the placeholder for any customization that you would like to do.
  • /utils: a default implementation of a visitor for your user’s model.
  • /validator: code that determines whether certain parts of your user’s model contain errors. The file CustomYourLanguageNameValidator.ts is the placeholder for any customization that you would like to do.
  • /writer: code that is able to write your user’s model units in string format to a file.
• external: any external Svelte components and the code to plug these into Freon.
• style: All CSS and SCSS file for styling Freon.
• starter.ts: the startup code for the web editor
• logger.ts: Code to turn logging on or off, used for debugging.

In the root of the project the following folder is also needed:

• modelstore This folder is where the simple server stores all models. If it is not there, the server will create it at startup. Each model is stored in a folder in which you can find its model units as separate .json files in LionWeb format.

The Freon projectional web editor needs to be embedded in an application to work properly. It also needs a server that allows to store and retrieve the models the user creates in the editor.

For the server we provide a minimal implementation for your convenience. We also provide a complete web app to embed the Freon editor.

However, we anticipate that in the context where Freon is used, these components usually need to be replaced with solutions appropriate for the company or organization where Freon is being used.

Note that Freon can optionally use the LionWeb repository.

A Freon language definition can have five parts:

1. The AST file: the abstract syntax tree (AST) or metamodel is defined in files with extension .ast.
2. The Edit file: the concrete syntax (CST), or editor definition, is defined in files with extension .edit.
3. The Scope file: the scope rules are defined in files with extension .scope.
4. The Type file: the typing rules are defined in files with extension .type.
5. The Validation file:: the validation rules are defined in files with extension .valid.

And yes, you can use multiple files to define one of the parts. For instance, Freon will combine multiple .ast files into one AST definition, and multiple .scope files into one scope definition.

See the Documentation and the Tutorial for a detailed description of the five language parts.

There is no need to write all the five definition files right from the start. The only one that is mandatory is the language structure (.ast). Freon will generate defaults for all the other elements. This is what we call the Default Level of the three levels of customization.

The Freon command line tool generates code from the various definition files. If you type freon in a (bash) terminal you will see the following overview of the different arguments that can be used. For detailed help about a specific command, type: ‘freon <command> -h’.

freon -h
usage: freon [-h] [-v] [-w] <command> ...

Freon toolset for generating languages, scopers, editors, etc.

Positional arguments:
  <command>
    all          Generates the TypeScript code for all parts of the work
                 environment for your language, plus some diagrams that show
                 the AST
    ast-it       Generates the TypeScript code for your language
    edit-it      Generates the typeScript code for the projectional editor
                 for your language
    parse-it     Generates the typeScript code for the reader and writer of
                 your language
    diagram-it   Generates Mermaid diagrams of the AST of your language
    scope-it     Generates the TypeScript code for the scoper for your
                 language
    validate-it  Generates the TypeScript code for the validator for your
                 language
    type-it      Generates the TypeScript code for the typer for your language
    interpret-it
                 Generates interpreter for your language
    clean-it     Removes the generated TypeScript code for all parts of the
                 work environment for your language

Optional arguments:
  -h, --help     Show this help message and exit.
  -v, --verbose  Show extra logging detail
  -w, --watch    Start generator in watch mode (only in combination with
                 'all')

For detailed help about a specific command, use: freon <command> -h

Previous

 

Next