MPS User's Guide

MPS User Guide for Language Designers

Welcome to MPS. This User Guide is a complete reference documentation to MPS and it will navigate you through the many concepts and usage patterns that MPS offers and will give you a hand whenever you need to know more details about any particular aspect of the system.

Topics

1. Fundamental knowledge - a high-level overview of the basic notions
   • Basic notions of MPS: nodes, concepts, and languages
   • Glossary
   • FAQ
   • MPS project structure
   • Copyrights

   • Contributing to JetBrains MPS - guidelines for MPS contributors and developers on how to get around the MPS source code

   • Language repository - find out more about languages that are available for use in MPS, both by JetBrains and external vendors

2. Using MPS - get familiar with the interface through which you'll communicate with MPS

   • The first run - essential information for total beginners into how MPS is organised, how it works and how users are supposed to interact with it.

   • Commanding the editor
   • Default keymap reference
   • IDE configuration
   • How to install language plugins
   • MPS Java compatibility
   • Getting the dependencies right

   • Resolving difficulties, understanding reported errors - tips to help you find your way out when you get stuck somewhere.

   • Version control notes
   • Using the debugger
   • Console

3. Language definition - defining a language involves specifying several aspects, each of which codifies some part of the language - the allowed AST structure, the appearance on the screen, type-system rules, etc.

   Aspect	Description	Core documentation
   Structure	Defines the kinds of nodes (called Concepts) that may be used in user models. Each node in the program (model) refers to its concept. Concepts specify, which properties, children and references nodes may have. Concepts can extend other Concepts and implement ConceptInterfaces.	Structure SModel language     - programatic access to the model Open API     - API reference for accessing models Quotations     - building AST snippets Pattern     - language for pattern matching nodes Using model & module dependencies from code FAQ Video -  Introduction to JetBrains MPS, The First Run: Projects Structure SModel language     - programatic access to the model Open API     - API reference for accessing models Quotations     - building AST snippets Pattern     - language for pattern matching nodes Using model & module dependencies from code FAQ Video -  Introduction to JetBrains MPS: Structure
   Constraints	Restricts the relationships between nodes as well as the allowed values for properties beyond the rules defined in Structure. Constraints typicaly define:  - the target scope for references (a collection of allowed nodes a reference can point to)  - situations, in which a node can be a child/parent/ancestor of another node  - allowed values for properties  - property accessor methods (getters and setters)	Constraints Scopes Video -  Introduction to JetBrains MPS, part 3: Constraints
   Behavior	Just like classes in OOP hold methods, Concepts may define methods and static methods that can be invoked on nodes in a polymorphic way. Nodes thus carry behaviour alongside their properties and relationships.	Behavior Video -  Introduction to JetBrains MPS, part 4: Behavior
   Editor	Instead of defining a parser that would translate code from an editable form (i.e. text) into the tree-like structure that a computer could manipulate, MPS offers the concept of  projectional editor, which let's the user edit the AST directly. The Editor aspect enables language designers to create a UI for editing their concept concepts.	Editor Diagramming Editor Transformation Menu Language Context Assistant Context actions tool Editor cookbook Editor language generation API Video -  Introduction to JetBrains MPS, part 5: Editor
   Actions	The Actions aspect provides means to specify advanced editor behavior, such as copy/paste or node initialization.	Editor Actions
   Intentions	All modern IDEs assist developers with instant code manipulating action available under a handy key-shortcut (Alt + Enter in MPS). Language authors can define such little code transformations for their languages in the Intentions aspect.	Intentions Video - Introduction to JetBrains MPS, part 7: Intentions
   Generator	Models written in one or more languages get ultimately translated into runnable code in some target general-purpose language and platform, such as Java. Along the way models get gradually transformed so that repeatedly concepts get replaced with concepts from a lower level of abstraction until the bottom-line level is reached. The rules for translating concepts and their proper ordering is defined in the Generator aspect.	Generator Generator Plan Generator cookbook Building an interpreter cookbook Video -  Introduction to JetBrains MPS, part 8: Generator
   TextGen	During code generation after the Generator has reached the bottom-line AST representation, the TextGen phase kicks in and translates all nodes in the model into their textual representation and saves the resulting textual source files on disk.	TextGen Video -  Introduction to JetBrains MPS, part 9: TextGen
   Dataflow	The ability to understand the flow of values and the flow of control through language constructs helps languages report issues such as unreachable code or potential null-pointer error. Language designer can leverage the Dataflow aspect to define the flow for each concept, which MPS will then use to calculate the dataflow for the whole program.	Dataflow Dataflow cookbook Video -  Introduction to JetBrains MPS, part 10: Dataflow
   Typesystem	Language that need to type-check their code need to provide type-system rules. The MPS type-system engine will evaluate the rules on-the-fly, calculate types for nodes and report  errors, wherever the calculated type differs from the expectations.  So called checking rules may additionally be defined to verify non-typesystem assertions about the model.	Typesystem Typesystem cookbook Using the typesystem Debugging the typesystem  Video -  Introduction to JetBrains MPS, part 11: Type-system
   Refactoring	Modern IDEs allow the developer to seamlessly and flawlessly change the structure of their code through refactoring. MPS allows the language designers to prepare such refactorings and make them part of their languages.	Refactoring
   Migrations	When a new version of a language is released to the public, projects that use the previous version of the language must be migrated so that they use the new language constructs. Migration scripts, prepared by the language authors, will manipulate user code and automatically update it to the most recent version of the language.	Migrations Migrations with branching
   Testing	Various aspects of language definition can be automatically tested. Language authors may create tests that will verify that the editor, actions, type-system, data flow or constraints of their languages behave according to the specifications.	Testing
   Scripts	TODO	Scripts
   Accessories	The Accessories Models can be stored at two places - either as an aspect of a language (recommended), or as a regular model under a solution. In both cases, the model needs to be added to the Language Runtime Language Settings so as it could be used. A typical use case would be a default library of Concept instances to be available at any place the language is used.	Accessories

4. IDE Integration - how to customise MPS, add language-specific visual extensions, use different persistence format, etc.
   • Generic placeholders and generic comments
   • Commenting out nodes
   • Custom language aspects

   • UI Plugin - extending the UI (menus, tool windows, tabs, preferences, etc.)

   • Find Usages - customising the way users discover nodes

   • Suppressing Errors
   • Debugger
   • Make
   • Extension support
   • MPS and Ant
   • HTTP support plugin
5. IDE tools - tools that MPS offers you to manipulate the languages

   • Dependencies Analyzer - analyze model dependencies (Analyze model dependencies)

   • Module Dependencies Tool (Analyze module dependencies)

   • Run Configurations
   • Changes highlighting
   • Module Cloning
6. Platform Languages - out-of-the-box languages ready for use
   • Base Language
     • Base Language Extensions Style Guide
     • MPS Java compatibility
     • Generate BaseLanguage expression extensions
   • Closures
   • Collections language
   • Tuples
   • Lightweight DSL
   • Regexp language
   • Type Extension Methods
   • Builders
   • Logging
   • XML language

   • Icon description - describing icons by text

   • Concept Functions
   • Other languages
7. Building MPS projects - building languages from the command line, Ant integration, continuous integration, creating and using plugins, obfuscating code
   • Build Language
   • Building IntelliJ IDEA language plugins
   • Using MPS inside IntelliJ IDEA
   • Building MPS language plugins
   • Building standalone IDEs for your languages
   • Extending the user interface

   • Removing sources from generated code  (Implementation stripping)

8. Cookbooks - quick how-to guides
   

   • Common language patterns - a how-to guide covering recurring language design patterns

   • Editor cookbook
   • Generator cookbook
   • Building an interpreter cookbook

   • Description comments - a cookbook showing how to leverage attributes, scopes and error suppression to add support for description comments on arbitrary code elements of your languages

   • Requirement tracking language - an commented tour round the Requirement tracking sample project. You will learn about node attributes, multiple projections and scoping.

   • Type System
   • Dataflow cookbook
   • Regular expressions
   • Open API - accessing models from code
   • Custom Persistence Cookbook
   • Custom Language Aspect Cookbook
9. External tutorials and guides

   • How to Add JARs to a JetBrains MPS Project - a tutorial by Federico Tomasseti

   • MindMaps - a tutorial by  Antoine Gagnon

   • Generators tutorial by Eugen Schindler

   • Maintainable generators by Kolja Dummann