Deploying to gh-pages from @ 6d3237e 🚀

.buildinfo

@@ -1,4 +1,4 @@
 # Sphinx build info version 1
 # This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
-config: 841e0c1b3b70d42001ac0241a0f9608c
+config: 10699483736a4cf99a02715755f594c2
 tags: 645f666f9bcd5a90fca523b33c5a78b7

_sources/library-reference/language-extensions/string-literals.rst.txt

@@ -9,11 +9,15 @@ processing ("raw" strings) and multi-line strings. Briefly,
 #. Multi-line strings begin with three double-quote characters: ``"""``
 
 #. End-of-line sequences in multi-line strings are always parsed as a single
-   Newline (``\\n``) character, regardless of source file line endings or the
+   Newline (``\n``) character, regardless of source file line endings or the
    conventions of the operating system.
 
 #. Any string, whether delimited by ``"`` or ``"""`` may be prefixed with
    ``#r`` or ``#R`` to disable escape sequence processing.
 
+#. Any leading whitespace that *matches the whitespace preceding the end
+   ``"""`` delimiter* is removed, allowing multi-line strings to be formatted
+   nicely in source code.
+
 See `DEP 12 <https://opendylan.org/proposals/dep-0012-string-literals.html>`_
 for details.

_sources/proposals/dep-0012-string-literals.rst.txt

@@ -4,15 +4,15 @@ String Literal Syntax
 
 ===============  =============================================
 DEP #:           12
-Supersedes:      DEP 8
+Supersedes:      DEP 8, multi-line-strings
 Type:            Standards Track
 Affects-DRM:     Yes
 Author:          Carl Gay
 Status:          Draft
 Created:         22-Mar-2023
-Last-Modified:   22-Mar-2023
+Last-Modified:   19-Aug-2023
 Post-History:    `28-Mar-2023 <https://groups.google.com/g/dylan-lang/c/xhofah0KYt8>`_
-Target-Version:  2023.1
+Target-Version:  2023.2
 ===============  =============================================
 
 
@@ -40,8 +40,9 @@ Multi-line String Literals
 
 While it should be noted that encoding long string literals into source code is
 not good practice when internationalization is desired, it is convenient to
-have this ability for quick scripts and especially for encoding test data.
-Most modern programming languages provide this ability.
+have this ability for quick scripts, for encoding test data, and as simple
+format string templates.  Most modern programming languages provide this
+ability.
 
 For very short multi-line strings one can get away with using \\n or
 \\r\\n in a regular string::
@@ -104,7 +105,7 @@ Specification
 Multi-line string literals are delimited by three double quote characters on
 each end: ``"""``. Any string literal, whether one-line or multi-line, may be
 prefixed with ``#r`` or ``#R`` to disable backslash escape processing, i.e., to
-make it a raw string literal.
+make it a "raw" string literal.
 
 Literal end-of-line sequences are always interpreted as a single LF character,
 in both raw and escaped string literals, regardless of operating system
@@ -128,6 +129,86 @@ just `#` followed by any standard string, we also allow ``#"""`` to indicate a
 multi-line quoted symbol, to be consistent. No new syntax is provided to create
 a "raw" quoted symbols, i.e., quoted symbols without escape processing.
 
+The Rectangle Rule
+------------------
+
+`The Rectangle Rule
+<https://github.com/google/google-java-format/wiki/The-Rectangle-Rule>`_ states
+
+  When a source file is formatted, each subtree gets its own bounding
+  rectangle, containing all of that subtree’s text and none of any other
+  subtree’s.
+
+To permit (but not require) Dylan source code to conform to that rule,
+multi-line string literals need special treatment of leading whitespace. In the
+following two examples the programmer wants to ensure that there is no leading
+whitespace on any line in the resulting string literal token:
+
+.. code-block:: dylan
+   :linenos:
+   :caption: Without support for the Rectangle Rule
+   :emphasize-lines: 3,4,5
+
+   define method foo ()
+     let text = """bits on the wire
+   protocols well understood
+   where did my mail go?
+   """;
+     ...
+   end method;
+
+Here, without special handling for leading whitespace, there is no choice but
+to put the first line of text on the same line with ``"""`` and to left-align
+the highlighted lines, harming readability due to violating the Rectangle Rule.
+
+.. code-block:: dylan
+   :linenos:
+   :emphasize-lines: 3,4,5,6
+   :caption: With support for the Rectangle Rule
+
+   define method foo ()
+     let text = """
+                bits on the wire
+                protocols well understood
+                where did my mail go?
+                """;
+     ...
+   end method;
+
+Here, the ``\n`` (and any other whitespace) after the opening delimiter is
+removed and leading whitespace is removed from the highlighted lines in the
+resulting string literal token, so they may be moved (as a unit) left or right
+without affecting the result.
+
+To achieve this we adopt the techniques used for `raw strings in C#
+<https://learn.microsoft.com/en-us/dotnet/csharp/programming-guide/strings/#raw-string-literals>`_.
+
+The following rules apply to both raw and non-raw multi-line string literals:
+
+* Starts and ends with a sequence of at least three double quote characters
+  (``"""``, ``#r"""``, or ``#R"""``). More than three consecutive ``"``
+  characters are allowed to start and end the sequence in order to support
+  string literals that contain three (or more) repeated ``"`` characters.
+
+* Single line string literals that use triple-double-quoting require the
+  opening and closing delimiters to be on the same line.
+
+* In multi-line string literals, any whitespace to the left of the closing
+  delimiter is removed from all lines of the string literal.
+
+* In multi-line string literals, whitespace to the left of the closing
+  delimiter must be identical on each line. For example, it is not valid to use
+  tab characters on one line and space characters on another.
+
+* In multi-line string literals, whitespace following the opening delimiter on
+  the same line is ignored.
+
+* In multi-line string literals, whitespace-only lines following the opening
+  delimiter are included in the string literal.
+
+BNF
+---
+
 In the Dylan Reference Manual, in the section `Tokens
 <https://opendylan.org/books/drm/Lexical_Grammar#HEADING-117-3>`_, ``#r`` is
 added to the ``#-word`` production.
@@ -149,7 +230,7 @@ is shown below.
     STRING:
         " more-string
 
-        " " " multi-line-string
+        " " "... multi-line-string
 
         # r raw-string
 
@@ -159,22 +240,22 @@ is shown below.
         "
 
     multi-line-string:
-        " " " more-multi-line-string
+        multi-line-string-character more-multi-line-string
 
     more-multi-line-string:
         multi-line-string-character more-multi-line-string
 
-        " " "
+        " " "...     (must match the number of " in start delimiter)
 
     multi-line-string-character:
-        any character except for \ or three " in a row
+        any character except for \ or the """... closing delimiter
 
         \ escape-character
 
     raw-string:
         " more-raw-string
 
-        " " " more-raw-string-multi-line
+        " " "... more-raw-string-multi-line
 
     more-raw-string:
         raw-string-character more-raw-string
@@ -184,7 +265,7 @@ is shown below.
     more-raw-string-multi-line:
         raw-string-character-multi-line more-raw-string-multi-line
 
-        " " "
+        " " "...     (must match the number of " in start delimiter)
 
     string-character:
         any printing character (including space) except for " or \
@@ -205,36 +286,63 @@ is shown below.
 Examples
 --------
 
-Equivalent to ``"abc"``::
+Strings equivalent to ``"abc"``::
+
+  """abc"""
+  #r"abc"
+  #r"""abc"""
+
+  """
+  abc
+  """
+
+  #r"""
+  abc
+  """
+
+Multi-line string equivalent to ``"line one\nline two"``::
+
+  let text = """
+             line one
+             line two
+             """;
 
-  """abc""" or #r"abc" or #r"""abc"""
+Same as above because whitespace *to the left of the closing delimiter* is
+removed::
 
-Equivalent to ``"line one\nline two"`` but **never** equivalent to ``"line
-one\r\nline two"``::
+  let text = """
+        line one
+        line two
+        """;
 
-  """line one
-  line two"""
+Multi-line string equivalent to ``"\nline one\nline two\n"``::
+
+  let text = """
+
+             line one
+             line two
+
+             """;
+
+Same as above but using escape sequences::
+
+  let text = """
+             \nline one
+             line two\n
+             """;
 
 Equivalent to ``"let x = \"foo\";"``::
 
   """let x = "foo";"""
 
-Equivalent to ``"\nfoo\nbar\n"``::
+Raw string for ``C:\users\``::
 
-  """
-  foo
-  bar
-  """
+  #R"C:\users\"
 
 Equivalent to ``"^\\s*([0-9A-Fa-f]+)\\s*"``::
 
   #r"^\s*([0-9A-Fa-f]+)\s*"
 
-Equivalent to ``"foo\nbar\\[A-Z]+"``::
-
-  #r"""foo
-  bar\[A-Z]+"""
-
 
 Reference Implementation
 ========================

_static/basic.css

@@ -670,6 +670,16 @@ dd {
     margin-left: 30px;
 }
 
+.sig dd {
+    margin-top: 0px;
+    margin-bottom: 0px;
+}
+
+.sig dl {
+    margin-top: 0px;
+    margin-bottom: 0px;
+}
+
 dl > dd:last-child,
 dl > dd:last-child > :last-child {
     margin-bottom: 0;
@@ -738,6 +748,14 @@ abbr, acronym {
     cursor: help;
 }
 
+.translated {
+    background-color: rgba(207, 255, 207, 0.2)
+}
+
+.untranslated {
+    background-color: rgba(255, 207, 207, 0.2)
+}
+
 /* -- code displays --------------------------------------------------------- */
 
 pre {

_static/pygments.css

@@ -22,6 +22,7 @@
 .highlight .cs { color: #8f5902; font-style: italic } /* Comment.Special */
 .highlight .gd { color: #a40000 } /* Generic.Deleted */
 .highlight .ge { color: #000000; font-style: italic } /* Generic.Emph */
+.highlight .ges { color: #000000; font-weight: bold; font-style: italic } /* Generic.EmphStrong */
 .highlight .gr { color: #ef2929 } /* Generic.Error */
 .highlight .gh { color: #000080; font-weight: bold } /* Generic.Heading */
 .highlight .gi { color: #00A000 } /* Generic.Inserted */
@@ -107,6 +108,7 @@ body[data-theme="dark"] .highlight .c1 { color: #ababab; font-style: italic } /*
 body[data-theme="dark"] .highlight .cs { color: #e50808; font-weight: bold; background-color: #520000 } /* Comment.Special */
 body[data-theme="dark"] .highlight .gd { color: #d22323 } /* Generic.Deleted */
 body[data-theme="dark"] .highlight .ge { color: #d0d0d0; font-style: italic } /* Generic.Emph */
+body[data-theme="dark"] .highlight .ges { color: #d0d0d0; font-weight: bold; font-style: italic } /* Generic.EmphStrong */
 body[data-theme="dark"] .highlight .gr { color: #d22323 } /* Generic.Error */
 body[data-theme="dark"] .highlight .gh { color: #ffffff; font-weight: bold } /* Generic.Heading */
 body[data-theme="dark"] .highlight .gi { color: #589819 } /* Generic.Inserted */
@@ -192,6 +194,7 @@ body:not([data-theme="light"]) .highlight .c1 { color: #ababab; font-style: ital
 body:not([data-theme="light"]) .highlight .cs { color: #e50808; font-weight: bold; background-color: #520000 } /* Comment.Special */
 body:not([data-theme="light"]) .highlight .gd { color: #d22323 } /* Generic.Deleted */
 body:not([data-theme="light"]) .highlight .ge { color: #d0d0d0; font-style: italic } /* Generic.Emph */
+body:not([data-theme="light"]) .highlight .ges { color: #d0d0d0; font-weight: bold; font-style: italic } /* Generic.EmphStrong */
 body:not([data-theme="light"]) .highlight .gr { color: #d22323 } /* Generic.Error */
 body:not([data-theme="light"]) .highlight .gh { color: #ffffff; font-weight: bold } /* Generic.Heading */
 body:not([data-theme="light"]) .highlight .gi { color: #589819 } /* Generic.Inserted */

about/examples/classes.html

@@ -1,16 +1,16 @@
 <!doctype html>
-<html class="no-js" lang="en">
+<html class="no-js" lang="en" data-content_root="">
   <head><meta charset="utf-8"/>
     <meta name="viewport" content="width=device-width,initial-scale=1"/>
     <meta name="color-scheme" content="light dark"><meta name="viewport" content="width=device-width, initial-scale=1" />
 <link rel="index" title="Index" href="../../genindex.html" /><link rel="search" title="Search" href="../../search.html" /><link rel="next" title="Generic Functions" href="generic_functions.html" /><link rel="prev" title="Everything is a value" href="everything_value.html" />
 
-    <link rel="shortcut icon" href="../../_static/favicon.ico"/><!-- Generated with Sphinx 7.0.1 and Furo 2023.05.20 -->
+    <link rel="shortcut icon" href="../../_static/favicon.ico"/><!-- Generated with Sphinx 7.1.2 and Furo 2023.09.10 -->
         <title>Classes &amp; Instantiation - Open Dylan</title>
-      <link rel="stylesheet" type="text/css" href="../../_static/pygments.css" />
-    <link rel="stylesheet" type="text/css" href="../../_static/styles/furo.css?digest=e6660623a769aa55fea372102b9bf3151b292993" />
-    <link rel="stylesheet" type="text/css" href="../../_static/graphviz.css" />
-    <link rel="stylesheet" type="text/css" href="../../_static/styles/furo-extensions.css?digest=30d1aed668e5c3a91c3e3bf6a60b675221979f0e" />
+      <link rel="stylesheet" type="text/css" href="../../_static/pygments.css?v=a746c00c" />
+    <link rel="stylesheet" type="text/css" href="../../_static/styles/furo.css?v=135e06be" />
+    <link rel="stylesheet" type="text/css" href="../../_static/graphviz.css?v=eafc0fe6" />
+    <link rel="stylesheet" type="text/css" href="../../_static/styles/furo-extensions.css?v=36a5483c" />
 
 
 
@@ -543,9 +543,9 @@ <h1>Classes &amp; Instantiation<a class="headerlink" href="#classes-instantiatio
 
     </aside>
   </div>
-</div><script data-url_root="../../" id="documentation_options" src="../../_static/documentation_options.js"></script>
-    <script src="../../_static/doctools.js"></script>
-    <script src="../../_static/sphinx_highlight.js"></script>
-    <script src="../../_static/scripts/furo.js"></script>
+</div><script data-url_root="../../" id="documentation_options" src="../../_static/documentation_options.js?v=2df60dd4"></script>
+    <script src="../../_static/doctools.js?v=888ff710"></script>
+    <script src="../../_static/sphinx_highlight.js?v=4825356b"></script>
+    <script src="../../_static/scripts/furo.js?v=32e29ea5"></script>
     </body>
 </html>