Document all language REPLs and ANSI support

doc/docs/terminal-sessions.rst

@@ -1,46 +1,54 @@
-Interactive terminal/shell sessions
------------------------------------
+=================
+Terminal sessions
+=================
 
-To highlight an interactive terminal or shell session, prefix your code snippet
-with a specially formatted prompt.
+Pygments support the parsing and highlighting of terminal sessions, like
+command-line shells, interactive consoles and language `REPL
+<https://en.wikipedia.org/wiki/Read–eval–print_loop>`_.
 
-Supported shells with examples are shown below. In each example, prompt parts in
-brackets ``[any]`` represent optional parts of the prompt, and prompt parts
-without brackets or in parenthesis ``(any)`` represent required parts of the
-prompt.
+They are typically command lines or code, mixed with generic output.
 
-* **Bash Session** (console, shell-session):
+Examples for each can be found in the :doc:`lexer <lexers>` documentation.
 
-  .. code-block:: console
 
-     [any@any]$ ls -lh
-     [any@any]# ls -lh
-     [any@any]% ls -lh
-     $ ls -lh
-     # ls -lh
-     % ls -lh
-     > ls -lh
+Operating system shells
+-----------------------
 
-* **MSDOS Session** (doscon):
+These lexers are expecting a prompt to identify user input. So to highlight a
+shell session, prefix your code snippet with a specially formatted prompt.
 
-  .. code-block:: doscon
+They are typically named ``<shell> Session``.
 
-     [any]> dir
-     > dir
-     More? dir
 
-* **Tcsh Session** (tcshcon):
+Interactive consoles
+--------------------
 
-  .. code-block:: tcshcon
+Similarly to systems shells, Pygments recognize a variety of interactive
+language sessions.
 
-     (any)> ls -lh
-     ? ls -lh
+Their IDs typically follow the ``<language>-console`` or
+``<language>-repl`` pattern.
 
-* **PowerShell Session** (ps1con):
 
-  .. code-block:: ps1con
+Generic output
+--------------
 
-     PS[any]> Get-ChildItem
-     PS> Get-ChildItem
-     >> Get-ChildItem
+To display standalone terminal output and keep styling consistent, you can use
+the generic ``output`` lexer.
 
+
+ANSI rendering
+--------------
+
+In all the lexers above, the command results are parsed as generic output.
+Which means they are rendered as-is, without any styling applied, for example by ANSI codes.
+
+Here is a couple of third-party projects covering this use-case:
+
+- `pygments-ansi-color
+  <https://github.com/chriskuehl/pygments-ansi-color>`_: implements
+  a new lexer and formatter to parse and render pure ANSI content.
+- `Click Extra <https://github.com/kdeldycke/click-extra>`_: adds
+  `ANSI-capable lexers
+  <https://kdeldycke.github.io/click-extra/pygments.html#ansi-language-lexers>`_
+  for each language listed above.

pygments/lexers/algebra.py

@@ -97,6 +97,7 @@ class GAPConsoleLexer(Lexer):
     filenames = ['*.tst']
     url = 'https://www.gap-system.org'
     version_added = '2.14'
+    _example = "gap-repl/euclidean.tst"
 
     def get_tokens_unprocessed(self, text):
         gaplexer = GAPLexer(**self.options)

pygments/lexers/dylan.py

@@ -242,7 +242,7 @@ class DylanConsoleLexer(Lexer):
     """
     For Dylan interactive console output.
 
-    This is based on a copy of the RubyConsoleLexer.
+    This is based on a copy of the ``RubyConsoleLexer``.
     """
     name = 'Dylan session'
     aliases = ['dylan-console', 'dylan-repl']

pygments/lexers/julia.py

@@ -251,6 +251,7 @@ class JuliaConsoleLexer(Lexer):
     aliases = ['jlcon', 'julia-repl']
     url = 'https://julialang.org/'
     version_added = '1.6'
+    _example = "julia/console"
 
     def get_tokens_unprocessed(self, text):
         jllexer = JuliaLexer(**self.options)

pygments/lexers/matlab.py

@@ -2747,6 +2747,7 @@ class MatlabSessionLexer(Lexer):
     aliases = ['matlabsession']
     url = 'https://www.mathworks.com/products/matlab.html'
     version_added = '0.10'
+    _example = "matlabsession/matlabsession_sample.txt"
 
     def get_tokens_unprocessed(self, text):
         mlexer = MatlabLexer(**self.options)

pygments/lexers/r.py

@@ -30,6 +30,7 @@ class RConsoleLexer(Lexer):
     filenames = ['*.Rout']
     url = 'https://www.r-project.org'
     version_added = ''
+    _example = "rconsole/r-console-transcript.Rout"
 
     def get_tokens_unprocessed(self, text):
         slexer = SLexer(**self.options)

pygments/lexers/shell.py

@@ -232,6 +232,7 @@ class BashSessionLexer(ShellSessionBaseLexer):
     mimetypes = ['application/x-shell-session', 'application/x-sh-session']
     url = 'https://en.wikipedia.org/wiki/Unix_shell'
     version_added = '1.1'
+    _example = "console/example.sh-session"
 
     _innerLexerCls = BashLexer
     _ps1rgx = re.compile(
@@ -542,6 +543,7 @@ class MSDOSSessionLexer(ShellSessionBaseLexer):
     mimetypes = []
     url = 'https://en.wikipedia.org/wiki/MS-DOS'
     version_added = '2.1'
+    _example = "doscon/session"
 
     _innerLexerCls = BatchLexer
     _ps1rgx = re.compile(r'^([^>]*>)(.*\n?)')
@@ -628,6 +630,7 @@ class TcshSessionLexer(ShellSessionBaseLexer):
     mimetypes = []
     url = 'https://www.tcsh.org'
     version_added = '2.1'
+    _example = "tcsh/session"
 
     _innerLexerCls = TcshLexer
     _ps1rgx = re.compile(r'^([^>]+>)(.*\n?)')
@@ -760,6 +763,7 @@ class PowerShellSessionLexer(ShellSessionBaseLexer):
     mimetypes = []
     url = 'https://learn.microsoft.com/en-us/powershell'
     version_added = '2.1'
+    _example = "powershell/session"
 
     _innerLexerCls = PowerShellLexer
     _bare_continuation = True

pygments/lexers/special.py

@@ -46,6 +46,7 @@ class OutputLexer(Lexer):
     aliases = ['output']
     url = ""
     version_added = '2.10'
+    _example = "special/output"
 
     def get_tokens_unprocessed(self, text):
         yield 0, Generic.Output, text

pygments/lexers/sql.py

@@ -310,6 +310,7 @@ class PostgresConsoleLexer(Lexer):
     mimetypes = ['text/x-postgresql-psql']
     url = 'https://www.postgresql.org'
     version_added = '1.5'
+    _example = "psql/psql_session.txt"
 
     def get_tokens_unprocessed(self, data):
         sql = PsqlRegexLexer(**self.options)
@@ -974,6 +975,7 @@ class SqliteConsoleLexer(Lexer):
     mimetypes = ['text/x-sqlite3-console']
     url = 'https://www.sqlite.org'
     version_added = '0.11'
+    _example = "sqlite3/sqlite3.sqlite3-console"
 
     def get_tokens_unprocessed(self, data):
         sql = SqlLexer(**self.options)

tests/examplefiles/doscon/session

@@ -0,0 +1,3 @@
+[any]> dir
+> dir
+More? dir

tests/examplefiles/julia/console

@@ -0,0 +1,22 @@
+julia> x = 2
+2
+
+julia> \"\"\"
+        The factorial function.
+
+        ```julia
+        @assert fac(3) == 1 * 2 * 3
+        ```
+        \"\"\"
+        function fac(n)
+            if n < 2
+                return 1
+            else
+                return n * fac(n - 1) # <-- recursive call
+            end
+        end
+
+
+        # Lets try the function out...
+        f(x + 1)
+6

tests/examplefiles/output/output

@@ -0,0 +1,28 @@
+                ,
+                \\`-._           __
+                \\\\  `-..____,.'  `.
+                :`.         /    \\`.
+                :  )       :      : \\
+                ;'        '   ;  |  :
+                )..      .. .:.`.;  :
+                /::...  .:::...   ` ;
+                ; _ '    __        /:\\
+                `:o>   /\\o_>      ;:. `.
+                `-`.__ ;   __..--- /:.   \\
+                === \\_/   ;=====_.':.     ;
+                ,/'`--'...`--....        ;
+                    ;                    ;
+                    .'                      ;
+                .'                        ;
+                .'     ..     ,      .       ;
+                :       ::..  /      ;::.     |
+            /      `.;::.  |       ;:..    ;
+            :         |:.   :       ;:.    ;
+            :         ::     ;:..   |.    ;
+            :       :;      :::....|     |
+            /\\     ,/ \\      ;:::::;     ;
+            .:. \\:..|    :     ; '.--|     ;
+            ::.  :''  `-.,,;     ;'   ;     ;
+        .-'. _.'\\      / `;      \\,__:      \\
+        `---'    `----'   ;      /    \\,.,,,/
+                            `----`              fsc

tests/examplefiles/powershell/session

@@ -0,0 +1,3 @@
+PS[any]> Get-ChildItem
+PS> Get-ChildItem
+>> Get-ChildItem

tests/examplefiles/tcsh/session

@@ -0,0 +1,2 @@
+(any)> ls -lh
+? ls -lh