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
int: 3

Or a more complex list comprehension:

rascal>[ n * n | int n <- [0..10] ]
list[int]: [0,1,4,9,16,25,36,49,64,81]

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

rascal>import List;
ok
rascal>size([ n * n | int n <- [0..10] ])
int: 10

Another use is to declare variables

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

and use them later on:

rascal>x * y
int: 6
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;
real: 3.14
rascal>data D = d1(int n) | d2(str s);
ok
rascal>declarations
data D = d1(int n) | d2(str s);

real pi;

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;
ok
rascal>import Set;
ok
rascal>modules
[error]#Error: Name modules is not in scope#

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;
ok
rascal>set trace true
trace set to true
rascal>fac(5)
main([])
  fac(5, {})
		at |file:///export/scratch1/jenkins/home/workspace/usethesource_rascal_master-S5ZKBVP7G6AAXOCX5AHV2IJ2QL35PDF5FJHTCPD6ZB5NPZDM4Q3Q/src/org/rascalmpl/library/demo/basic/Factorial.rsc|(483,10,<14,34>,<14,44>)
    fac(4, {})
		at |file:///export/scratch1/jenkins/home/workspace/usethesource_rascal_master-S5ZKBVP7G6AAXOCX5AHV2IJ2QL35PDF5FJHTCPD6ZB5NPZDM4Q3Q/src/org/rascalmpl/library/demo/basic/Factorial.rsc|(483,10,<14,34>,<14,44>)
      fac(3, {})
		at |file:///export/scratch1/jenkins/home/workspace/usethesource_rascal_master-S5ZKBVP7G6AAXOCX5AHV2IJ2QL35PDF5FJHTCPD6ZB5NPZDM4Q3Q/src/org/rascalmpl/library/demo/basic/Factorial.rsc|(483,10,<14,34>,<14,44>)
        fac(2, {})
		at |file:///export/scratch1/jenkins/home/workspace/usethesource_rascal_master-S5ZKBVP7G6AAXOCX5AHV2IJ2QL35PDF5FJHTCPD6ZB5NPZDM4Q3Q/src/org/rascalmpl/library/demo/basic/Factorial.rsc|(483,10,<14,34>,<14,44>)
          fac(1, {})
		at |file:///export/scratch1/jenkins/home/workspace/usethesource_rascal_master-S5ZKBVP7G6AAXOCX5AHV2IJ2QL35PDF5FJHTCPD6ZB5NPZDM4Q3Q/src/org/rascalmpl/library/demo/basic/Factorial.rsc|(483,10,<14,34>,<14,44>)
          fac returns 1
        fac returns 1
      fac returns 2
    fac returns 6
  fac returns 24
main returns 120

Turn trace off and execute the same function:

rascal>set trace false
trace set to false
rascal>fac(5)
int: 120
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;
ok
rascal>test

TEST SUMMARY: 4 tests executed; 0 failed; 0 ignored

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

rascal>test lang::rascal::tests::basic::Integers

TEST SUMMARY: 20 tests executed; 0 failed; 0 ignored

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;
real: 3.14
rascal>data D = d1(int n) | d2(str s);
ok
rascal>declarations
data D = d1(int n) | d2(str s);

real pi;

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

rascal>undeclare D
No declaration for  D found
rascal>declarations
data D = d1(int n) | d2(str s);

real pi;

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;
ok
rascal>import Set;
ok
rascal>modules
[error]#Error: Name modules is not in scope#

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

rascal>unimport List
Import List removed
rascal>modules
[error]#Error: Name modules is not in scope#

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;
int: 1
rascal>b = 2;
int: 2
rascal>c = 3;
int: 3

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.