RascalTutor
Synopsis

The available Rascal libraries.

Description

The libraries described here provide the following functionality:

  • Prelude: The Rascal standard prelude.

  • analysis: Library functions for analysis tasks.

  • lang: Definitions and tools for various languages.

  • util: Utilities: functions, data types and interfaces with external libraries.

1. Prelude

Synopsis

The Rascal standard prelude.

Description

The Prelude library provides core functionality for handling all of Rascal’s data-types. See the Rascal Language Reference for details of the language Rascal itself.

For

  • numeric functions, see the [Math] library,

  • statistical functions see statistics,

  • graph functions see graphs,

  • other common utilitites see util.

Prelude provides the following:

  • Boolean: Library functions for Booleans.

  • DateTime: Library functions for date and time.

  • Exception: Exceptions thrown by the Rascal run-time.

  • IO: Library functions for input/output.

  • List: Library functions for lists.

  • ListRelation: Library functions for list relations.

  • Map: Library functions for maps.

  • Message: A Message datatype that represents messages in the IDE.

  • Node: Library functions for nodes.

  • ParseTree: Library functions for parse trees.

  • Relation: Library functions for relations.

  • Set: Library functions for sets.

  • String: Library functions for strings.

  • Type: Rascal’s type system, implemented in Rascal itself.

  • ValueIO: Library functions for reading and writing values in textual and binary format.

Benefits

This library makes it possible to import all core Rascal functionality with a single import.

Pitfalls
  • The prelude may contain more functionality than you need; this leads to an unnecessary longer import and pollution of your name space.

  • The precise contents of the prelude are under discussion.

  • In the future, Rascal may automatically load the prelude.

Unresolved directive in Prelude/Prelude.adoc - include::Boolean/Boolean.adoc[Boolean]

Unresolved directive in Prelude/Prelude.adoc - include::DateTime/DateTime.adoc[DateTime]

Unresolved directive in Prelude/Prelude.adoc - include::Exception/Exception.adoc[Exception]

Unresolved directive in Prelude/Prelude.adoc - include::IO/IO.adoc[IO]

Unresolved directive in Prelude/Prelude.adoc - include::List/List.adoc[List]

Unresolved directive in Prelude/Prelude.adoc - include::ListRelation/ListRelation.adoc[ListRelation]

Unresolved directive in Prelude/Prelude.adoc - include::Map/Map.adoc[Map]

Unresolved directive in Prelude/Prelude.adoc - include::Message/Message.adoc[Message]

Unresolved directive in Prelude/Prelude.adoc - include::Node/Node.adoc[Node]

Unresolved directive in Prelude/Prelude.adoc - include::ParseTree/ParseTree.adoc[ParseTree]

Unresolved directive in Prelude/Prelude.adoc - include::Relation/Relation.adoc[Relation]

Unresolved directive in Prelude/Prelude.adoc - include::Set/Set.adoc[Set]

Unresolved directive in Prelude/Prelude.adoc - include::String/String.adoc[String]

Unresolved directive in Prelude/Prelude.adoc - include::Type/Type.adoc[Type]

Unresolved directive in Prelude/Prelude.adoc - include::ValueIO/ValueIO.adoc[ValueIO]

2. analysis

Synopsis

Library functions for analysis tasks.

Description
  • FCA: Library for Formal Concept Analysis.

  • graphs: Analyzing unlabeled and labelled graphs.

    • Graph: A Graph datatype with associated functions.

    • LabeledGraph: Return the bottom nodes of a LGraph.

  • m3: a language independent meta model for facts about source code, which is extensible to include language specific modeling elements.

  • statistics: Statistical functions.

Pitfalls

Unresolved directive in analysis/analysis.adoc - include::formalconcepts/formalconcepts.adoc[formalconcepts]

2.1. graphs

Synopsis

Analyzing unlabeled and labelled graphs.

Description

Graphs are represented as relations. So in general the idea is to use the Relation module to manipulate graphs. At the same time there are algorithms and analyses which make particular sense when we view a relation as a graph, hence the existence of the Graph and LabeledGraph libraries.

  • Graph: A Graph datatype with associated functions.

  • LabeledGraph: Return the bottom nodes of a LGraph.

Pitfalls

Unresolved directive in analysis/graphs/graphs.adoc - include::Graph/Graph.adoc[Graph]

Unresolved directive in analysis/graphs/graphs.adoc - include::LabeledGraph/LabeledGraph.adoc[LabeledGraph]

2.2. m3

Synopsis

a language independent meta model for facts about source code, which is extensible to include language specific modeling elements

Description
this documentation awaits adaptation of m3 with the Rascal compiler

This is the core language independent model:

  • M3: the m3 constructor is identified by the name of a project encoded as a [$Expressions/Values/Location] and has annotations for each kind of fact extracted from a project.

For language-specific support, please go here:

  • [lang/java/m3]

To get started with m3 immediately, please have a look at:

  • [$lang/java/jdt/m3/Core/createM3FromEclipseProject]

Examples
  • See [$Recipes:Metrics/MeasuringJava] for a step-by-step by-example recipe for how to use M3 for measuring things about Java:

2.3. statistics

Synopsis

Statistical functions.

Description

A collection of statistical functions based on the Apache statistics library.

We do not provide a course on (or even an introduction to) statistics. Useful background information can be found here:

The following functionality is offered:

Pitfalls
  • Be aware that in creating data for statistical analysis, repeated values may occur. This implies that you should avoid creating sets of observations. This also explains why the functions provided here take lists (with elements of various types) as argument.

  • The validity of several of the statistics depend on the assumption that the observations included in the model are drawn from a Bivariate Normal Distribution. This is explicitly stated for functions this is the case.

The statistics library is still highly experimental. Interfaces may change and functions maybe added or deleted without notice.

Unresolved directive in analysis/statistics/statistics.adoc - include::Correlation/Correlation.adoc[Correlation]

Unresolved directive in analysis/statistics/statistics.adoc - include::Descriptive/Descriptive.adoc[Descriptive]

Unresolved directive in analysis/statistics/statistics.adoc - include::Frequency/Frequency.adoc[Frequency]

Unresolved directive in analysis/statistics/statistics.adoc - include::Inference/Inference.adoc[Inference]

Unresolved directive in analysis/statistics/statistics.adoc - include::SimpleRegression/SimpleRegression.adoc[SimpleRegression]

3. lang

Synopsis

Definitions and tools for various languages.

Description
  • RSF: Functions for reading/writing the Rigi Standard Format (RSF).

    • readRSF: Read a file in Rigi Standard Format (RSF).

  • csv: Comma-Separated Values (CSV).

  • java: Definitions and tools related to the Java language.

    • jdt: tools for Java provided via reusing the Eclipse JDT.

    • m3: Java-specific version of the M3 model.

  • xml: XML utilities.

3.1. RSF

Synopsis

Functions for reading/writing the Rigi Standard Format (RSF).

Usage

import lang::RSF::IO;

Description

Rigi Standard Format (RSF) is a textual format to represent binary relations and is used to exchange relational facts between different tools.

An RSF file consists of triples of the form

$RelName$ $Elem_1$ $Elem_2$

where RelName is the name of a relation and Elem1 and Elem2 are element values.

Provides the following function:

  • readRSF: Read a file in Rigi Standard Format (RSF).

Examples
call    main          printf
call    main          listcreate
data    main          FILE
data    listcreate    List

defines two relations named call and data.

3.1.1. readRSF

Synopsis

Read a file in Rigi Standard Format (RSF).

Function

map[str, rel[str,str]] readRSF(str nameRSFFile) throws IO(str msg)

Description

Since an RSF file may define more than one relation, a mapping from relation name to relation value is returned.

Examples

For the RSF file:

call    main          printf
call    main          listcreate
data    main          FILE
data    listcreate    List

readRSF will create the following map:

("call" : {<"main", "printf">, <"main", "listcreate">},
 "data" : {<"main", "FILE">, <"listcreate", "List">})

3.2. csv

Synopsis

Comma-Separated Values (CSV).

Description

The CSV format was originally intended for exchanging information between spreadsheets and databases but is today used as an exchange format in many other application domains as well. A CSV file has the following structure:

  • An optional header line consisting of field names separated by comma’s.

  • One or more lines consisting of values separated by comma’s.

Some adaptation is possible and includes:

  • Including or excluding the header line (use "header" : "true" in the option map for the various functions).

  • Using another separator than a comma (use "separator" : ";" in the option map for the various functions, where ";" can be any single character string).

The following functions are provided in the [Rascal-Libraries-lang-csv-IO] library:

Examples

Here is an example CSV file using the default separator (","):

field_name1,field_name2,field_name3
aaa,bbb,ccc
zzz,yyy,xxx

Here is an example CSV file using a non-default separator (";"):

position;artist;title;year
1;Eagles;Hotel California;1977
2;Queen;Bohemian rhapsody;1975
3;Boudewijn de Groot;Avond;1997

3.3. java

Synopsis

Definitions and tools related to the Java language.

3.3.1. jdt

Synopsis

tools for Java provided via reusing the Eclipse JDT

m3
Synopsis

functions for generating M3 models starting from Eclipse projects

3.3.2. m3

Synopsis

Java-specific version of the M3 model

Description

This API extends m3 with Java specific functionality:

Use this API to extract Java m3 models starting from Eclipse Java projects:

Pitfalls

Unresolved directive in lang/java/m3/m3.adoc - include::AST/AST.adoc[AST]

Unresolved directive in lang/java/m3/m3.adoc - include::Core/Core.adoc[Core]

Unresolved directive in lang/java/m3/m3.adoc - include::TypeHierarchy/TypeHierarchy.adoc[TypeHierarchy]

Unresolved directive in lang/java/m3/m3.adoc - include::TypeSymbol/TypeSymbol.adoc[TypeSymbol]

3.4. xml

Synopsis

XML utilities

Description

XML is a widely used markup language for encoding and exchanging documents.

The following functions and datatypes are provided, all based on the Document Object Model (DOM):

4. util

Synopsis

Utilities: functions, data types and interfaces with external libraries.

Description

Unresolved directive in util/util.adoc - include::Benchmark/Benchmark.adoc[Benchmark]

4.1. Clipboard

documentation awaits Eclipse integration

4.2. ContentCompletion

documentation awaits Eclipse integration

4.3. Editors

documentation awaits Eclipse integration

Unresolved directive in util/util.adoc - include::Eval/Eval.adoc[Eval]

4.4. IDE

documentation awaits Eclipse integration

Unresolved directive in util/util.adoc - include::Math/Math.adoc[Math]

Unresolved directive in util/util.adoc - include::Monitor/Monitor.adoc[Monitor]

4.5. ParseTreeUI

documentation awaits Eclipse integration

Unresolved directive in util/util.adoc - include::PriorityQueue/PriorityQueue.adoc[PriorityQueue]

4.6. Prompt

documentation awaits Eclipse integration

4.7. ResourceMarkers

documentation awaits Eclipse integration