Fin Text Format

• This specification is currently unstable, expect changes.
  • Once stable, there will be no updates (no versions).
• File extension is .fin.
• MIME type is application/fin.
• The fin format is defined in terms of Unicode text (code points).
• Each code point is distinct (e.g. case-sensitive).
• All fin payloads must be valid Unicode text encoded as UTF-8.
• Decoders will ignore a UTF-8 encoded byte order mark U+FEFF at the start of input.
• Encoders must not emit a byte order mark at the start of output.
• Some terminology used in this spec.
  • Inline means notation that is free of line feeds. Specifically the U+000A code point.
    • It does not mean the notation is guaranteed to be displayed to a human on the same line that's something different.
  • Expanded is the opposite. Expanded elements contain at least one line feed.
  • Container elements can include (nest) other elements (children).
  • Block elements are expanded, non-container elements that are rendered (and indented) as a block.
  • Non-value means an element is not treated like a value when interpreting the notation. Instead, non-values act like comments (documentation only).

Gaps

• The following codepoints are accepted between other notation elements.
  • space U+0020
  • \t tab U+0009
  • \n line feed U+000A
  • \r carriage return U+000D

Symbols

examples = [
  # symbols
  foo, foo_bar, _98, foo_, _98_, _ 
  :key, crypto:sha256, :a:b:c:_:_98_
]

• Symbols can contain the following code points
  • : colon U+003A
  • _ underscore U+005F
  • a-z lowercase letters U+0061 - U+007A
  • 0-9 decimal digits U+0030 - U+0039
• Must not start with a digit.
• Must not end with a colon.
• A digit must not follow a colon.
• Consecutive underscores are not allowed.
• Consecutive colons are not allowed.
• Symbols are inline values.

Numbers

examples = [
  # numbers
  98, 1.23e4, -42, 0, 84e0
  0.55, -0.123e-4, -0.00
]

• Numbers can contain the following code points
  • 0-9 decimal digits U+0030 - U+0039
  • - hyphen U+002D
  • A single . full stop U+002E
  • A single e lowercase letter e U+0065.
• Syntax notation

  dig  = "0" ... "9" .
  dig1 = "1" ... "9" .
  int  = "0" | dig1 {dig} .
  frac = "." dig {dig} .
  exp  = "e" [ "-" ] int .
  number = [ "-" ] int [ frac ] [ exp ] .
  

• Does not represent NaN or +/- infinity. Use extensions.
• Numbers are inline values.

Strings

Escaped Strings

• A sequence of Unicode code points within double quotes U+0022 that represents valid Unicode text.
• Zero length sequences (empty strings) are allowed.
• Supports escape sequence interpretation.
  • \ backslash U+005C initiates an escape sequence.
  • An error occurs if the next code point results in an unknown escape sequence.
  • The supported escape sequences are
    • \\ backslash U+005C.
    • \" double quotation U+0022. Prevents early termination of the string.
    • \n line feed U+000A.
    • \r carriage return U+OOOD.
    • \t horizontal tab U+0009.
    • \u{hex} Unicode escape. Where hex is the hexadecimal number for a Unicode code point.
• All code points values less than 32 (C0 controls) must be escaped.
• Escaped strings are inline values.

examples = [
  ""
  "fin 🐬"
  "escape sequences \\ \" \t \n \r \u{7f}"
]

Raw Strings

• A sequence of Unicode code points collected by alternating between the following states
  • accept
    • Initiated by a vertical bar | U+007C.
    • Accept all code points up to and including the next line feed U+000A which transitions the state to ignore.
  • ignore
    • Ignore all space U+0020 and horizontal tabs U+0009.
    • | transitions the state back to accept.
    • Any other code point terminates the string.
    • The final line feed is not included in the string.
• Raw strings are expanded block values.

examples = [
  |a raw string
 
  |raw strings are not interpreted.
  |  - unescaped \n, #not a comment, 
  |  - this bar | is part of the string.
  |can span multiple lines.

  |another raw string 🐬
  |this one ends with a line feed
  |

  # below is an empty raw string
  |
]

Comments

• Follow the exact same rules as raw strings except they are initiated with # U+0023 and are not treated as values.
• Comments are expanded block non-values.

# comments can span multiple 
# lines just like raw strings

# unlike raw strings they're not values. 🐬

Arrays

• A sequence of children elements surrounded by square brackets [ U+005B and ] U+005D
• Can be empty (zero length)
• Element order is significant.
• Elements can be almost any type of notation
  • All values including other collections (nesting).
  • All non-values (e.g. comments or discarded extensions).
  • Map entries are not allowed.
• Can be tagged with an optional symbol that immediately precedes the opening bracket
• Arrays are values and can be rendered in two forms
  • inline if all elements are inline
  • expanded if any element has expanded

expanded_array = [

  # expanded array elements are indented with tabs.
  # consecutive empty lines are removed.

  # comma is used to separate values on the same line.
  a, 98, [
    # commas can be used pre/post expanded notation.
    | comments and raw strings trigger expansion.
  ], "foo"

  # for inline arrays - elements are comma separated
  # on the same line as the surrounding brackets
  [], tagged["array"], [98, goal, []]

]

Maps

• A sequence of children elements surrounded by parenthesis ( U+0028 and ) U+0029
• Unlike arrays child elements are restricted to
  • non-values (e.g. comments or discarded extensions)
  • map entries
• Other than that they have the same rules as arrays
  • Can be empty (zero length)
  • Can be tagged with an optional symbol that immediately precedes the opening parenthesis
  • Are values and can be rendered in two forms
    • inline if all elements are inline
    • expanded if any element has expanded
• TODO order semantics and handling of duplicate keys.
  • The raw notation conveys order and says nothing of uniqueness.

expanded_map = (

  # like arrays expanded map elements are indented with tabs.
  # consecutive empty lines are removed.

  # comma is used to separate entries on the same line.
  a = b, 1 = "two"

  # keys and vals can also be other collections
  # inline maps have entries on the same line comma separated
  () = tag(cb = 98, kk = 55)
)

Map Entries

• A map entry represents an association of two values
• Separated by = U+003D
• The first value is the key.
• The second value is confusingly called the value or val.
• A map entry is a key/val pair.

# example map entries
# most keys in the wild are symbols, strings or numbers
# however, fin supports all value types as keys

# inline-inline
a = 98, nested = (a = 98) 

# inline-block
b =
|raw

# block-inline
|c
= 98

# block-block
|d
= 
|e

(
  # key is an expanded map
  a = 98
) = [ 
  # val is an expanded array
], f =
| line continuation (comma) works
| after expanded vals & before expanded keys

Top Level Value

• The top level value is an implicit map. Implicit means
  • the surrounding parenthesis are not rendered
  • map elements are not indented
• All code examples in this specification are valid fin payloads (top level maps)

Extensions

• Includes all symbols and tagged collections where the symbol
  • starts with fin: (builtin extensions)
  • is true or false (considered builtin)
  • starts with ext: (custom extension)
• Extensions are values unless they are discarded.
• Discarded extensions are those with symbols ending in _ they are non-values.
• Extensions are expanded if the tagged collection is also expanded
• Otherwise extensions are inline

extensions = [

  # builtin extensions (start with fin:)
  fin:timestamp["2024-02-26T03:01:13.644Z"]
  fin:bytes[
    |f6 69 6e 20 54 d6 78 74
    |2a 46 6f 72 6d 61 74 0a
  ]
  fin:uuid["c83ccbb6-44d0-4d62-8263-b8afec01f3a2"]

  # booleans are builtins
  true, false

  # extensions ending with _ are discarded
  fin:_(is_value = false, treated_as = "comment")

  # custom extensions (start with ext:)
  ext:null, ext:nan, ext:int:hex_10fe
  ext:loc(x = 1, y = 2) 
  ext:markdown[
    |# title 
    |
    |a **markdown** extension!
  ]
]