Libraries

bool arbBool()

Return an arbitrary Boolean value.

arbInt is a convenient generator for arbitrary binary choices.

bool fromString(str s)

Convert the strings "true" or "false" to a bool.

int toInt(bool b)

Convert a Boolean value to integer.

Maps true to 1 and false to 0.

real toReal(bool b)

Convert Boolean value to real.

Maps true to 1.0 and false to 0.0.

str toString(bool b)

Convert Boolean value to string.

Maps true to "true" and false to "false".

Content wraps the HTTP Request/Response API to support interactive visualization types on the terminal [Rascal.REPL].

Values wrapped in a Content wrapper will be displayed by interactive Rascal applications such as the IDE, the REPL terminal and the documentation pages.

For example, a piece of html can be displayed directly like such:

In its most general form, Content is an HTTP(s) webserver callback, such that you might deliver any kind of content, based on any kind of request. If you produce a Content value which processes requests dynamically, subsequent interaction from the web browser will be processed as well. So using the Content wrapper you can start an interactive user experience in the browser directly from the REPL.

Content values stay plugged into the application server that is hidden in the REPL environment until they have not been used for at least 30 minutes. If you want the same interaction back after 30 minutes of non-usage, you have to produce another Content value on the commandline.

When you are happy with the interaction, or you want a permanent visualization which is not garbage collected after 30 minutes, you can consider wrapping the same callback in a webserver using the [util::Webserver::serve] function.

Content html(str html)

Directly serve a static html page

Content file(loc src)

Directly serve the contents of a file

Content text(str text)

Directly serve the contents of a string as plain text

value (type[value] expected)

Request values represent what a browser is asking for, most importantly the URL path.

A request value also contains the full HTTP headers, the URL parameters as a map[str,str] and possibly uploaded content, also coded as a map[str,str]. From the constructor type, put or get you can see what kind of HTTP request it was.

A response encodes what is send back from the server to the browser client.

The three kinds of responses, encode either content that is already a str, some file which is streamed directly from its source location or a jsonResponse which involves a handy, automatic, encoding of Rascal values into json values.

Utility to quickly render a string as HTML content

Response plain(str text)

Utility to quickly make a plaintext response.

Utility to serve a file from any source location.

Encoding of HTTP status

datetime now()

Get the current datetime.

datetime createDate(int year, int month, int day)

Create a new date.

Create a new time (with optional timezone offset).

Create a new datetime (with optional timezone offset).

datetime joinDateAndTime(datetime date, datetime time)

Create a new datetime by combining a date and a time.

tuple[datetime date, datetime time] splitDateTime(datetime dt)

Split an existing datetime into a tuple with the date and the time.

Increment the years by given amount or by 1.

Increment the months by a given amount or by 1. .Function

Increment the days by given amount or by 1.

Increment the hours by a given amount or by 1.`

Increment the minutes by a given amount or by 1.

Increment the seconds by a given amount or by 1.

Increment the milliseconds by a given amount or by 1.

Decrement the years by a given amount or by 1.

Decrement the months by a given amount or by 1.

Decrement the days by a given amount or by 1.

Decrement the hours by a given amount or by 1.

Decrement the minutes by a given amount or by 1.

Decrement the seconds by a given amount or by 1.

Decrement the milliseconds by a given amount or by 1.

A closed interval on the time axis.

interval createInterval(datetime begin, datetime end)

Given two datetime values, create an interval.

A duration of time, measured in individual years, months, etc.

tuple[int,int,int,int,int,int,int] createDurationInternal(datetime begin, datetime end)

Create a new duration representing the duration between the begin and end dates.

int daysInInterval(interval i)

Return the number of days in an interval, including the begin and end days.

int daysDiff(datetime begin, datetime end)

Return the difference between two dates and/or datetimes in days.

list[datetime] dateRangeByDay(interval i)

Given an interval, return a list of days.

Given an interval i, return a list of days [i.begin, …​, i.end].

datetime parseDate(str inputDate, str formatString)

Parse an input date given as a string using the given format string.

datetime parseDateInLocale(str inputDate, str formatString, str locale)

Parse an input date given as a string using a specific locale and format string.

datetime parseTime(str inputTime, str formatString)

Parse an input time given as a string using the given format string.

datetime parseTimeInLocale(str inputTime, str formatString, str locale)

Parse an input time given as a string using a specific locale and format string.

datetime parseDateTime(str inputDateTime, str formatString)

Parse an input datetime given as a string using the given format string.

datetime parseDateTimeInLocale(str inputDateTime, str formatString, str locale)

Parse an input datetime given as a string using a specific locale and format string.

Print an input date using the given format string.

Print an input date using a specific locale and format string.

Print an input time using the given format string.

Print an input time using a specific locale and format string.

Print an input datetime using the given format string.

Print an input datetime using a specific locale and format string.

datetime arbDateTime()

Create a new arbitrary datetime.

The Exception datatype used in all Rascal exceptions.

Since declarations for ADTs are extensible, the user can add new exceptions when needed.

Exceptions are either generated by the Rascal run-time (e.g., IndexOutOfBounds) or they are generated by a throw. Exceptions can be caught with a try catch.

Import relevant libraries:

Define the map weekend and do a subscription with a non-existing key:

Repeat this, but catch the exception. We use variable N to track what happened:

void registerLocations(str scheme, str authority, map[loc logical, loc physical] m)

register a logical file scheme including the resolution method via a table.

Logical source location schemes, such as |java+interface://JRE/java/util/List| are used for precise qualified names of artifacts while abstracting from their physical location in a specific part of a file on disk or from some webserver or source repository location.

Using this function you can create your own schemes. The authority field is used for scoping the names you wish to resolve to certain projects. This way one name can resolve to different locations in different projects.

void unregisterLocations(str scheme, str authority)

undo the effect of [registerLocations]

For debugging or for memory management you may wish to remove a lookup table.

loc resolveLocation(loc l)

void appendToFile(loc file, value V…​) throws PathNotFound, IO

Append a value to a file.

Append a textual representation of some values to an existing or a newly created file:

The existing file can be stored using any character set possible, if you know the character set, please use appendToFileEnc. Else the same method of deciding the character set is used as in readFile.

void appendToFileEnc(loc file, str charset, value V…​) throws PathNotFound, IO

Append a value to a file.

Append a textual representation of some values to an existing or a newly created file:

Files are encoded using the charset provided.

set[str] charsets()

Returns all available character sets.

set[str] canEncode(str charset)

Returns whether this charset can be used for encoding (use with writeFile)

bool bprintln(value arg)

Print a value and return true.

Print a value and return true. This is useful for debugging complex Boolean expressions or comprehensions. The only difference between this function and println is that its return type is bool rather than void.

bool exists(loc file)

Check whether a given location exists.

Check whether a certain location exists, i.e., whether an actual file is associated with it.

Does the library file IO.rsc exist?

loc find(str name, list[loc] path) throws PathNotFound

Find a named file in a list of locations.

Find the file IO.rsc in the standard library:

bool isDirectory(loc file)

Check whether a given location is a directory.

Check whether the location file is a directory.

void iprint(value arg, int lineLimit = 1000)

Print an indented representation of a value.

See iprintExp for a version that returns its argument as result and iprintln for a version that adds a newline and iprintToFile for a version that prints to a file.

void iprintToFile(loc file, value arg)

Print an indented representation of a value to the specified location.

See iprint for a version that displays the result on the console and iprintExp for a version that returns its argument as result and iprintln for a version that adds a newline.

&T iprintExp(&T v)

Print an indented representation of a value and returns the value as result.

See iprintlnExp for a version that adds a newline.

&T iprintlnExp(&T v)

Print an indented representation of a value followed by a newline and returns the value as result.

See iprintExp for a version that does not add a newline.

void iprintln(value arg, int lineLimit = 1000)

Print a indented representation of a value and add a newline at the end.

See iprintlnExp for a version that returns its argument as result and iprint for a version that does not add a newline.

By default we only print the first 1000 lines, if you want to print larger values, either use writeTextValueFile or change the limit with the lineLimit parameter.

bool isFile(loc file)

Check whether a given location is actually a file (and not a directory).

Check whether location file is actually a file.

datetime lastModified(loc file)

Last modification date of a location.

Returns last modification time of the file at location file.

Determine the last modification date of the Rascal standard library:

void touch(loc file)

Set the modification date of a file to now or create the file if it did not exist yet

void setLastModified(loc file, datetime timestamp)

Set the modification date of a file to the timestamp

list[str] listEntries(loc file)

List the entries in a directory.

List the entries in directory file.

List all entries in the standard library:

void mkDirectory(loc file) throws PathNotFound, IO

Create a new directory.

Create a directory at location file.

void print(value arg)

Print a value without subsequent newline.

Print a value on the output stream. See println for a version that adds a newline and printExp for a version that returns its argument as value.

Note that the only difference with println is that no newline is added after the value is printed

WARNING: unexpected errors in the above SHELL example. Documentation author please fix! NOTE: Since print does not add a newline, the prompt ok appears at a weird place, i.e., glued to the output of print.

Print a value and return it as result.

WARNING: unexpected errors in the above SHELL example. Documentation author please fix!

Print a value to the output stream and add a newline.

Print a value on the output stream followed by a newline. See print for a version that does not add a newline and printlnExp for a version that returns its argument as value.

Introduce variable S and print it:

Introduce variable L and print it:

Use a string template to print several values:

Just print a newline

Print a value followed by a newline and return it as result.

void rprint(value arg)

Raw print of a value.

This function is only available for internal use in the Rascal development team.

void rprintln(value arg)

Raw print of a value followed by newline.

This function is only available for internal use in the Rascal development team.

str readFile(loc file) throws PathNotFound, IO

Read the contents of a location and return it as string value.

Return the contents of a file location as a single string. Also see readFileLines.

A text file can be encoded in many different character sets, most common are UTF8, ISO-8859-1, and ASCII. If you know the encoding of the file, please use the readFileEnc and readFileLinesEnc overloads. If you do not know, we try to detect this. This detection is explained below:

To summarize, we use UTF-8 by default, except if the location has available meta-data, the file contains a BOM, or the first 32 bytes of the file are not valid UTF-8.

str readFileEnc(loc file, str charset) throws PathNotFound, IO

Read the contents of a location and return it as string value.

Return the contents (decoded using the Character set supplied) of a file location as a single string. Also see readFileLinesEnc.

str uuencode(loc file) throws PathNotFound, IO

list[int] readFileBytes(loc file) throws PathNotFound, IO

Read the contents of a file and return it as a list of bytes.

list[str] readFileLines(loc file) throws PathNotFound, IO

Read the contents of a file location and return it as a list of strings.

Return the contents of a file location as a list of lines. Also see readFile.

Look at readFile to understand how this function chooses the character set. If you know the character set used, please use readFileLinesEnc.

list[str] readFileLinesEnc(loc file, str charset) throws PathNotFound, IO

Read the contents of a file location and return it as a list of strings.

Return the contents (decoded using the Character set supplied) of a file location as a list of lines. Also see readFileLines.

void remove(loc file) throws IO

void writeFile(loc file, value V…​) throws PathNotFound, IO

Write values to a file.

Write a textual representation of some values to a file:

Files are encoded in UTF-8, in case this is not desired, use writeFileEnc.

void writeFileBytes(loc file, list[int] bytes) throws PathNotFound, IO

Write a list of bytes to a file.

void writeFileEnc(loc file, str charset, value V…​) throws PathNotFound, IO

Write values to a file.

Write a textual representation of some values to a file:

Files are encoded using the charset provided.

str md5HashFile(loc file) throws PathNotFound, IO

Read the contents of a location and return its MD5 hash.

MD5 hash the contents of a file location.

str createLink(str title, str target)

str toBase64(loc file) throws PathNotFound, IO

bool copyFile(loc source, loc target)

bool copyDirectory(loc source, loc target)

loc arbLoc()

list[&T] concat(list[list[&T]] xxs)

Concatenate a list of lists.

list[&T] delete(list[&T] lst, int n)

Delete an element from a list.

Delete the n-th element from a list. A new list without the n-th element is returned as result. The IndexOutOfBounds exception is thrown when n is not a valid index.

map[&T element, int occurs] distribution(list[&T] lst)

Get the distribution of the elements of the list. That is how often does each element occur in the list?

list[&T] drop(int n, list[&T] lst)

Drop elements from the head of a list.

Drop n elements (or size(lst) elements if size(lst) < n) from the head of lst. See take to get elements from the head of a list].

list[&T] dup(list[&T] lst)

Remove multiple occurrences of elements in a list. The first occurrence remains.

&T elementAt(list[&T] lst, int index)

&T getOneFrom(list[&T] lst)

Pick a random element from a list.

Get an arbitrary element from a list. See takeOneFrom for a function that also removes the selected element.

Pick first element from a list.

Get the first element from a list. As opposed to getOneFrom this function always returns the same (first) list element.

Get the first element(s) from a list.

Get the first element:

An exception is thrown when taking the head of an empty list:

Get the first n elements:

An exception is thrown when the second argument exceeds the length of the list:

Split a list in a head and a tail.

This function is identical to pop.

list[int] index(list[&T] lst)

A list of legal index values of a list.

Returns a list of all legal index values for a given list lst.

This function is useful in for loops over lists.

int indexOf(list[&T] lst, &T elt)

Index of first occurrence of an element in a list.

Return index of first occurrence of elt in lst, or -1 if elt is not found. Also see lastIndexOf.

list[&T] insertAt(list[&T] lst, int n, &T elm) throws IndexOutOfBounds

Insert an element at a specific position in a list.

Returns a new list with the value of elm inserted at index position n of the old list.

An exception is thrown when the index position is outside the list:

str intercalate(str sep, list[value] l)

Join a list of values into a string separated by a separator.

list[&T] intersperse(&T sep, list[&T] xs)

Intersperses a list of values with a separator.

bool isEmpty(list[&T] lst)

Test whether a list is empty.

Returns true when a list is empty and false otherwise.

Return the last element of a list, if any.

Also see tail that returns a list of one or more of the last elements of a list.

int lastIndexOf(list[&T] lst, &T elt)

Return index of last occurrence of elt in lst, or -1 if elt is not found.

Also see indexOf.

list[&U] mapper(list[&T] lst, &U (&T) fn)

Apply a function to all list elements and return list of results.

Apply a function fn to each element of lst and return the list of results.

Determine the largest element in a list.

Merge the elements of two sorted lists into one list.

Merge the elements of two sorted lists into one list using the built-in ordering between values. Optional, a comparison function lessOrEqual may be given for a user-defined ordering between values.

Merge two lists of strings and use their length as ordering:

Determine the smallest element in a list.

list[&T] mix(list[&T] l, list[&T] r)

Mix the elements of two lists.

Let n be the minimum of the length of the two lists l and r. mix returns a list in which the first n elements are taken alternately from the left and the right list, followed by the remaining elements of the longest list.

set[list[&T]] permutations(list[&T] lst)

Compute all permutations of a list.

set[list[&T]] permutationsBag(map[&T element, int occurs] b)

tuple[&T, list[&T]] pop(list[&T] lst)

Pop top element from list, return a tuple. .Description This function is identical to headTail. Also see push and top.

list[&T] prefix(list[&T] lst)

Return all but the last element of a list.

list[&T] push(&T elem, list[&T] lst)

Push an element in front of a list.

Also see pop and top.

&T reducer(list[&T] lst, &T (&T, &T) fn, &T unit)

Apply a function to successive elements of list and combine the results (deprecated).

Apply the function fn to successive elements of list lst starting with unit.

WARNING: This function is deprecated, use a reducer instead.

list[&T] remove(list[&T] lst, int indexToDelete)

list[&T] reverse(list[&T] lst)

Reverse a list.

Returns a list with the elements of lst in reverse order.

int size(list[&T] lst)

Determine the number of elements in a list.

list[&T] slice(list[&T] lst, int begin, int len)

Compute a sublist of a list.

Returns a sublist of lst from index start of length len.

Here are the equivalent expressions using the slice notation:

Sort the elements of a list.

Sort the elements of a list:

Shuffle a list.

Returns a random (unbiased) shuffled list.

tuple[list[&T],list[&T]] split(list[&T] l)

Split a list into two halves.

Sum the elements of a list.

Get the tail element(s) from a list.

All but first element:

Try an error case:

Last n elements:

Try an error case:

list[&T] take(int n, list[&T] lst)

Get number of elements from the head of a list.

Get n elements (or size(lst) elements if size(lst) < n) from the head of the list. See drop to remove elements from the head of a list.

tuple[&T, list[&T]] takeOneFrom(list[&T] lst)

Remove an arbitrary element from a list, returns the element and the modified list.

Select an arbitrary element from lst, and return a tuple consisting of:

See getOneFrom to only selected an element from a list.

list[&T] takeWhile(list[&T] lst, bool (&T a) take)

Take elements from the front of the list as long as a predicate is true.

map[&A,list[&B]] toMap(list[tuple[&A, &B]] lst) throws MultipleKey

Convert a list of pairs to a map; first elements are associated with a set of second elements.

Convert a list of tuples to a map in which the first element of each tuple is associated with the set of second elements from all tuples with the same first element. Keys should be unique.

toMap collects all values in tuples with the same first value in a set. Contrast this with toMapUnique that associates each first tuple value with the second tuple value, but imposes the constraint that those keys are unique.

map[&A,&B] toMapUnique(list[tuple[&A, &B]] lst) throws MultipleKey

Convert a list of tuples to a map; result must be a map.

Convert a list of tuples to a map; result must be a map.

Let’s explore an error case:

The keys in a map are unique by definition. toMapUnique throws a MultipleKey exception when the list contains more than one tuple with the same first value.

&T top([&T t, *&T _])

Take the top element of a list. .Description This function is identical to [head]. Also see pop and push.

rel[&T,&T] toRel(list[&T] lst)

Convert a list to a relation. .Description Convert a list to relation, where each tuple encodes which elements are followed by each other. This function will return an empty relation for empty lists and for singleton lists.

set[&T] toSet(list[&T] lst)

Convert a list to a set.

Convert lst to a set.

Note that the same can be done using splicing

str toString(list[&T] lst)

Convert a list to a string.

Convert lst to a string.

str itoString(list[&T] lst)

Convert a list to an indented string.

Convert lst to a indented string.

tuple[list[&T],list[&U]] unzip2(list[tuple[&T,&U]] lst)

Make a pair (triple) of lists from a list of pairs (triples).

Also see [List-unzip];

tuple[list[&T],list[&U],list[&V]] unzip3(list[tuple[&T,&U,&V]] lst)

list[int] upTill(int n)

Returns the list 0,1..n-1. .Description Returns the list 0, 1, .., n-1, this is slightly faster than [0..n], since the returned values are shared.

list[tuple[&T first, &U second]] zip2(list[&T] a, list[&U] b)

Make a list of pairs from two (three) lists of the same length.

Also see [List-unzip].

WARNING: unexpected errors in the above SHELL example. Documentation author please fix!

list[tuple[&T first, &U second, &V third]] zip3(list[&T] a, list[&U] b, list[&V] c)

Return the list of all elements in any tuple in a list relation.

A list relation restricted to certain element values in tuples.

Returns list relation R restricted to tuples with elements in set S.

A list relation excluding tuples containing certain values.

Returns list relation R excluding tuples with some element in S.

Complement of a list relation.

Given a list relation R a new relation U can be constructed that contains all possible tuples with element values that occur at corresponding tuple positions in R. The function complement returns the complement of R relative to U, in other words: U - R.

Declare R and compute corresponding U:

Here is the complement of R computed in two ways:

Domain of a list relation: a list consisting of the first element of each tuple, uniquely.

The domain can be seen as all possible inputs of the relation image operation. The result contains elements (or tuples) in the order of appearance of the original relation, but all occurences after the first occurrence of an element have been removed.

List relation restricted to certain domain elements.

Restriction of a list relation R to tuples with first element in S.

List relation excluding certain domain values.

List relation R excluding tuples with first element in S.

list[list[&U]] groupDomainByRange(lrel[&U dom, &T ran] input)

Make sets of elements in the domain that relate to the same element in the range.

list[list[&T]] groupRangeByDomain(lrel[&U dom, &T ran] input)

Make sets of elements in the range that relate to the same element in the domain.

lrel[&T, &T] ident (list[&T] S)

The identity list relation.

The identity list relation for set S.

Invert the tuples in a list relation.

The range is composed of all but the first element of each tuple of a list relation, uniquely.

The range can be seen as all the elements of in all possible images of the relation. The result contains elements (or tuples) in the order of appearance of the original relation, but all occurences after the first occurrence of an element have been removed.

List relation restricted to certain range values.

Restriction of binary list relation R to tuples with second element in set S.

List relation excluding certain range values.

Restriction of binary list relation R to tuples with second element not in set S.

map[&K, set[&V]] index(lrel[&K, &V] R)

Listes a binary list relation as a map

Converts a binary list relation to a map of the domain to a set of the range.

list[&T] squeeze(list[&T] xs)

bool isSameFile(loc l, loc r)

Check that two locations refer to the same file.

bool isLexicallyLess(loc l, loc r)

Compare two location values lexicographically.

When the two locations refer to different files, their paths are compared as string. When they refer to the same file, their offsets are compared when present.

This ordering regards the location value itself as opposed to the text it refers to.

str getContent(loc l)

Get the textual content a location refers to.

bool isStrictlyContainedIn(loc inner, loc outer)

Is a location textually (strictly) contained in another location?

Strict containment between two locations inner and outer holds when

bool isContainedIn(loc inner, loc outer)

Is a location textually contained in another location?

Containment between two locations inner and outer holds when

bool beginsBefore(loc l, loc r)

Begins a location’s text before (but may overlap with) another location’s text?

bool isBefore(loc l, loc r)

Begins and ends a location’s text before another location’s text?

isBefore(l, r) holds when l 's text occurs textually before r 's text.

bool isImmediatelyBefore(loc l, loc r)

Occurs a location’s text immediately before another location’s text?

isImmediatelyBefore(l, r) holds when l 's text occurs textually before, and is adjacent to, r 's text.

bool beginsAfter(loc l, loc r)

Begins a location’s text after (but may overlap with) another location’s text?

Description beginsAfter(l, r) holds when l 's text begins after r 's text. No assumption is made about the end of both texts. In other words, l 's text may end before or after the end of r 's text.

bool isAfter(loc l, loc r)

Is a location’s text completely after another location’s text?

bool isImmediatelyAfter(loc l, loc r)

Is a location’s text immediately after another location’s text?

bool isOverlapping(loc l, loc r)

Refer two locations to text that overlaps?

loc cover(list[loc] locs)

Compute a location that textually covers the text of a list of locations.

Create a new location that refers to the smallest text area that overlaps with the text of the given locations. The given locations should all refer to the same file but they may be overlapping or be contained in each other.

map[&K,&V] delete(map[&K,&V] m, &K k)

Delete a key from a map.

Returns the map m minus the key k.

set[&K] domain(map[&K, &V] M)

Determine the domain (set of keys) of a map.

Returns the domain (set of keys) of map M.

map[&K, &V] domainR(map[&K, &V] M, set[&K] S)

Map restricted to certain keys.

Return the map M restricted to pairs with key in S.

map[&K, &V] domainX(map[&K, &V] M, set[&K] S)

Map with certain keys excluded.

Return the map M restricted to pairs with key not in S.

&K getOneFrom(map[&K, &V] M)

Get a n arbitrary key from a map.

Returns an arbitrary key of map M.

map[&V, set[&K]] invert(map[&K, &V] M)

Invert the (key,value) pairs in a map.

Returns inverted map in which each value in the old map M is associated with a set of key values from the old map. Also see invertUnique.

map[&V, &K] invertUnique(map[&K, &V] M)

Invert the (key,value) pairs in a map.

Returns a map with key and value inverted; the result should be a map. If the initial map contains duplicate values, the MultipleKey exception is raised since an attempt is made to create a map where more than one value would be associated with the same key.

Also see invert and Exception.

Here is an examples that generates an exception:

bool isEmpty(map[&K, &V] M)

Test whether a map is empty.

Returns true if map M is empty, and false otherwise.

map[&K, &V] mapper(map[&K, &V] M, &L (&K) F, &W (&V) G)

Apply a function to all (key, value) pairs in a map.

Apply the functions F and G to each key/value pair in a map and return the transformed map.

set[&V] range(map[&K, &V] M)

The range (set of values that correspond to its keys) of a map.

Returns the range (set of values) of map M.

map[&K, &V] rangeR(map[&K, &V] M, set[&V] S)

Map restricted to certain values in (key,values) pairs.

Returns the map restricted to pairs with values in S.

map[&K, &V] rangeX(map[&K, &V] M, set[&V] S)

Map with certain values in (key,value) pairs excluded.

Returns the map restricted to pairs with values not in S.

int size(map[&K, &V] M)

Number of (key, value) pairs in a map.

Returns the number of pairs in map M.

list[tuple[&K, &V]] toList(map[&K, &V] M)

Convert a map to a list of tuples.

Convert a map to a relation.

str toString(map[&K, &V] M)

Convert a map to a string.

str itoString(map[&K, &V] M)

Convert a map to a indented string.

Messages can be used to communicate information about source texts. They can be interpreted by IDE’s to display type errors and warnings, etc.

int arity(node T)

Determine the number of children of a node.

list[value] getChildren(node T)

Get the children of a node.

map[str,value] getKeywordParameters(node T)

Get the keyword parameters of a node.

map[str, value] getAnnotations(node T)

&T <: node setKeywordParameters(&T <: node x, map[str,value] keywordParameters)

Set the keyword parameters of a node.

&T <: node setAnnotations(&T <: node x, map[str,value] keywordParameters)

str getName(node T)

Determine the name of a node.

node makeNode(str N, value V…​, map[str, value] keywordParameters = ())

Create a node given its function name and arguments.

&T <: node unset(&T <: node x, str keywordParameter)

Reset a specific keyword parameter back to their default on a node.

&T <: node delAnnotation(&T <: node x, str keywordParameter)

Reset a set of keyword parameters back to their default on a node.

&T <: node delAnnotations(&T <: node x)

&T unsetRec(&T x)

Recursively reset all keyword parameters of the node and its children back to their default.

&T delAnnotationsRec(&T x)

Recursively reset a specific keyword parameter of the node and its children back to its default.

node arbNode()

str toString(node T)

Convert a node to a string.

str itoString(node T)

Convert a node to an indented string.

The Tree data type as produced by the parser.

A Tree defines the trees normally found after parsing; additional constructors exist for execptional cases:

Production in ParseTrees

The type Production is introduced in Type, see Production. Here we extend it with the symbols that can occur in a ParseTree. We also extend productions with basic combinators allowing to construct ordered and un-ordered compositions, and associativity groups.

Attributes in productions.

An Attr (attribute) documents additional semantics of a production rule. Neither tags nor brackets are processed by the parser generator. Rather downstream processors are activated by these. Associativity is a parser generator feature though.

Associativity attribute.

Associativity defines the various kinds of associativity of a specific production.

Character ranges and character class .Description

list[CharRange]

Symbols that can occur in a ParseTree

The type Symbol is introduced in Type, see Symbol, to represent the basic Rascal types, e.g., int, list, and rel. Here we extend it with the symbols that may occur in a ParseTree.

bool subtype(Symbol::\sort(_), Symbol::\adt("Tree", _))

Datatype for declaring preconditions and postconditions on symbols

A Condition can be attached to a symbol; it restricts the applicability of that symbol while parsing input text. For instance, follow requires that it is followed by another symbol and at-column requires that it occurs at a certain position in the current line of the input text.

Production priority(Symbol s, [*Production a, priority(Symbol _, list[Production] b), *Production c])

Nested priority is flattened.

Normalization of associativity.

Parse input text (from a string or a location) and return a parse tree.

The parse either throws ParseError exceptions or returns parse trees of type Tree. See .

The allowAmbiguity flag dictates the behavior of the parser in the case of ambiguity. When allowAmbiguity=true the parser will construct ambiguity clusters (local sets of parse trees where the input string is ambiguous). If it is false the parser will throw an Ambiguous exception instead which is comparable to a ParseError exception. The latter option terminates faster.

The hasSideEffects flag is normally set to false. When a uses side-effects to filter ambiguity, this option must be set to true to ensure correct behavior. Otherwise the parser employs optimizations which assume the parse tree construction algorithm is context-free. When filter functions associated with syntax definitions exist that use global variables, for example to store type definitions in a symbol table , then this option must be set to true.

Seeing that parse returns a parse tree:

Catching a parse error:

&T (value input, loc origin) parser(type[&T] grammar, bool allowAmbiguity=false, bool hasSideEffects=false, bool firstAmbiguity=false)

Generates a parser from an input grammar.

This builtin function wraps the Rascal parser generator by transforming a grammar into a parsing function.

The resulting parsing function has the following overloaded signature:

So the parse function reads either directly from a str or via the contents of a loc. It also takes a origin parameter which leads to the prefix of the src fields of the resulting tree.

The parse function behaves differently depending of the given keyword parameters: * allowAmbiguity: if true then no exception is thrown in case of ambiguity and a parse forest is returned. if false, * the parser throws an exception during tree building and produces only the first ambiguous subtree in its message. * if set to false, the parse constructs trees in linear time. if set to true the parser constructs trees in polynomial time. * * hasSideEffects: if false then the parser is a lot faster when constructing trees, since it does not execute the parse actions in an * interpreted environment to make side effects (like a symbol table) and it can share more intermediate results as a result. * * firstAmbiguity: if true, then the parser returns the subforest for the first (left-most innermost) ambiguity instead of a parse tree for * the entire input string. This is for grammar debugging purposes a much faster solution then waiting for an entire * parse forest to be constructed in polynomial time.

&U (type[&U] nonterminal, value input, loc origin) parsers(type[&T] grammar, bool allowAmbiguity=false, bool hasSideEffects=false, bool firstAmbiguity=false)

Generates parsers from a grammar (reified type), where all non-terminals in the grammar can be used as start-symbol.

This parser generator behaves the same as the parser function, but it produces parser functions which have an additional nonterminal parameter. This can be used to select a specific non-terminal from the grammar to use as start-symbol for parsing.

This function is similar to the function in its functionality. However, in case of serious ambiguity parse could be very slow. This function is much faster, because it does not try to construct an entire forest and thus avoids the cost of constructing nested ambiguity clusters.

If the input sentence is not ambiguous after all, simply the entire tree is returned.

str unparse(Tree tree)

Yield the string of characters that form the leafs of the given parse tree.

unparse is the inverse function of parse, i.e., for every syntactically correct string TXT of type S, the following holds:

First parse an expression, this results in a parse tree. Then unparse this parse tree:

str printSymbol(Symbol sym, bool withLayout)

&T<:value implode(type[&T<:value] t, Tree tree)

Implode a parse tree according to a given (ADT) type.

Given a grammar for a language, its sentences can be parsed and the result is a parse tree (or more precisely a value of type Tree). For many applications this is sufficient and the results are achieved by traversing and matching them using concrete patterns.

In other cases, the further processing of parse trees is better done in a more abstract form. The abstract syntax for a language is a data type that is used to represent programs in the language in an abstract form. Abstract syntax has the following properties:

The function implode bridges the gap between parse tree and abstract syntax tree. Given a parse tree and a Rascal type it traverses them simultaneously and constructs an abstract syntax tree (a value of the given type) as follows:

An IllegalArgument exception is thrown if during implosion a tree is encountered that cannot be imploded to the expected type in the ADT. As explained above, this function assumes that the ADT type names correspond to syntax non-terminal names, and constructor names correspond to production labels. Labels of production arguments do not have to match with labels in ADT constructors.

Finally, source location fields are propagated as keyword fields on constructor ASTs. To access them, the user is required to explicitly declare a keyword field on all ADTs used in implosion. In other words, for every ADT type T, add:

Here are some examples for the above rules.

Given the grammar

Decls will be imploded as:

(assuming Id is a lexical non-terminal).

Given the grammar

The corresponding ADT could be:

Given the grammar

In this case, a Decl is imploded into the following ADT:

Given the grammar

Can be imploded into:

Tree search result type for treeAt.

Select the innermost Tree of a given type which is enclosed by a given location.

Determine if the given type is a non-terminal type.

Return the set of all elements in any tuple in a relation.

A relation restricted to certain element values in tuples.

Returns relation R restricted to tuples with elements in set S.

A relation excluded tuples containing certain values.

Returns relation R excluding tuples with some element in S.

Complement of a relation.

Given a relation R a new relation U can be constructed that contains all possible tuples with element values that occur at corresponding tuple positions in R. The function complement returns the complement of R relative to U, in other words: U - R.

Declare R and compute corresponding U:

Here is the complement of R computed in two ways:

Domain of a relation: a set consisting of the first element of each tuple.

Relation restricted to certain domain elements.

Restriction of a relation R to tuples with first element in S.

Relation excluding certain domain values.

Relation R excluded tuples with first element in S.

set[set[&U]] groupDomainByRange(rel[&U dom, &T ran] input)

Make sets of elements in the domain that relate to the same element in the range.

set[set[&T]] groupRangeByDomain(rel[&U dom, &T ran] input)

Make sets of elements in the range that relate to the same element in the domain.

rel[&T, &T] ident (set[&T] S)

The identity relation.

The identity relation for set S.

Invert the tuples in a relation.

The range (i.e., all but the first element of each tuple) of a relation.

rel[&T0,&T1] rangeR (rel[&T0,&T1] R, set[&T2] S)

Relation restricted to certain range values.

Restriction of binary relation R to tuples with second element in set S.

rel[&T0,&T1] rangeX (rel[&T0,&T1] R, set[&T2] S)

Relation excluding certain range values.

Restriction of binary relation R to tuples with second element not in set S.

map[&K, set[&V]] index(rel[&K, &V] R)

Indexes a binary relation as a map

Converts a binary relation to a map of the domain to a set of the range.

map[&K,set[&V]] classify(set[&V] input, &K (&V) getClass)

Classify elements in a set.

We classify animals by their number of legs.

Create a map from animals to number of legs.

Define function nLegs that returns the number of legs for each animal (or 0 when the animal is unknown):

Now classify a set of animals:

set[set[&T]] group(set[&T] input, bool (&T a, &T b) similar)

Group elements in a set given an equivalence function.

We classify animals by their number of legs.

Create a map from animals to number of legs.

Define function nLegs that returns the number of legs fro each animal (or 0 when the animal is unknown):

Now group a set of animals:

map[&T,int] index(set[&T] s)

Map set elements to a fixed index.

bool isEmpty(set[&T] st)

Test whether a set is empty.

Yields true if s is empty, and false otherwise.

set[&U] mapper(set[&T] st, &U (&T) fn)

Apply a function to all set elements and return set of results.

Return a set obtained by applying function fn to all elements of set s.

&T max(set[&T] st)

Determine the largest element of a set.

&T min(set[&T] st)

Determine the smallest element of a set.

set[set[&T]] power(set[&T] st)

Determine the powerset of a set.

Returns a set with all subsets of s.

set[set[&T]] power1(set[&T] st)

The powerset (excluding the empty set) of a set value.

Returns all subsets (excluding the empty set) of s.

Apply a function to successive elements of a set and combine the results (deprecated).

Apply the function fn to successive elements of set s starting with unit.

int size(set[&T] st)

Determine the number of elements in a set.

&T getOneFrom(set[&T] st)

Pick an arbitrary element from a set.

Get "first" element from a set.

Get "first" element of a set. Of course, sets are unordered and do not have a first element. However, we may assume that sets are internally ordered in some way and this ordering is reproducible. Applying getFirstFrom on the same set will always returns the same element.

This function helps to make set-based code more deterministic, for instance, for testing purposes.

tuple[&T, set[&T]] takeOneFrom(set[&T] st)

Remove an arbitrary element from a set, returns the element and a set without that element.

Remove an arbitrary element from set s and return a tuple consisting of the element and a set without that element. Also see getOneFrom.

Remove "first" element from a set, returns the element and a set without that element.

element of a set.

list[&T] toList(set[&T] st)

Convert a set to a list.

Note that the same result can be obtained using splicing:

Recall that the elements of a set are unordered and that there is no guarantee in which order the set elements will be placed in the resulting list.

map[&A,set[&B]] toMap(rel[&A, &B] st)

Convert a set of tuples to a map; each key is associated with a set of values.

Convert a set of tuples to a map in which the first element of each tuple is associated with the set of second elements of all tuples with the same first element.

map[&A,&B] toMapUnique(rel[&A, &B] st) throws MultipleKey

Convert a set of tuples to a map (provided that there are no multiple keys).

Convert a set of tuples to a map. The result should be a legal map (i.e., without multiple keys).

Now explore an erroneous example:

str toString(set[&T] st)

Convert a set to a string.

Recall that the elements of a set are unordered and that there is no guarantee in which order the set elements will be placed in the resulting string.

str itoString(set[&T] st)

Convert a set to an indented string.

Recall that the elements of a set are unordered and that there is no guarantee in which order the set elements will be placed in the resulting string.

Sort the elements of a set.

Sort the elements of a set:

This function lessThan (<) function should implement a strict partial order, meaning:

This function is fast if k is relatively small, say 10 out of a 1000 elements. It operates in O(n*k) time where n is the size of the set.

If k is a larger value, say k > 10, then it’s perhaps better to just sort the entire set using the asympotically faster (n*log^2(n)) sort function and take the first k elements of the resulting list.

If k is a negative number, top will return the largest abs(k) elements of the set instead of the smallest.

set[&T] union(set[set[&T]] sets)

Flatten a set of sets into a single set.

real jaccard(set[value] x, set[value] y)

Compute the Jaccard similarity between two sets.

Center a string in given space.

int charAt(str s, int i) throws IndexOutOfBounds

Return character in a string by its index position.

Return the character at position i in string s as integer character code. Also see stringChar that converts character codes back to string.

list[int] chars(str s)

Return characters of a string. .Description Return a list of the characters of s as integer character codes. Also see stringChars that converts character codes back to string.

bool contains(str input, str find)

Check that a string contains another string.

Check whether the string find occurs as substring in the string subject.

str deescape(str s)

Replace escaped characters by the escaped character itself (using Rascal escape conventions).

bool endsWith(str subject, str suffix)

Check whether a string ends with a given substring.

Yields true if string subject ends with the string suffix.

str escape(str subject, map[str,str] mapping)

Replace single characters in a string.

Return a copy of subject in which each single character key in replacements has been replaced by its associated value.

list[int] findAll(str subject, str find)

Find all occurrences of a string in another string.

Find all occurrences of string find in string subject. The result is a (possible empty) list of positions where find matches.

See also findFirst and findLast.

int findFirst(str subject, str find)

Find the first occurrence of a string in another string.

Find the first occurrence of string find in string subject. The result is either a position in subject or -1 when find is not found.

Also see findAll and findLast.

int findLast(str subject, str find)

Find the last occurrence of a string in another string.

Find the last occurrence of string find in string subject. The result is either a position in subject or -1 when find is not found.

Also see findAll and findFirst.

bool isEmpty(str s)

Check whether a string is empty.

Returns true if string s is empty.

str arbString(int n)

Generate a arbitrary string.

Returns a string of maximum n length, with arbitrary characters.

Left alignment of string in given space.

str replaceAll(str subject, str find, str replacement)

Replace all occurrences of a string in another string.

Return a copy of subject in which all occurrences of find (if any) have been replaced by replacement. Also see replaceFirst and replaceLast.

Note that find is a string (as opposed to, for instance, a regular expression in Java).

str replaceFirst(str subject, str find, str replacement)

Replace the first occurrence of a string in another string.

Return a copy of subject in which the first occurrence of find (if it exists) has been replaced by replacement. Also see replaceAll and replaceLast.

Note that find is a string (as opposed to, for instance, a regular expression in Java).

str replaceLast(str subject, str find, str replacement)

Replace the last occurrence of a string in another string.

Return a copy of subject in which the last occurrence of find (if it exists) has been replaced by replacement. Also see replaceFirst and replaceLast.

Note that find is a string (as opposed to, for instance, a regular expression in Java).

str reverse(str s)

Return a string with all characters in reverse order.

Returns string with all characters of string s in reverse order.

Right alignment of a string value in a given space.

int size(str s)

Determine length of a string value.

Returns the length (number of characters) in string s.

bool startsWith(str subject, str prefix)

Check whether a string starts with a given prefix.

Yields true if string subject starts with the string prefix.

str stringChar(int char) throws IllegalArgument

Convert a character code into a string.

str stringChars(list[int] chars) throws IllegalArgument

Convert a list of character codes into a string.

bool isValidCharacter(int ch)

Check that a given integer value is a valid Unicode code point.

Extract a substring from a string value.

Convert a string value to integer.

Throws IllegalArgument when s cannot be converted.

Now try an erroneous argument:

str toLowerCase(str s)

Convert the characters in a string value to lower case.

Convert all characters in string s to lowercase. Also see toUpperCase.

real toReal(str s)

Convert a string value to real.

Converts string s to a real. Throws IllegalArgument when s cannot be converted.

str toUpperCase(str s)

Convert the characters in a string value to upper case.

Converts all characters in string s to upper case.

Also see toLowerCase.

str trim(str s)

Returns string with leading and trailing whitespace removed.

str squeeze(str src, str charSet)

Squeeze repeated occurrences of characters. .Description Squeeze repeated occurrences in src of characters in charSet removed. See Apache for the allowed syntax in charSet.

list[str] split(str sep, str src)

Split a string into a list of strings based on a literal separator.

str capitalize(str src)

str uncapitalize(str src)

str toBase64(str src)

str fromBase64(str src)

str wrap(str src, int wrapLength)

Word wrap a string to fit in a certain width.

Inserts newlines in a string in order to fit the string in a certain width. It only breaks on spaces (' ').