Re: [PATCH olang v1 1/2] docs: spec: rename program to translation-unit

[Johnny Richard <johnny@johnnyrichard.com>]

On Wed, Mar 27, 2024 at 12:21:27AM -0300, Carlos Maniero wrote:
> We started to rename the program node in AST to translation-unit. This

Nitpick:  Perhaps we can highlight the problem and solution better?

    Today, the AST node "program" serves as the main entry point for the
    grammar, potentially leading to confusion as the program ultimately
    becomes the final ELF binary after linking all .o files. Therefore, we
    have collectively decided to replace it with "translation-unit," which
    more accurately conveys the concept of a singular unit being translated
    into a single binary. This adjustment enables us to assert that a
    translation-unit corresponds directly to the .ol source file on a
    one-to-one basis.

> commit also makes a few refactors on spec such as:
> 
> - Makes EOF a end-of-statement

This patch does the opposite.  Make a end-of-statement a EOF as well,
which I not agree.  See following comments...

> - create global-statements section to accommodate upcoming global
>   definitions.
> 
> Signed-off-by: Carlos Maniero <carlos@maniero.me>
> ---
>  docs/pages/language-specification.md | 6 ++++--
>  1 file changed, 4 insertions(+), 2 deletions(-)
> 
> diff --git a/docs/pages/language-specification.md b/docs/pages/language-specification.md
> index 5769d95..4541ba8 100644
> --- a/docs/pages/language-specification.md
> +++ b/docs/pages/language-specification.md
> @@ -22,7 +22,9 @@ language.
>  
>  ```
>  (* Entry Point *)
> -<program>             ::= <ows> <function-definition> <ows> <end-of-file>
> +<translation-unit>    ::= <ows> (<global-statements> <end-of-statement>)*

This change expect that every followed new statement has no optional
white space. According to your change the following expression is invalid:

    |fn add(): u32 {
    |  return 0;
    |}
    |
     ^~~ this is a line-break (syntax error according to your grammar)
    | fn main(): u32 {
     ^~~ this is a linear-space (syntax error according to your grammar)
    |  return 0;
    |}


suggestion: This change fixes the problem.

    <translation-unit>    ::= (<ows> <global-statements> <ows> (<end-of-statement> | <end-of-file>))*

> +
> +<global-statements>   ::= <function-definition>

This doesn't need to be plural if it has a single "statement".

>  
>  (* Functions *)
>  <function-definition> ::= 'fn' <ws> <function-name> <ows>
> @@ -35,7 +37,7 @@ language.
>  (* Statements *)
>  <block>               ::= '{' <ows> <statement> <ows> (<end-of-statement>
>  <ows> <statement> <ows>)* <end-of-statement>? <ows> '}'
> -<end-of-statement>    ::= ';' | <line-break>
> +<end-of-statement>    ::= ';' | <line-break> | <end-of-file>

Hmmm... this is not true, this means the every end-of-statement can be a
end-of-file.