Skip to content

Latest commit

 

History

History
290 lines (203 loc) · 10.9 KB

perli.md

File metadata and controls

290 lines (203 loc) · 10.9 KB
Raw

perli(1) - a simple, convenient Perl REPL

SYNOPSIS

A simple, convenient Perl REPL for interactive experimentation.

perli [<options>]

--norc      skips loading of the initialization file

The following Perl options are also supported:

-M<name>    (repeatable) load a module and import its defaults,  
                         or activate a pragma (-M-<name> deactivates)
-m<module>  (repeatable) load a module without importing
-I<dir>     (repeatable) prepend <dir> to module search path (@INC)

Initialization file is ~/.perli_rc

Standard options: --help, --man, --version, --home

DESCRIPTION

perli is a Perl REPL (read-eval-print loop) for interactive
experimentation with Perl code, convenient documentation lookups,
and quick computations.

On Unix-like platforms, installation of rlwrap is highly recommended; see PLATFORM NOTES below.

Interactive input is executed line by line, and results are automatically
printed.

Once you've entered the REPL (invoked perli), submit ? for an
overview of its features and commands.

An optional initialization file may be maintained at ~/.perli_rc.

INITIALIZATION FILE

To preload modules into the REPL, you may maintain an optional
initialization file with Perl code at ~/.perli_rc, which is loaded
automatically on startup.

Caveat: The scope of use <pragma> statements is limited to the
initialization file itself;
if you want a pragma such as use integer to be in effect for the REPL,
you must specify it on the command line with -M<pragma>.

The file need not be a module, and nothing needs to be exported;
simply load modules / declare subroutines for the REPL in the global
namespace.

The last statement in the file is expected to return a truthy value;
otherwise, a warning is issued.

REPL FUNDAMENTALS AND LIMITATIONS

A concise summary of most of the topics discussed below can be displayed from inside perli by submitting ?.

Perl features in effect by default

The active locale's character encoding is respected (with strings internally represented as Unicode and automatic translation to and from the locale's encoding for streams and files, as if perl -C had been run). Also see LOCALE SUPPORT below.

All optional features of the host Perl version are enabled (as if perl -E had been run). For instance, the say feature is in effect in host Perl versions >= 5.9.5.
To deactivate all features, start perli with perli -M-feature=:all.
To activate a given version's feature bundle, start perli with something like
perli -Mv5.10.

Useful warnings are enabled by default (as if perl -w had been run).
To enable ALL warnings, start perli with perli -W.
To SUPPRESS all warnings, start perli with perli -X.

use English; is in effect to enable the natural-language aliases for Perl's special variables; e.g., $MATCH for $&.

use Math::Trig; is in effect to facilitate calculations involving trigonometry and the constant pi.

Input

Only single-line input is supported, and each line submitted is its own scope; this has the following implications:

  • Pragmas such as use locale; only take effect for the line at hand;
    for pragmas to take effect globally, you must specify them on the
    command line when starting perli; e.g., perli -Mlocale.

  • Variables declared with my only exist on the line they're defined on; omit the my to create global variables, which stay in scope for the
    remainder of the REPL session.

To complement direct input of Perl code, special REPL commands - commmands provided by perli itself - are availabe, all of which start with . and must be the only statement on the line. ? is an alias for .help or .doc

Submit ? from inside perli to see all REPL commands; only a select few are highlighted here.

Documentation lookups

perli supports Perl documentation lookups using either of the following two forms:

  • ? [<perldoc-opt>] <search-term>
  • ... <search-term>?

The first form is the stand-alone form that also allows explicit passing of options to perldoc.

The second form is handy for quick lookup of a term as you're typing a line of Perl code.

In the first form without [<perldoc-opt>], and invariably in the second form, the lookup is "fuzzy" for convenience, i.e., perli tries to guess the type of element being searched for, and automatically passes the appropriate perldoc option (-f for function, ...) behind the scenes. perli may try several options in sequence until a lookup succeeds.

If the lookup ultimately fails, or perli guessed the wrong type, use the first form and pass perldoc options explicitly; e.g.: ? -q while explicitly searches the FAQs for the word while instead of looking up the flow-control keyword.

As with perldoc, topics may be looked up without the perl prefix; e.g., ? run is a shortcut for ? perlrun.

Regex-match inspection

.remi ... =~ ... facilitates inspection of regular-expression matches by automatically printing the automatic variables that Perl defines for the most recent successful match.

Note that only a single expression involving =~ is supported; e.g.:

.remi "a barn." =~ /(?<foo>b(.)(.))n/

Following the expression's own result, the values of the following special variables are printed (use English; aliases in parentheses):

$` ($PREMATCH), $& ($MATCH), $' ($POSTMATCH),
%- (%LAST_MATCH_START), @- (@LAST_MATCH_START), @+ (@LAST_MATCH_END)

To reduce noise, only non-empty values are printed.

Note that %- is only printed if named capture groups are present, and that the related %+ (%LAST_PAREN_MATCH) is never printed, because its information is effectively contained in the value of %-.

As a reminder, a regex operation's result is a Boolean, if the regex contains no capture groups at all, and the list of capture group values otherwise - whether from named or unnamed groups.

Output printing and formatting

Evaluation results are automatically printed, using the core Data::Dumper module, which presents results in a way that allows its reuse as input and shows the structure of the result.

To best represent arrays and hashes, store them in a variable first and prefix the variabe with \ (so as to hand a reference to Data::Dumper); try \%ENV, for instance.

To print a result as-is instead, use an explicit output command, such as print, printf or say, but note that the automatic result-printing mechanism still applies and then appends 1, which is the return value from these output statements. Explicit output commands are also needed if locale support is activated and numbers should be formatted accordingly - see LOCALE SUPPORT below.

Warnings and error messages are printed in different colors so as to stand out. However, you can disable coloring altogether with the PERLI_NOCOLOR enviroment variable - see ENVIRONMENT VARIABLES below.

Tab completion

If rlwrap is available (see PLATFORM NOTES below), tab-completion is available, but it lacks context-awareness so that ALL tokens are offered in any context, which can be confusing.
For instance, typing $<tab> does NOT limit the completion candidates to just variable names, unfortunately. (Conceivably, this could be remedied in a future perli release, using rlwrap's custom tab-completion feature.)

The following elements are added to the pool of tab-completion tokens:

  • Perl functions, operators, compound statements
  • Perl's special variables
  • perli's own REPL commands
  • any token typed or output during a REPL session

Note: The latter facilitates reusing previously typed tokens such as custom variables, but, due to indiscriminately adding tokens both from the input and output of commands, can also introduce noise.

Generally, typing at least a few characters reduces the set of candidates, and repeatedly pressing the Tab key cycles through them.

Command history

If rlwrap is available (see PLATFORM NOTES below), a persistent command history is maintained in file ~/.perli_history

LOCALE SUPPORT

Your system's active locale is only respected in terms of character encoding; NO other aspects of the locale, notably number formatting, are explicitly activated, deferring to the host Perl's default behavior.

Perl's default behavior is NOT to support the active locale so as to maintain backward compatibility. Locale support - once activated with use locale; - is patchy in older Perl versions and the behavior changed over time; UTF-8-based locales further complicate things - see perldoc perllocale or visit
http://perldoc.perl.org/perllocale.html

To activate locale support in perli, start with perli -Mlocale.

Note, however, that the automatically printed numeric results do NOT reflect Perl's effective LC_NUMERIC locale category; use explicit print, printf, or say statements instead, but note that the automatic result-printing mechanism still applies and then appends 1, which is the return value from these output statements.

Note that, as of this writing, the MSYS Unix-emulation enviroment for Windows and products based on it (such as Git Bash) do not support locales at all (the 'C' locale is invariably in effect).

ENVIRONMENT VARIABLES

  • PERLI_PERLBIN
    Allows overriding the perl executable that is used to run the REPL.
    By default, the (first) perl executable in the system's path is used.

  • PERLI_PS1
    If specified, overrides the default prompt. Specify the string
    including a space to put between the prompt proper and the start
    of the user input, if desired.
    Note that if you want the prompt to be colored, the value has to
    include the relevant ANSI color escape sequences.

  • PERLI_NOCOLOR
    If set to 1, turns off all colored output.

PLATFORM NOTES

perli requires Perl version v5.6.2 or higher.

On Unix platforms, perli makes use of the rlwrap utility, if present,
to provide command-line editing support, persistent command history,
and simple tab completion.

Installing rlwrap is highly recommended, and in its absence a warning
with download instructions is given.

On Windows, rlwrap is not available, unfortunately, but you do get
in-session history and basic command-line editing out of the box.

LICENSE

For license information and more, visit the home page by running
perli --home, or, from within the REPL, .home.

STANDARD OPTIONS

All standard options provide information only.

  • -h, --help
    Prints the contents of the synopsis chapter to stdout for quick
    reference.

  • --man
    Displays this manual page, which is a helpful alternative to using
    man, if the manual page isn't installed, such as on Windows.

  • --version
    Prints version information.

  • --home
    Opens this utility's home page in the system's default web browser.