EEP-XXX: Triple-Quoted Binary-Strings

eeps/eep-0064.md

@@ -0,0 +1,187 @@
+    Author: Kiko Fernandez-Reyes <kiko(at)erlang(dot)org>
+    Status: Draft
+    Type: Standards Track
+    Created: 07-Jun-2023
+    Erlang-Version: OTP-27
+    Post-History:
+****
+EEP XXX: Triple-quoted binary strings
+----
+
+Abstract
+========
+
+This EEP proposes the introduction of triple-quoted binary-strings syntax and
+runtime semantics. The main benefit is to allow multi-line binary strings in an
+easy way, similar to other languages, e.g., Elixir.
+
+Rationale
+=========
+
+One limitation of Erlang today (June 2023) is the ability to write multi-line
+string binaries. That said, the main reason to consider this EEP is
+[EEP-59][] where documentation attributes can
+benefit from multi-line string binaries: the documentation generates Docs chunks
+format -- documentation in its binary format-- which saves space and makes the
+documentation available to the shell.
+
+Triple-Quoted Binary-String Design Decisions
+---------------------------------------------
+
+### Runtime semantics
+
+Triple-quoted strings should only produce binary-strings. This makes easy to
+avoid typing issues with union types, and makes clear that a triple-quoted string
+does not need function with guards to test if the produce result is a list or a
+binary (this can happen if Erlang adds string interpolation,
+[EEP-62][],
+[PR-7343][]).
+
+Triple-quoted binary-strings do not allow string interpolation and, if we were
+to accept them, only calls to statically known values should be allowed, e.g.,
+macros. This design decision forbids the creation of dynamic documentation that
+generates code at runtime, e.g., doing an IO call to get a value not known
+statically and based on it perform an action (notice that this is allowed when
+using string interpolation).
+
+### Binary-String Design
+
+To make the usage of binary-string similar to other languages, this EEP proposal
+makes the binary-string design decisions similar to the ones for the Elixir language.
+
+#### Binary-String Start and End
+
+Binary-strings must start and end with triple-quotes in their own lines:
+
+*Code Example*
+
+    X = """
+        This is the beginning of the triple-quote text
+        """
+
+*Documentation Example*
+
+    -doc """
+         Removes double-quotes (") from a given string
+         """
+    remove_double_quotes(X) -> 
+
+#### Binary-Strings Closing of Triple-Quotes
+
+The closing of the triple-quotes denotes the space (indentation):
+
+*1. Code Example*
+
+    >> X = """
+           This text
+           has no indentation
+           """
+
+    Equivalent to: <<"This text\nhas no indentation\n">>
+
+*2. Code Example*
+
+    >> Y = """
+           This text
+           has indentation
+    """
+
+    Equivalent to: <<"       This text\n       has indentation\n">>
+
+*3. Code Example*
+
+    >> Z = """
+      This text has
+      two space indentation
+    """
+
+    Equivalent to: <<"  This text has\n  two space indentation\n">>
+
+*1. Documentation Example - No indentation*
+
+    -doc """
+         Removes double-quotes (") from a given string
+         """
+    remove_double_quotes(X) -> 
+
+*2. Documentation Example - No indentation*
+
+    -doc """
+    Removes double-quotes (") from a given string
+    """
+    remove_double_quotes(X) -> 
+
+*3. Documentation Example - Indentation*
+
+    -doc """
+         Removes double-quotes (") from a given string
+    """
+    remove_double_quotes(X) -> 
+
+#### Binary-Strings Errors
+
+An error should be raised when there is text that starts before the closing of triple-quotes, where
+the error makes the code written using triple-quotes to have a uniform style:
+
+*Code Example*
+
+    >> Err = """
+    This shall be an error
+             """
+
+    error             
+
+*Documentation Example*
+
+    -doc """
+    Removes double-quotes (") from a given string
+         """
+    remove_double_quotes(X) -> 
+
+#### Escaping Newlines in Triple-Quotes
+
+Escaping new lines using `\`:
+
+To write `\` inside triple quotes, one needs to use `\\`. [EEP-59][] should
+ignore the meaning of `\` if inside a code block.
+
+*Code Example*
+
+    >> X = """
+           This text \
+           has no indentation
+           """
+
+    Equivalent to: <<"This text has no indentation\n">>
+
+*Documentation Example*
+
+    -doc """
+    Removes double-quotes (") \
+    from a given string
+    """
+    remove_double_quotes(X) -> 
+
+[EEP 59]: https://www.erlang.org/eeps/eep-0059
+    "EEP 59: Module attributes for documentation"
+
+[EEP-62]: https://www.erlang.org/eeps/eep-0062
+    "String Interpolation Syntax"
+
+[PR-7343]: https://github.com/erlang/otp/pull/7343
+    "Feature: String Interpolation"
+
+Copyright
+=========
+
+This document is placed in the public domain or under the CC0-1.0-Universal
+license, whichever is more permissive.
+
+[EmacsVar]: <> "Local Variables:"
+[EmacsVar]: <> "mode: indented-text"
+[EmacsVar]: <> "indent-tabs-mode: nil"
+[EmacsVar]: <> "sentence-end-double-space: t"
+[EmacsVar]: <> "fill-column: 70"
+[EmacsVar]: <> "coding: utf-8"
+[EmacsVar]: <> "End:"
+[VimVar]: <> " vim: set fileencoding=utf-8 expandtab shiftwidth=4 softtabstop=4: "