Skip to content

ctor

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History
 
 

ctor

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
benchmark
benchmark
 
 
bin
bin
 
 
data
data
 
 
docs
docs
 
 
etc
etc
 
 
examples
examples
 
 
lib
lib
 
 
scripts
scripts
 
 
README.md
README.md
 
 
package.json
package.json
 
 

README.md

REPL

Read-Eval-Print Loop (REPL) environment.

A Read-Eval-Print Loop (REPL) environment is an interactive programming environment which takes individual user inputs (e.g., single expressions), evaluates those inputs, and returns the result. Accordingly, a program written in a REPL environment is executed piecewise and sequentially.

REPL environments find common use in exploratory programming, prototyping, and debugging.

The REPL environment exposed here is available both as a standalone application and as a library which is embeddable in other libraries and applications.

Usage

var REPL = require( '@stdlib/repl/ctor' );

REPL( [options] )

Returns a REPL instance.

// Create a new REPL:
var repl = new REPL();

// ...

// Close the REPL:
repl.close();

The function accepts the following options:

  • input: input (readable) stream. Default: stdin.
  • output: output (writable) stream. Default: stdout.
  • sandbox: boolean indicating whether to run a REPL in a sandboxed context. Default: false.
  • timeout: number of milliseconds to execute a command before terminating execution. Default: 4294967295.
  • isTTY: boolean indicating whether the input and output streams should be treated like a TTY (terminal) and whether the REPL should use ANSI/VT100 escape codes when writing to the output stream.
  • inputPrompt: input prompt. If the input prompt includes the character sequence %d, the input prompt includes line numbers. Default: 'In [%d]: '.
  • outputPrompt: output prompt. If the output prompt includes the character sequence %d, the output prompt includes line numbers. Default: 'Out[%d]: '.
  • welcome: welcome message.
  • padding: number of empty lines between consecutive commands. Default: 1.
  • load: file path specifying a JavaScript file to load and evaluate line-by-line (e.g., a previous REPL history file).
  • save: file path specifying where to save REPL command history.
  • log: file path specifying where to save REPL commands and printed output.
  • quiet: boolean indicating whether log information, confirmation messages, and other possible REPL diagnostics should be silenced. Default: false.

REPL.prototype.createContext()

Returns a REPL context.

// TODO

REPL.prototype.resetContext()

Resets a REPL's execution context.

// TODO

REPL.prototype.clearHistory()

Clears a REPL's history.

// TODO

REPL.prototype.load( fpath, clbk )

Loads and evaluates a JavaScript file line-by-line.

// TODO

REPL.prototype.reset()

Resets a REPL.

// TODO

REPL.prototype.clear()

Clears the entire REPL screen and scrollback history.

// TODO

This method is only applicable for TTY REPLs. In non-TTY REPLs, this method is a non-operation.

REPL.prototype.clearLine()

Clears the current line.

// TODO

This method is only applicable for TTY REPLs. In non-TTY REPLs, this method is a non-operation.

REPL.prototype.clearCommand()

Clears the current REPL command buffer (i.e., clear any command which has been buffered but not yet executed).

// TODO

REPL.prototype.close()

Closes a REPL.

// TODO

Commands

REPL instances support the following commands...

alias2pkg( arg )

Returns the package name associated with a provided alias or class instance.

// TODO

Note: only direct instances of documented built-in constructors are supported.

alias2related( arg )

Returns aliases related to a specified alias or class instance.

// TODO

Note: only direct instances of documented built-in constructors are supported.

ans

Result of the last successfully executed command.

// TODO

assignfrom( workspace, variable )

Reads a value from a specified workspace.

// TODO

assignin( workspace, variable, value )

Assigns a value to a variable in a specified workspace.

// TODO

clear()

Clears the entire REPL screen and scrollback history.

// TODO

Note: this function is only applicable for TTY REPLs. In non-TTY REPLs, this function is a non-operation.

clearHistory()

Clears the REPL history.

// TODO

clearUserDocs( [options] )

Deletes user-defined documentation.

// TODO

The function supports the following options:

  • include: inclusion filter. May be either an array-like object or a regular expression.

  • exclude: exclusion filter. May be either an array-like object or a regular expression.

  • filter: filter type. This option is only applicable for array-like object filters. Must be one of the following values:

    • 'alias': filter based on documentation alias. If a filter matches a documentation alias, the user-defined documentation is removed.
    • 'value': filter based on object reference. If a filter matches an associated object reference, the user-defined documentation is removed.
    • '*': filter based on both documentation alias and object reference. If a filter matches either a documentation alias or an associated object reference, the user-defined documentation is removed.

    Default: '*'.

// TODO

clearvars( [options] )

Deletes user-defined variables in the current workspace.

// TODO

The function supports the following options:

  • include: variable name inclusion filter. May be either an array-like object or a regular expression.
  • exclude: variable name exclusion filter. May be either an array-like object or a regular expression.
// TODO

clearWorkspace( [name, ][options] )

Deletes user-defined variables in a specified workspace.

// TODO

By default, the function clears user-defined variables in the current workspace. To clear user-defined variables in a different workspace, provide a workspace name.

// TODO

The function supports the following options:

  • include: variable name inclusion filter. May be either an array-like object or a regular expression.
  • exclude: variable name exclusion filter. May be either an array-like object or a regular expression.
// TODO

currentWorkspace

Returns the name of the current workspace.

// TODO

deleteWorkspace( [name] )

Deletes a workspace.

// TODO

If not provided an argument, the REPL deletes the current workspace and switches to the 'base' workspace.

// TODO

Note: the 'base' workspace cannot be deleted.

evalin( workspace, expression )

Evaluates an expression in a specified workspace.

// TODO

example( arg )

Runs examples for a specified alias, property, or class instance.

// TODO

Note: only direct instances of documented built-in constructors are supported.

help( [arg] )

Prints help text.

// TODO

To print help text for an alias,

// TODO

To print help text for a property,

// TODO

To print help text for a class instance,

// TODO

Note: only direct instances of documented built-in constructors are supported.

info( arg )

Prints abbreviated help text for a provided alias, property, or class instance.

// TODO

Note: only direct instances of documented built-in constructors are supported.

isKeyword( keyword )

Returns a boolean indicating whether a string is a reserved keyword in the REPL environment.

// TODO

load( fpath )

Loads and evaluates a JavaScript file, such as a REPL history file, line-by-line.

// TODO

loadWorkspace( name[, options] )

Loads variables from a specified workspace into the current workspace.

// TODO

The function supports the following options:

  • **include: variable name inclusion filter. May be either an array-like object or a regular expression.
  • **exclude: variable name exclusion filter. May be either an array-like object or a regular expression.
  • override: boolean indicating whether to override existing workspace variables. Default: true.
// TODO

logStart( fpath )

Starts logging commands and printed output to a specified file path.

// TODO

logStop( id )

Stops logging commands and printed output to a file path associated with a specified record identifier.

// TODO

renameWorkspace( oldName, newName )

Renames a workspace.

// TODO

Note: the new workspace name must not already exist. The only exception is when the old name and the new name are the same; in which case, invoking this command is a non-operation.

Note: as a 'base' workspace must always exist, when renaming the 'base' workspace, variables from the 'base' workspace are simply copied to a new workspace and the 'base' workspace cleared of user-defined variables.

quit()

Exits the REPL.

// TODO

rerun( [arg] )

Reruns previous commands.

// TODO

By default, the command re-executes the previous command. If provided an integer, the previous n commands are re-executed.

// TODO

If provided a regular expression, the most recent command matching the regular expression is rerun.

// TODO

If provided an array of command identifiers, the command corresponding to each identifier is rerun.

// TODO

If provided a subsequence string, the command corresponding to each resolved command identifier is rerun.

// TODO

WARNING: be careful when re-evaluating previously executed rerun commands, as this can lead to infinite execution loops.

reset()

Resets the REPL.

// TODO

save( fpath )

Saves previous commands to a specified file path.

// TODO

saveStart( fpath )

Starts saving commands to a specified file path.

// TODO

saveStop( id )

Stops saving commands to a file path associated with a specified record identifier.

// TODO

userDoc( alias, [ref,] doc )

Adds user-defined documentation.

// TODO

If user-defined documentation already exists for the provided alias, the current documentation is overwritten.

// TODO

vars( [options] )

Returns a list of variable names in the current workspace.

// TODO

The function supports the following options:

  • include: regular expression variable name inclusion filter.
  • exclude: regular expression variable name exclusion filter.
  • types: array-like object containing variable type inclusion filter(s).
  • details: boolean indicating whether to include additional variable details, such as variable type, contents, etc. Default: false.
// TODO

varsWorkspace( [name, ][options] )

Returns a list of variable names in a specified workspace.

// TODO

The function supports the following options:

  • include: regular expression variable name inclusion filter.
  • exclude: regular expression variable name exclusion filter.
  • types: array-like object containing variable type inclusion filter(s).
  • details: boolean indicating whether to include additional variable details, such as variable type, contents, etc. Default: false.
// TODO

workspace( name )

Switch to a specified workspace.

// TODO

If a workspace with the specified name does not exist, the workspace is created.

// TODO

workspaces( [options] )

Returns a list of workspace names.

// TODO

The function supports the following options:

  • include: regular expression workspace name inclusion filter.
  • exclude: regular expression workspace name exclusion filter.
  • details: boolean indicating whether to include additional workspace details, such as variable names, types, contents, etc. Default: false.
// TODO

Examples

var join = require( 'path' ).join;
var REPL = require( '@stdlib/repl/ctor' );

function onExit() {
    console.log( '' );
    console.log( 'REPL closed.' );
}

// Create a new REPL:
var repl = new REPL();
repl.on( 'exit', onExit );

// Load a history file:
repl.load( join( __dirname, 'examples', 'history.txt' ) );

// Close the REPL:
repl.close();

CLI

Usage

Usage: stdlib-repl [options]

Options:

  -h, --help                    Print this message.
  -V, --version                 Print the package version.
      --welcome <message>       Welcome message.
      --input_prompt <prompt>   Input prompt. Default: 'In [%d]: '.
      --output_prompt <prompt>  Output prompt. Default: 'Out[%d]: '.
      --padding <padding>       Empty lines between commands. Default: 1.
      --load <filepath>         JavaScript file to evaluate line-by-line.
      --save <filepath>         File to save REPL command history.
      --logfile <filepath>      File to log REPL commands and printed output.
      --timeout <timeout>       Milliseconds before terminating a command.
      --quiet                   Disable printing of REPL logs and diagnostics.

Examples

$ stdlib-repl