First pass at Languages/REPL

Author: coke

doc/Language/REPL.rakudoc

@@ -0,0 +1,71 @@
+=begin pod :kind("Language") :subkind("Language") :category("tutorial")
+
+=TITLE REPL
+
+=SUBTITLE Read-eval-print loop
+
+=head1 Overview
+
+The C<REPL> is an interactive Raku prompt. Each line of code you enter in the C<REPL>
+is executed, and if no output was generated, the value returned
+by the expression is output.
+
+=head1 Trap
+
+B<Note>: Running code in the C<REPL> is not equivalent to saving the code in a file and
+running that. Each line introduces a new scope which can confuse code that has multiple
+lines. See C<sub repl()> below for a way to target a REPL inside a larger script.
+
+=head1 non-interactive mode
+
+If invoked from the command line with  C<raku --repl-mode=non-interactive>, no history or prompts
+are printed, and the code is not executed until you close input (on Linux, for example, you can pipe
+the code to it or press C<Control-d>.
+
+=for code :lang<shell>
+    $ echo "say 3" | raku --repl-mode=non-interactive
+    3
+
+=head1 sub repl()
+
+This routine allows you to embed a REPL inside a larger script and have access to all
+the variables in context.
+
+See L<sub repl()|/type/independent-routines#sub_repl> in Independent Routines for more
+information.
+
+=head1 ENVIRONMENT Variables
+
+See L<ENVIRONMENT Variables|/programs/03-environment-variables#Environment_variables_used_by_the_raku_command_line>.
+
+=head2 Get command line history
+
+In a fresh install, there is no command history. Running the C<REPL> in this mode will
+prompt you to install one of the various modules that provide this support. If enabled,
+you can use the arrow keys to scroll through previous commands and use standard terminal
+shortcuts for editing. There are currently four options:
+
+=item 1
+
+=for code :lang<shell>
+    zef install Terminal::LineEditor
+
+=item 2
+
+=for code :lang<shell>
+    zef install Linenoise
+
+=item 3
+
+=for code :lang<shell>
+    zef install Readline # requires a readline install
+
+=item 4
+
+An alternative for UNIX-like systems is to install C<rlwrap>. This can
+be done on Debian-ish systems by running:
+
+=for code :lang<shell>
+sudo apt-get install rlwrap
+
+=end pod

doc/Language/faq.rakudoc

@@ -414,17 +414,6 @@ There are also L<several ecosystem modules|https://raku.land/?q=dump>
 that provide more control over how data structures are dumped, including
 support for colored output.
 
-=head2 How can I get command line history in the Raku prompt (REPL)?
-
-Install L<Linenoise|https://github.com/hoelzro/p6-linenoise/> from the
-ecosystem.
-
-An alternative for UNIX-like systems is to install C<rlwrap>. This can
-be done on Debian-ish systems by running:
-
-=for code :lang<shell>
-sudo apt-get install rlwrap
-
 =head2 Why is the Rakudo compiler so apologetic?
 
 If SORRY! is present in the output, the error is a compile time error.

doc/Language/unicode_entry.rakudoc

@@ -415,7 +415,7 @@ following key combination (whitespace has been added for clarity):
     =end code
 
 This also the method one would use to enter unicode characters into the
-C<raku> REPL, if one has started the REPL inside a Unix shell.
+C<raku> L<REPL|/language/REPL>, if one has started the REPL inside a Unix shell.
 
 =head2 Screen
 

doc/Language/variables.rakudoc

@@ -247,7 +247,7 @@ X<|Syntax,*>X<|Syntax,$*>X<|Syntax,@*>X<|Syntax,%*>X<|Syntax,&*>
 
 This twigil is used for dynamic variables which are looked up through the
 caller's, not through the outer, scope. Look at the example below.N<The example
-below cannot run correctly in the REPL, yielding an error about not finding the
+below cannot run correctly in the L<REPL|/language/REPL>, yielding an error about not finding the
 dynamic variables. Please test it by copy-pasting it into a file, then run the
 file.>
 

doc/Programs/03-environment-variables.rakudoc

@@ -135,13 +135,13 @@ X<|Programs,RAKUDO_NO_PRECOMPILATION>
 If set to 1, precompilation will be disabled. Available as of the 2023.08
 release of the Rakudo compiler.
 
-=head2 REPL (Read Eval Print Loop)
+=head2 REPL (Read-eval-print loop)
 
 X<|Programs,RAKU_REPL_OUTPUT_METHOD>
 =item C<RAKU_REPL_OUTPUT_METHOD>
 
 This specifies the name of the method that should be called on the result
-value of a statement in the REPL if the statement did B<not> cause any
+value of a statement in the L<REPL|/language/REPL> if the statement did B<not> cause any
 output of its own.  If absent, C<gist> will be assumed.  One can use
 C<raku> to force a more literal, parsable representation.  Or C<Str> to force a
 complete string representation.  Available as of the 2020.06 release of
@@ -150,8 +150,8 @@ the Rakudo compiler.
 X<|Programs,RAKUDO_LINE_EDITOR>
 =item C<RAKUDO_LINE_EDITOR>
 
-This specifies the preferred line editor to use; valid values are C<Readline>,
-C<Linenoise>, and none. A value of none is useful if you want to avoid the
+This specifies the preferred line editor to use; valid values are C<LineEditor>,
+C<Readline>, C<Linenoise>, and none. A value of none is useful if you want to avoid the
 recommendation message upon REPL startup.
 
 X<|Programs,RAKUDO_DISABLE_MULTILINE>

doc/Programs/04-running-raku.rakudoc

@@ -16,7 +16,7 @@ raku [switches] [--] [programfile] [arguments]
 
 =head1 DESCRIPTION
 
-With no arguments, it enters a REPL. With a C<[programfile]> or the C<-e>
+With no arguments, it enters a L<REPL|/language.REPL>. With a C<[programfile]> or the C<-e>
 option, compiles the given program and by default also executes the
 compiled code.
 

doc/Type/independent-routines.rakudoc

@@ -137,7 +137,7 @@ I<Note>: C<repl> was introduced in release 2021.06 of the Rakudo compiler.
 
     sub repl()
 
-Pauses execution and enters a REPL (read-eval-print loop) in the current
+Pauses execution and enters a L<REPL|/language/REPL> (read-eval-print loop) in the current
 context.  This REPL is exactly like the one created when you run C<raku>
 L<without any arguments|/programs/04-running-raku#DESCRIPTION> except that
 you can access/modify the program's current context (such as lexical