Skip to content

Latest commit

 

History

History
193 lines (161 loc) · 6.11 KB

tutorial.md

File metadata and controls

193 lines (161 loc) · 6.11 KB
Raw

rascal-lsp-skeletons

Initializing a Maven project

Based on https://maven.apache.org/guides/getting-started/maven-in-five-minutes.html

To create a new directory named my-app with a new Maven project:

mvn archetype:generate \
    -DgroupId=com.mycompany.app \
    -DartifactId=my-app \
    -DarchetypeArtifactId=maven-archetype-quickstart \
    -DarchetypeVersion=1.4 \
    -DinteractiveMode=false

From here on, start working inside the my-app directory:

cd my-app

Including Rascal project information

First, create a directory to hold the Rascal project information:

mkdir META-INF && cd META-INF

In this directory, create a file RASCAL.MF with the following contents. Note: It is currently required to end this file with two newlines:

Manifest-Version: 0.0.1
Main-Function: main
Project-Name: my-app
Main-Module: VSMain
Source: src

Creating a Rascal file

Next up, create a Rascal file Syntax.rsc in the constructed my-app/src/ directory.

module Syntax

extend lang::std::Layout;
extend lang::std::Id;

start syntax Machine = machine: State+ states;
syntax State = @Foldable state: "state" Id name Trans* out;
syntax Trans = trans: Id event ":" Id to;

You should now be able to import this module in a Rascal console in either of two ways:

  • Click Import in new Rascal terminal at the top of the Syntax.rsc source file or
  • Open a Rascal Terminal yourself (cmd/ctrl + shift + P > Create Rascal Terminal), and import using import Syntax;.

Working with Java bindings

In Rascal, you can bind functions to Java, and therefore use Java libraries. However, this requires a conversion between Java and Rascal values. To convert values between Rascal and Java, we use the library Vallang.

Making Vallang available

Vallang is available from the usethesource maven repository. This has to be added as a repository to the maven project first in the file pom.xml as a child of the project node:

  <repositories>
    <repository>
      <id>usethesource</id>
      <url>https://releases.usethesource.io/maven/</url>
    </repository>
  </repositories>
  <pluginRepositories>
    <pluginRepository>
      <id>usethesource</id>
      <url>https://releases.usethesource.io/maven/</url>
    </pluginRepository>
  </pluginRepositories>

Now that Vallang can be found, add it as a dependency for the project in the dependencies element:

    <dependency>
      <groupId>io.usethesource</groupId>
      <artifactId>vallang</artifactId>
      <version>0.14.4</version>
    </dependency>

Next up, let Maven download and install the dependencies:

mvn verify

Constructing the Java source

Now the Vallang library is available in our Java files. First add a constructor in src/main/java/com/mycompany/app/App.java taking an IValueFactory object:

package com.mycompany.app;

import io.usethesource.vallang.IInteger;
import io.usethesource.vallang.IValueFactory;


public class App 
{
    private final IValueFactory vf;

    public App(IValueFactory vf) {
        this.vf = vf;
    }
}

and then add a function BigIncrement to the same class:

    public IInteger BigIncrement(IInteger rascal_value) {
        // Convert to Java value
        int java_value = rascal_value.intValue();

        // Big increment
        java_value += 100;

        // Return value that can be used in Rascal
        return vf.integer(java_value);
    }

Constructing the Rascal source

And finally, lets create the binding between Rascal and the Java file we created. Lets do this in a new file src/RascalJavaBindings.rsc:

module RascalJavaBindings

@javaClass{com.mycompany.app.App}
public java int BigIncrement(int rascal_value);

Note: This will NOT work if you have opened VS-code with a parent folder of the project. Ensure that MY-APP is the root folder opened in VScode (Top of file browser on the left). Now, in a Rascal terminal import RascalJavaBindings; and call it using BigIncrement(20).

Note that conversion of Java exceptions to Rascal exceptions is done using rascalmpl instead of Vallang. It can be included as dependency by adding onto pom.xml:

    <dependency>
      <groupId>org.rascalmpl</groupId>
      <artifactId>rascal</artifactId>
      <version>0.23.0</version>
    </dependency>

Using local Java libraries

Based on this so answer, but without the requirement of a local-maven-repo:

  1. Install each local jar as an artifact using Maven. Be sure to specify the correct metadata:
mvn install:install-file \
  -DcreateChecksum=true \
  -DupdateReleaseInfo=true \
  -DgeneratePom=true \
  -Dpackaging=jar \
  -Dfile=[your-jar] \
  -DgroupId=[...] \
  -DartifactId=[...] \
  -Dversion=[...]

An example:

mvn install:install-file \
  -DcreateChecksum=true \
  -DupdateReleaseInfo=true \
  -DgeneratePom=true \
  -Dpackaging=jar \
  -Dfile=./lib/frink.jar \
  -DgroupId=frinklang \
  -DartifactId=frink \
  -Dversion=22.4.18
  1. Add each installed artifact as dependecy in pom.xml using the specified metadata:
    <dependency>
      <groupId>groupId</groupId>
      <artifactId>artifactId</artifactId>
      <version>version</version>
    </dependency>
  1. Let Maven download and install the dependencies:
mvn verify

The next step is to specify the location of the installed .jar file in RASCAL.MF. Right now, this has to be done using a full, absolute path. Note that you therefore cannot copy the following path, but have to adjust it to match your username:

Require-Libraries: |file:////Users/auke/.m2/repository/frinklang/frink/22.4.18/frink-22.4.18.jar|

Multiple libraries can be added by adding addition locations, comma-separated:

Require-Libraries: |file:///<location1>|, |file:///<location2>|

After this, you can use the functionality provided by the local jar in the Java source files.