From fce780473c10bc06422f00c4a2b41c516f494a02 Mon Sep 17 00:00:00 2001
From: Burdette Lamar <BurdetteLamar@Yahoo.com>
Date: Wed, 21 Feb 2024 14:42:23 -0600
Subject: [PATCH] [DOC] Doc for field processing (#10008)

---
 doc/.document                        |   1 +
 doc/command_line/field_processing.md | 132 +++++++++++++++++++++++++++
 2 files changed, 133 insertions(+)
 create mode 100644 doc/command_line/field_processing.md

diff --git a/doc/.document b/doc/.document
index 5a58e6e3ad..3a790727d7 100644
--- a/doc/.document
+++ b/doc/.document
@@ -9,3 +9,4 @@ rdoc
 regexp
 rjit
 yjit
+command_line
diff --git a/doc/command_line/field_processing.md b/doc/command_line/field_processing.md
new file mode 100644
index 0000000000..4b5a460778
--- /dev/null
+++ b/doc/command_line/field_processing.md
@@ -0,0 +1,132 @@
+## Field Processing
+
+Ruby supports <i>field processing</i>.
+
+This means that when certain command-line options are given,
+the invoked Ruby program can process input line-by-line.
+
+### About the Examples
+
+Examples here assume that file `desiderata.txt` exists:
+
+```
+$ cat desiderata.txt
+Go placidly amid the noise and the haste,
+and remember what peace there may be in silence.
+As far as possible, without surrender,
+be on good terms with all persons.
+```
+
+The examples also use command-line option `-e`,
+which passes the Ruby code to be executed on the command line itself:
+
+```sh
+$ ruby -e 'puts "Hello, World."'
+```
+
+### Option `-n`
+
+Option `-n` runs your program in a Kernel#gets loop:
+
+```
+while gets
+  # Your Ruby code.
+end
+```
+
+Note that `gets` reads the next line and sets global variable `$_`
+to the last read line:
+
+```sh
+$ ruby -n -e 'puts $_' desiderata.txt
+Go placidly amid the noise and the haste,
+and remember what peace there may be in silence.
+As far as possible, without surrender,
+be on good terms with all persons.
+```
+
+### Option `-p`
+
+Option `-p` is like option `-n`, but also prints each line:
+
+```sh
+$ ruby -p -e 'puts $_.size' desiderata.txt
+42
+Go placidly amid the noise and the haste,
+49
+and remember what peace there may be in silence.
+39
+As far as possible, without surrender,
+35
+be on good terms with all persons.
+```
+
+### Option `-a`
+
+Option `-a`, when given with either of options `-n` or `-p`,
+splits the string at `$_` into an array of strings at `$F`:
+
+```sh
+$ ruby -an -e 'p $F' desiderata.txt
+["Go", "placidly", "amid", "the", "noise", "and", "the", "haste,"]
+["and", "remember", "what", "peace", "there", "may", "be", "in", "silence."]
+["As", "far", "as", "possible,", "without", "surrender,"]
+["be", "on", "good", "terms", "with", "all", "persons."]
+```
+
+For the splitting,
+the default record separator is `$/`,
+and the default field separator  is `$;`.
+
+### Option `-F`
+
+Option `-F`, when given with option `-a`,
+specifies that its argument is to be the input field separator to be used for splitting:
+
+```sh
+$ ruby -an -Fs -e 'p $F' desiderata.txt
+["Go placidly amid the noi", "e and the ha", "te,\n"]
+["and remember what peace there may be in ", "ilence.\n"]
+["A", " far a", " po", "", "ible, without ", "urrender,\n"]
+["be on good term", " with all per", "on", ".\n"]
+```
+
+The argument may be a regular expression:
+
+```
+$ ruby -an -F'[.,]\s*' -e 'p $F' desiderata.txt
+["Go placidly amid the noise and the haste"]
+["and remember what peace there may be in silence"]
+["As far as possible", "without surrender"]
+["be on good terms with all persons"]
+```
+
+### Option `-l`
+
+Option `-l`, when given with option `-n` or `-p`,
+modifies line-ending processing by:
+
+- Setting global variable output record separator `$\`
+  input record separator `$/`;
+  this affects line-oriented output (such a that from Kernel#puts).
+- Calling String#chop! on each line read.
+
+Without option `-l` (unchopped):
+
+```sh
+$ ruby -n -e 'p $_' desiderata.txt
+"Go placidly amid the noise and the haste,\n"
+"and remember what peace there may be in silence.\n"
+"As far as possible, without surrender,\n"
+"be on good terms with all persons.\n"
+```
+
+With option `-l' (chopped):
+
+```sh
+$ ruby -ln -e 'p $_' desiderata.txt
+"Go placidly amid the noise and the haste,"
+"and remember what peace there may be in silence."
+"As far as possible, without surrender,"
+"be on good terms with all persons."
+```