RascalTutor
Synopsis

The interactive RascalShell

Description

The RascalShell is an interactive console — or if you prefer a Command Line Interface (CLI) or Read Eval Print Loop (REPL) — for entering and executing Rascal expressions, statements and declarations.

In addition, several RascalShell commands and features are available to support the user:

1. Read Eval Print Loop (REPL)

Synopsis

The Rascal Read Eval Print Loop (REPL)

Description

RascalShell is first and foremost an interactive console to execute Rascal code, be it declarations, statements or expressions.

Examples

Rascal code can be a trivial expression

rascal>1+2
[red]##An unexpected internal error occurred##

Or a more complex list comprehension:

rascal>[ n * n | int n <- [0..10] ]
[red]##An unexpected internal error occurred##

Or importing a file and using a function declared in it:

rascal>import List;
[red]##An unexpected internal error occurred##
rascal>size([ n * n | int n <- [0..10] ])
[red]##An unexpected internal error occurred##

Another use is to declare variables

rascal>int x = 2;
ok
rascal>int y = 3;
ok

and use them later on:

rascal>x * y
[red]##An unexpected internal error occurred##
Pitfalls

Rascal is quite demanding as far as the proper placement of semicolons (;) is concerned. The RascalShell is more permissive but at the end of a statement there is still one required.

2. Commands

Synopsis

RascalShell commands

Description

The RascalShell provides several built-in commands:

2.1. Apropos Command

Synopsis

Get help and search documentation, results shown in console.

Syntax
  • apropos

  • apropos Topics

Description

Rascal provides a help system as described in Getting Help.

The apropos command is similar to Help Command, but results are only shown in the RascalShell console (no browser window is opened).

2.2. Break Command

Synopsis

Manage breakpoints.

Syntax
  • break

  • break FunctionName

  • break FunctionName Lino

Description

The Rascal system includes an interactive debugger that allows setting break points, step-by-step execution and more. Break points are identified by their break point number as determined by the order in which they were created.

The first form, lists all current break points.

The second and third form, set a break point for a specific function or line in a function.

2.3. Clear Command

Synopsis

Clear all break points.

Syntax

clear

Description

Removes all break points.

2.4. Declarations Command

Synopsis

Show all declarations in current RascalShell session.

Syntax

declarations

Description

All declarations entered during the current session are shown. Also see Undeclare Command to remove a declaration.

Examples
rascal>real pi = 3.14;
ok
rascal>data D = d1(int n) | d2(str s);
[red]##An unexpected internal error occurred##
rascal>declarations

2.5. Help Command

Synopsis

Get help and search Rascal documentation, results shown in a browser.

Syntax
  • help

  • help Topics

Description

Rascal provides a help system as described in Getting Help.

In the first form, the list of RascalShell commands is printed.

In the second form, the search results for Topics are shown in a browser window.

Use Apropos Command, to get help results shown in the console.

2.6. Modules Command

Synopsis

Show all modules that have been imported in the current RascalShell session.

Syntax

modules

Description

All modules that have been imported during the current session are shown. Also see Unimport Command to remove an imported module.

Examples
rascal>import List;
[red]##An unexpected internal error occurred##
rascal>import Set;
[red]##An unexpected internal error occurred##
rascal>modules
[red]##An unexpected internal error occurred##

2.7. Quit Command

Synopsis

Quit the RascalShell.

Syntax
  • quit

  • Ctrl+d or Eof

Description

Typing quit or Ctrl+d will end the execution of the RascalShell.

2.8. Set Command

Synopsis

Set parameters that control options of RascalShell.

Syntax
  • set

  • set Option TrueOrFalse

Description

RascalShell provides a number of options to control its behaviour. The set command manages their value.

In the first form, the list of current settings is printed.

In the second form a specific option is set to true or false.

The options are:

  • profile: record execution times while executing subsequent Rascal code and print the results after each RascalShell command.

  • trace: while executing Rascal code, print a trace of all function calls.

  • coverage: record which code is executed while executing subsequent Rascal code and print the results after each RascalShell command.

Examples

Turn trace on and execute a function:

rascal>import demo::basic::Factorial;
[red]##An unexpected internal error occurred##
rascal>set trace true
trace set to true
rascal>fac(5)
[red]##An unexpected internal error occurred##

Turn trace off and execute the same function:

rascal>set trace false
trace set to false
rascal>fac(5)
[red]##An unexpected internal error occurred##
Pitfalls

The set command is completely unrelated to Rascal’s built-in set type.

2.9. Test Command

Synopsis

Run tests.

Syntax
  • test

  • test Modules

Description

Run Rascal tests.

In the first form, the tests in all currently imported modules are executed.

In the second form, the tests in the given list of Modules are executed.

Examples

Execute the tests in an imported module:

rascal>import demo::basic::Factorial;
[red]##An unexpected internal error occurred##
rascal>test
No tests to execute; import modules with tests or give list of modules with tests

Execute the tests in the Integers module in the Rascal test suite:

rascal>test lang::rascal::tests::basic::Integers
[red]##NoSuchField("results")##

2.10. Undeclare Command

Synopsis

Remove declarations from the current RascalShell session.

Syntax
  • undeclare Name1 Name2 …​

  • undeclare

Description

When one or more names are given, the corresponding declared entities will be removed from the current session.

When no names are given, all declarations will be removed from the current session.

Also see Declarations Command to list all declarations.

Examples

First declare variable pi and data type D and check that the declarations command lists them:

rascal>real pi = 3.14;
ok
rascal>data D = d1(int n) | d2(str s);
[red]##An unexpected internal error occurred##
rascal>declarations

Now remove the declaration for D and verify that it has indeed been removed:

rascal>undeclare D
[red]##An unexpected internal error occurred##
No declaration for  D found
rascal>declarations

2.11. Unimport Command

Synopsis

Remove imported modules from the current RascalShell session.

Syntax
  • unimport Module1 Module2 …​

  • unimport

Description

When one or more module names are given, they are removed from the list of imported modules.

When no module names are given, all imported modules are removed from the list of imported modules.

Also see Modules Command to list all currently imported modules.

Examples

Import the modules List and 'Set` and check that the modules command lists them:

rascal>import List;
[red]##An unexpected internal error occurred##
rascal>import Set;
[red]##An unexpected internal error occurred##
rascal>modules
[red]##An unexpected internal error occurred##

Now remove the import of module List and verify that it has indeed been removed:

rascal>unimport List
[red]##An unexpected internal error occurred##
No import List found
rascal>modules
[red]##An unexpected internal error occurred##

3. Command Completion

Synopsis

Context-dependent command completion.

Description

RascalShell provides context-dependent command completion. Typing Tab autocompletes from the current cursor position and will show all possible completions (or will directly add the completion when this is unique).

4. Command History

Synopsis

Use the command history.

Description

RascalShell provides a history of previously entered commands. This can be accessed as follows:

↑

Show previous command in history; Type Return to execute it.

↓

Next command in history; Type Return to execute it.

Ctrl+r

(After search text) Search backward in history.

Ctrl+s

(After search text) Forward search in history

Examples
rascal>a = 1;
[red]##An unexpected internal error occurred##
rascal>b = 2;
[red]##An unexpected internal error occurred##
rascal>c = 3;
[red]##An unexpected internal error occurred##

Typing ↑ will then show the text (not followed by Return!):

rascal>c = 3;

Typing Return will reexecute c = 3.

Typing the letter a (the search text in this example) followed by Ctrl+r will show the text:

(reverse-i-search)`a': a = 3;

And again, typing Return will reexecute a = 3.

5. Keyboard Shortcuts

Synopsis

Keybord shortcuts.

Description

When handling console input, RascalShell supports a subset of the shortcuts provided by GNU Readline

Some convenient shortcuts are:

Ctrl+a

Move cursor to begin of line.

Ctrl+d

EOF marker, closes the current RascalShell (equivalent to the command (quit).

Ctrl+e

Move cursor to end of line.

Ctrl+k

Kill remainder of line after cursor.

Ctrl+l

Clear screen.