Skip to main content

module util::Reflective

rascal-Not specified

Usage​

import util::Reflective;

Dependencies​

extend util::PathConfig;
import IO;
import List;
import ParseTree;
import String;
import util::FileSystem;
import Message;
import lang::rascal::\syntax::Rascal;
import lang::manifest::IO;

function getLineSeparator​

Returns the system-dependent line separator string

str getLineSeparator()

function evalCommands​

lrel[str result, str out, str err] evalCommands(list[str] command, loc org)

function parseModule​

Just parse a module at a given location without any further processing (i.e., fragment parsing) or side-effects (e.g. module loading)

lang::rascal::\syntax::Rascal::Module parseModule(loc location)

function parseModuleWithSpaces​

Parse a module (including surrounding spaces) at a given location without any further processing (i.e., fragment parsing) or side-effects (e.g. module loading)

start[Module] parseModuleWithSpaces(loc location)

data RascalConfigMode​

data RascalConfigMode  
     = compiler()
     | interpreter()
     ;

data RascalManifest​

data RascalManifest  
     = rascalManifest(
      str \Project-Name = "Project",
      str \Main-Module = "Plugin",
      str \Main-Function = "main", 
      list[str] Source = ["src"],
      str Bin = "bin",
      list[str] \Required-Libraries = [],
      list[str] \Required-Dependencies = []
    )
     ;

data JavaBundleManifest​

data JavaBundleManifest  
     = javaManifest(
      str \Manifest-Version = "",
      str \Bundle-SymbolicName = "",
      str \Bundle-RequiredExecutionEnvironment = "JavaSE-1.8",
      list[str] \Require-Bundle = [],
      str \Bundle-Version = "0.0.0.qualifier",
      list[str] \Export-Package = [],
      str \Bundle-Vendor = "",
      str \Bundle-Name = "",
      list[str] \Bundle-ClassPath = [],
      list[str] \Import-Package = [] 
    )
     ;

function resolveProjectOnClasspath​

Makes the location of a jar file explicit, based on the project name

loc resolveProjectOnClasspath(str projectName)

The classpath of the current JVM is searched and jar files are searched that contain META-INF/MANIFEST.MF file that match the given projectName.

Benefits​

  • This is typically used to link bootstrap libraries such as rascal.jar and rascal-lsp.jar into testing Path Configs.
  • The classpath is not used implicitly in this way, but rather explicitly. This helps in making configuration issues tractable.
  • The resulting loc value can be used to configure a Path Config instance directly.

function resolveModuleOnCurrentInterpreterSearchPath​

Search a module name in the interpreter's search path

loc resolveModuleOnCurrentInterpreterSearchPath(str moduleName)

This exists to help debugging interactive loading and reloading of Rascal modules by the REPL and the interpreter. It does not work in a compiled context.

Pitfalls​

This is internal information for the interpreter and should not be used by client code. Only for debugging purposes of the interpreter and the REPL.

function resolvedCurrentRascalJar​

Makes the location of the currently running rascal jar explicit.

loc resolvedCurrentRascalJar()

function metafile​

loc metafile(loc l)

function applyManifests​

Converts a PathConfig and replaces all references to roots of projects or bundles by the folders which are nested under these roots as configured in their respective META-INF/RASCAL.MF files.

PathConfig applyManifests(PathConfig cfg)

function makeFileName​

str makeFileName(str qualifiedModuleName, str extension = "rsc")

function getSearchPathLoc​

loc getSearchPathLoc(str filePath, PathConfig pcfg)

function getModuleLocation​

Get the location of a named module, search for src in srcs and tpl in libs

loc getModuleLocation(str qualifiedModuleName,  PathConfig pcfg)

function splitFileExtension​

tuple[str,str] splitFileExtension(str path)

function commonSuffix​

Determine length of common suffix of list of strings

int commonSuffix(list[str] dir, list[str] m)

function commonPrefix​

Determine length of common prefix of list of strings

int commonPrefix(list[str] rdir, list[str] rm)

function getModuleName​

Find the module name corresponding to a given module location via its (src or tpl) location

str getModuleName(loc moduleLoc,  PathConfig pcfg)

function getDerivedReadLoc​

Derive a location from a given module name for reading

tuple[bool, loc] getDerivedReadLoc(str qualifiedModuleName, str extension, PathConfig pcfg, set[str] srcExtensions = {"rsc", "mu"}, str rootDir = "")

Given a module name, a file name extension, and a PathConfig, a path name is constructed from the module name + extension.

If a file F with this path exists in one of the directories in the PathConfig, then the pair <true, F> is returned. Otherwise <false, some error location> is returned.

For a source extension (typically "rsc" or "mu" but this can be configured) srcs is searched, otherwise binPath + libs.

Examples​

rascal>import util::Reflective;
ok
rascal>getDerivedReadLoc("List", "rsc", pathConfig());
tuple[bool,loc]: <false,|error:///|>
rascal>getDerivedReadLoc("experiments::Compiler::Compile", "rvm", pathConfig());
tuple[bool,loc]: <false,|error:///|>
rascal>getDerivedReadLoc("experiments::Compiler::muRascal2RVM::Library", "mu", pathConfig());
tuple[bool,loc]: <false,|error:///|>

Benefits​

This function is useful for type checking and compilation tasks, when derived information related to source modules has to be read from locations in different, configurable, directories.

function getDerivedWriteLoc​

Derive a location from a given module name for writing

loc getDerivedWriteLoc(str qualifiedModuleName, str extension, PathConfig pcfg, set[str] srcExtensions = {"rsc", "mu"}, str rootDir = "")

Given a module name, a file name extension, and a PathConfig, a path name is constructed from the module name + extension.

For source modules, a writable location cannot be derived. For other modules, a location for this path in bin will be returned.

Examples​

rascal>import util::Reflective;
ok
rascal>getDerivedWriteLoc("List", "rvm", pathConfig());
loc: |unknown:///rascal/$List.rvm|
rascal>getDerivedWriteLoc("experiments::Compiler::Compile", "rvm", pathConfig());
loc: |unknown:///rascal/experiments/Compiler/$Compile.rvm|
rascal>getDerivedWriteLoc("experiments::Compiler::muRascal2RVM::Library", "rsc", pathConfig());
|prompt:///|(0,18,<1,0>,<1,18>): Undeclared variable: getDerivedWriteLoc
Advice: |https://www.rascal-mpl.org/docs/Rascal/Errors/CompileTimeErrors/UndeclaredVariable|

Benefits​

This function is useful for type checking and compilation tasks, when derived information related to source modules has to be written to locations in separate, configurable, directories.

function getProjectPathConfig​

PathConfig getProjectPathConfig(loc projectRoot, RascalConfigMode mode = compiler())

function inCompiledMode​

Is the current Rascal code executed by the compiler or the interpreter?

bool inCompiledMode()

function diff​

Give a textual diff between two values.

str diff(value old, value new)

function getFingerprint​

Compute a fingerprint of a value for the benefit of the compiler and the compiler runtime

int getFingerprint(value val, bool concretePatterns)

function getFingerprint​

Compute a fingerprint of a value and arity modifier for the benefit of the compiler and the compiler runtime

int getFingerprint(value val, int arity, bool concretePatterns)

function getFingerprintNode​

Compute a fingerprint of a complete node for the benefit of the compiler and the compiler runtime

int getFingerprintNode(node nd)

function getHashCode​

Get the internal hash code of a value. For the benefit of debugging the Rascal implementation.

int getHashCode(value v)

This function is useless for Rascal programmer's as it is a part of the under-the-hood implementation of values. You can use a value directly as a lookup key. The internal data-structures probably use this hashCode for optimal lookups in O(log(size)).

We use this function to diagnose possible performance issues caused by hash collisions.

function throwNullPointerException​

Throw a raw Java NullPointerException, to help simulate an unexpected exception in test scenarios

void throwNullPointerException()

function getRascalReservedIdentifiers​

Return a list of all Rascal reserved identifiers (a.k.a. keywords)

set[str] getRascalReservedIdentifiers()

function getRascalVersion​

str getRascalVersion()

function newRascalProject​

Create a folder structure for an empty Rascal project with Maven support

void newRascalProject(loc folder, str group="org.rascalmpl", str version="0.1.0-SNAPSHOT")

function pomFile​

loc pomFile(loc folder)

function emptyModule​

str emptyModule()

function rascalMF​

str rascalMF(str name)

function newRascalMfFile​

Create a new META-INF/RASCAL.MF file.

void newRascalMfFile(loc folder, str name=folder.file)

The folder parameter should point to the root of a project folder. The name of the project will be derived from the name of that folder and a META-INF/RASCAL.MF file will be generated and written.

The folder is created if it does not exist already.

function newRascalPomFile​

Create a new pom.xml for a Rascal project

void newRascalPomFile(loc folder, str name=folder.file, str group="org.rascalmpl", str version="0.1.0-SNAPSHOT")

The folder parameter should point to the root of a project folder. The name of the project will be derived from the name of that folder and a pom.xml file will be generated and written.

The folder is created if it does not exist already.

function pomXml​

str pomXml(str name, str group, str version)

function vscodeSettings​

str vscodeSettings()

function vscodeFolder​

loc vscodeFolder(loc folder)

function vscodeSettingsFile​

loc vscodeSettingsFile(loc folder)

function newRascalVsCodeSettings​

Create a .vscode folder for a Rascal project

void newRascalVsCodeSettings(loc folder)

The folder parameter should point to the root of a project folder. A .vscode folder will be generated and written.

The project folder is created if it does not exist already.