[PATCH olang v3] docs: create o programming language spec

[PATCH olang v3] docs: create o programming language spec

[Johnny Richard]

This document specifies the semantics and behavior of the O Programming
Language for compiler designers be informed on how the language is designed.

This document will help newcomers to understand how the language looks
like and also as a DRAFT guide to drive design discussions.

The grammar was made by using a EBNF evaluator tool[1].

[1]: The live example https://mdkrajnak.github.io/ebnftest/ and a locked
     version https://github.com/Engelberg/instaparse/tree/v1.4.12 as
     reference.

Signed-off-by: Johnny Richard <johnny@johnnyrichard.com>
Co-authored-by: Ricardo Kagawa <ricardo.kagawa@gmail.com>
---
V3: 
  - fix markdown reference link
  - add Pandoc metadata to fix page header
  - add spec link to layout header
  - fix page max-width to avoid EBNF of wrapping lines on big screens

 docs/pages/language-specification.md | 64 ++++++++++++++++++++++++++++
 docs/template.html                   |  3 +-
 2 files changed, 66 insertions(+), 1 deletion(-)
 create mode 100644 docs/pages/language-specification.md

diff --git a/docs/pages/language-specification.md b/docs/pages/language-specification.md
new file mode 100644
index 0000000..5769d95
--- /dev/null
+++ b/docs/pages/language-specification.md
@@ -0,0 +1,64 @@
+% O programming language specification
+
+Abstract
+--------
+
+This document specifies the semantics and behavior of the O Programming
+Language for compiler designers be informed how the language is designed.
+
+This specification is a DRAFT and will be the discussions drive over olang-dev
+mailing list.
+
+Language Syntax
+---------------
+
+This is the O Programming Language EBNF grammar specification[^1]
+
+[^1]: EBNF variant https://github.com/Engelberg/instaparse/tree/v1.4.12 and live
+      test can be accessed here https://mdkrajnak.github.io/ebnftest/
+
+NOTE: This grammar spec is a DRAFT and it covers only a small portion of the
+language.
+
+```
+(* Entry Point *)
+<program>             ::= <ows> <function-definition> <ows> <end-of-file>
+
+(* Functions *)
+<function-definition> ::= 'fn' <ws> <function-name> <ows>
+<function-parameters> <ows> ':' <ows> <return-type> <ows> <function-body>
+<function-name>       ::= <identifier>
+<function-parameters> ::= '(' <ows> ')'
+<return-type>         ::= <type>
+<function-body>       ::= <block>
+
+(* Statements *)
+<block>               ::= '{' <ows> <statement> <ows> (<end-of-statement>
+<ows> <statement> <ows>)* <end-of-statement>? <ows> '}'
+<end-of-statement>    ::= ';' | <line-break>
+<statement>           ::= <return-statement>
+<return-statement>    ::= 'return' <ws> <expression>
+
+(* Expressions *)
+<expression>          ::= <integer>
+
+(* Identifiers *)
+<type>                ::= 'u32'
+<identifier>          ::= (<alpha> | '_') (<alpha> | <digit> | '_')*
+
+(* Literals *)
+<integer>             ::= <integer-base10> | <integer-base16>
+<integer-base10>      ::= #'[1-9]' (<digit> | '_')* | '0'
+<integer-base16>      ::= #'0[Xx]' <hex-digit> (<hex-digit> | '_')*
+
+(* Utilities *)
+<ws>                  ::= <white-space>+
+<ows>                 ::= <white-space>*
+<white-space>         ::= <linear-space> | <line-break>
+<line-break>          ::= #'[\n\v\f\r]' | '\r\n'
+<linear-space>        ::= #'[ \t]'
+<alpha>               ::= #'[a-zA-Z]'
+<digit>               ::= #'[0-9]'
+<hex-digit>           ::= <digit> | #'[a-fA-F]'
+<end-of-file>         ::= #'$'
+```
diff --git a/docs/template.html b/docs/template.html
index 4e066d1..52a22d1 100644
--- a/docs/template.html
+++ b/docs/template.html
@@ -30,7 +30,7 @@
       color: var(--link-color);
     }
     article, nav, header, footer {
-      max-width: 820px;
+      max-width: 1024px;
       margin: 10px auto;
     }
     header, footer {
@@ -56,6 +56,7 @@
     <nav>
       <a href="/">Index</a> |
       <a href="/pages/getting-started.html">Getting started (WIP)</a> |
+      <a href="/pages/language-specification.html">Specification</a> |
       <a href="/pages/hacking.html">Hacking</a> |
       <a href="https://sr.ht/~johnnyrichard/olang/sources" target="_blank">Sources ↗</a> |
       <a href="https://sr.ht/~johnnyrichard/olang/lists" target="_blank">Mailing list ↗</a>
-- 
2.44.0

[olang/patches/.build.yml] build success

[builds.sr.ht]

olang/patches/.build.yml: SUCCESS in 40s

[docs: create o programming language spec][0] v3 from [Johnny Richard][1]

[0]: https://lists.sr.ht/~johnnyrichard/olang-devel/patches/50408
[1]: mailto:johnny@johnnyrichard.com

✓ #1177304 SUCCESS olang/patches/.build.yml https://builds.sr.ht/~johnnyrichard/job/1177304

Re: [PATCH olang v3] docs: create o programming language spec

[Carlos Maniero]

Nice work! I tested and everything seems to be good.

Except a weird spacing in the code that is coming from nowhere when
the HTML is generated, but since it is unrelated with your change we are
good to go.

I'm changing the patch status to approved since I can't trigger
pipelines during the git pushes.

Re: [PATCH olang v3] docs: create o programming language spec

[Johnny Richard]

Patch applied! Thanks for reviewing it.

https://builds.sr.ht/~johnnyrichard/job/1177348

To git.sr.ht:~johnnyrichard/olang
   64e2289..ce5389c  main -> main