Freon Documentation (version 0.5.0)

Project Structure

This description of the project structure of a Freon project is based on the Freon-example project which you can clone from GitHub.

The source code (in ~/src) in a Freon project is organised into the following subfolders.

  • defs: the language definition files.

  • picode: the generated source code.

    You can use your own names for defs and picode.
    The defs and picode folders can have any name as long as both the generate script in package.json, and the configuration of the web application in the file ~/src/webapp/WebappConfiguration.ts, are adjusted.

  • picode/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: ProjectitConfiguration.ts. Here you can configure any third-level customization that you want the generated code to take into account.

  • picode/diagrams: a number of UML diagrams generated from the language structure including an UML class diagram of the AST, an overview of all inheritance in the language, and one diagram per .ast file. You can find all of them both in ordinary HTML and in Markdown format. In the future we plan to make the generation customizable.

  • picode/editor: code for the editor. This folder contains two files that will not be overwritten at regeneration: Custom<yourLanguageName>Actions.tsand Custom<yourLanguageName>Projection.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 third-level customization that you would like to do.

  • picode/language: code that implements the language structure.

  • picode/reader: a parser that is able to read model units from a text string or file.

  • picode/scoper: code for that determines which elements are visible for a certain element in the user’s model.

  • picode/stdlib: code that implements some standard elements of your language, for instance limited concepts.

  • picode/typer: code that that determines which type is associated with a certain element in the user’s model. The file Custom<yourLanguageName>TyperPart.ts is the placeholder for any third-level customization that you would like to do.

  • picode/utils: a default implementation of a visitor for your user’s model.

  • picode/validator: code that determines whether or not certain parts of your user’s model contain errors. The file Custom<yourLanguageName>Validator.ts is the placeholder for any third-level customization that you would like to do.

  • picode/writer: code that is able to write your user’s model units in string format to a file.

  • webapp: source code for the web-application used for all generated languages.

  • Noteworthy is the file picode/webapp/config/WebappConfiguration.ts. This file holds the references to the generated language workbench and the web address of the server which stores your user’s models.

Another folder that can be found in the project is ~/modelstore. This is the folder where the server stores all models, and it is created at the moment that the server is started. Each model is stored in a separate folder in which you can find its modelunits as .json files.

Be careful with handmade changes in picode.
The contents of all folders in picode is divided into files (usually TypeScript classes) that are contained directly in the folder, and files that are contained in the subfolder gen. The latter are always removed before regeneration, so be careful not to add important code to the gen folder. Code that is contained directly in each folder is not changed upon regeneration.

The Webapp and Server

For the language environment to function, more is needed than the code for the editor, validator and such. In particular, there is a need for a server which can hold and provide stored users models, and for a small web application that is able to show the editor, errors message, models that are available form the server, and so on.

Therefore, we provide a minimal server that stores your user models in a json format. You can start it through the commandline:

    yarn model-server

A simple web application where you can see your language in action is also provided. The code can be found in ~/webapp. It was created using Svelte. You can start it through the commandline:

    yarn dev

Note that both the server, and the web application are provided for your convenience. We assume that when Freon is used in a larger context, these two parts will be interchanged with suitable choices made by the language engineer and team.