From 62edd2bb781ef459175f2ecc571f2da5f0223e2f Mon Sep 17 00:00:00 2001 From: Piotr Polesiuk Date: Fri, 13 Dec 2024 23:05:48 +0100 Subject: [PATCH 1/3] Specification of comments --- src/ref/lexer.md | 85 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 85 insertions(+) diff --git a/src/ref/lexer.md b/src/ref/lexer.md index 4e84738..5b3731b 100644 --- a/src/ref/lexer.md +++ b/src/ref/lexer.md @@ -9,10 +9,95 @@ by the lexer, but they separate tokens, e.g., identifiers or literals. ## Comments +Fram supports two kinds of comments: single-line, and block comments. Comments +are treated similarly to whitespace: they are ignored by the lexer, but they +always separate tokens. + +Single-line comments start with the `#` character and end with the new line or +the end of file. + +Block comments are introduced by the sequence `{#` followed by any, possibly +empty sequence *name* of valid identifier characters, operators, and +`#` characters. Such a block comment is terminated by the first occurrence of +*name* that is immediately followed by `#}`. More precisely, it can be +described by the following grammar. +```bnf +block-comment-name ::= { ident-char | op-char | "#" } +block-comment-start ::= "{#" block-comment-name +block-comment-end ::= block-comment-name "#}" +``` +Non-terminal symbols `ident-char` and `op-char` are defined later in this +chapter. At the comment opening, the longest consecutive sequence described by +`block-comment-name` is taken as a comment name. This name should be a suffix +of the name provided at comment closing. Fram doesn't support nested comments, +but the programmer may always choose the name that doesn't occur in the +comment. + +By convention, single-line comments starting with `##`, and block comments +with a name starting with `#` are used as documentation comments, and can be +recognized by some external tools. + +### Examples + +The following code contains some valid comments. +```fram +# This is a single-line comment. +{# This is a block comment. #} +{# Block comments + may span multiple lines. +#} +let id x = x # single-line comment may appear at the end of line of code. + +let n {# block comment may span a part of single line #} = 42 +{#aaa +Comments cannot be nested, +{# but a programmer may choose the comment delimiters. #} +aaa#} + +{#!a! Comment names may contain operators. !a!#} + +{#abc +This comment is ended by `abc` immediately followed by `#}`, +even if it is preceded by other characters. +zzabc#} + +let {# +# This is not a single-line comment, +# because comments are not nested. +# This comment can be ended #} here = 13 + +## This is a documentation comment. +let foo x = x + +{## This is an another documentation comment. ##} +let bar = foo + +{### +Documentation comments can contain a code +``` +{## with an another documentation comment (with a different name). #}} +let some_code = 42 +``` +###} +let baz = bar +``` + ## Literals +```bnf +digit ::= "0"..."9" +lower-char ::= "a"..."z" | "_" +upper-char ::= "A"..."Z" +ident-char ::= lower-char | upper-char | digit | "'" +``` + ## Keywords ## Identifiers ## Operators + +```bnf +op-char ::= "<" | ">" | "&" | "$" | "?" | "!" | "@" | "^" | "+" | "-" + | "~" | "*" | "%" | ";" | "," | "=" | "|" | ":" | "." | "/" +``` From 09d00f377f78f6a462adc9b60b9460b4c7d1f9c7 Mon Sep 17 00:00:00 2001 From: Piotr Polesiuk Date: Sat, 14 Dec 2024 09:36:51 +0100 Subject: [PATCH 2/3] Fixed nested code in Markdown --- src/ref/lexer.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/ref/lexer.md b/src/ref/lexer.md index 5b3731b..ae541cb 100644 --- a/src/ref/lexer.md +++ b/src/ref/lexer.md @@ -40,7 +40,7 @@ recognized by some external tools. ### Examples The following code contains some valid comments. -```fram +````fram # This is a single-line comment. {# This is a block comment. #} {# Block comments @@ -80,7 +80,7 @@ let some_code = 42 ``` ###} let baz = bar -``` +```` ## Literals From 91518419cbfc7e0748bedb6702ca55c74808295f Mon Sep 17 00:00:00 2001 From: Patrycja Balik Date: Sat, 14 Dec 2024 21:27:17 +0100 Subject: [PATCH 3/3] Some language tweaks --- src/ref/lexer.md | 30 +++++++++++++++--------------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/src/ref/lexer.md b/src/ref/lexer.md index ae541cb..ac10d0a 100644 --- a/src/ref/lexer.md +++ b/src/ref/lexer.md @@ -9,15 +9,15 @@ by the lexer, but they separate tokens, e.g., identifiers or literals. ## Comments -Fram supports two kinds of comments: single-line, and block comments. Comments +Fram supports two kinds of comments: single-line and block comments. Comments are treated similarly to whitespace: they are ignored by the lexer, but they always separate tokens. -Single-line comments start with the `#` character and end with the new line or +Single-line comments start with the `#` character and end with a new line or the end of file. Block comments are introduced by the sequence `{#` followed by any, possibly -empty sequence *name* of valid identifier characters, operators, and +empty, sequence *name* of valid identifier characters, operators, and `#` characters. Such a block comment is terminated by the first occurrence of *name* that is immediately followed by `#}`. More precisely, it can be described by the following grammar. @@ -28,12 +28,12 @@ block-comment-end ::= block-comment-name "#}" ``` Non-terminal symbols `ident-char` and `op-char` are defined later in this chapter. At the comment opening, the longest consecutive sequence described by -`block-comment-name` is taken as a comment name. This name should be a suffix -of the name provided at comment closing. Fram doesn't support nested comments, -but the programmer may always choose the name that doesn't occur in the -comment. +`block-comment-name` is taken as the comment name. This name should be a suffix +of the name provided at comment closing. Comments using the same name cannot +be nested. This is not an issue in practice, since the programmer can always +choose a unique name to accomplish nesting. -By convention, single-line comments starting with `##`, and block comments +By convention, single-line comments starting with `##` and block comments with a name starting with `#` are used as documentation comments, and can be recognized by some external tools. @@ -46,19 +46,19 @@ The following code contains some valid comments. {# Block comments may span multiple lines. #} -let id x = x # single-line comment may appear at the end of line of code. +let id x = x # A single-line comment may appear at the end of a line. -let n {# block comment may span a part of single line #} = 42 +let n {# A block comment may span a part of a single line. #} = 42 {#aaa Comments cannot be nested, -{# but a programmer may choose the comment delimiters. #} +{# but the programmer may choose the comment delimiters. #} aaa#} {#!a! Comment names may contain operators. !a!#} {#abc This comment is ended by `abc` immediately followed by `#}`, -even if it is preceded by other characters. +even if the closing sequence is preceded by other characters. zzabc#} let {# @@ -69,13 +69,13 @@ let {# ## This is a documentation comment. let foo x = x -{## This is an another documentation comment. ##} +{## This is another documentation comment. ##} let bar = foo {### -Documentation comments can contain a code +Documentation comments can contain some code ``` -{## with an another documentation comment (with a different name). #}} +{## with another documentation comment (with a different name). #}} let some_code = 42 ``` ###}