mighty

commit 2a6dc32ce6885e37e811b8f4032acd773483bfde
parent c89518dc5e05b4a38ac040883acc5ddf5d9177fc
Author: citbl <citbl@citbl.org>
Date:   Mon, 25 May 2026 21:32:43 +1000

doco

Diffstat:
M
mtcl/doco.md
 | 
65
+++++++++++++++++++++++++++++++++++++++++++++--------------------

1 file changed, 45 insertions(+), 20 deletions(-)
diff --git a/mtcl/doco.md b/mtcl/doco.md
@@ -3,52 +3,77 @@
 ```mty
 use std
 
-fx main(int a, int b) int {
+fx main(int a, int b) int ::
     print("hello")
-    ret 0
-}
+    return 0
+end
+
+fx main :: print("hello world") end
+
+fx main ::
+    print("hello, world")
+    while true do
+    end
+end
+
+pub struct Person ::
+    float age
+    int height
+    str name
+end
+
+enum Type ::
+    FLOAT
+    INT
+    JACK
+end
 ```
 
 ## Current Shape
 
-- `use` imports a library/module name.
+- `use` imports a single module/library identifier and ends at newline or `;`.
+    - `use <exported symbol [, ]> from <module>` will be used to scope narrower imports.
 - `fx` and `fn` introduce a function. `fx` is exported, `fn` is internal.
-- Functions take a name, a parameter list, an optional return type, and a block.
-- `ret` is a reserved keyword for returning a value.
-- Identifiers are plain alphabetic names with digits allowed after the first character.
+- Functions take a name, comma-separated typed parameters like `int a`, an optional return type, and a `:: ... end` block. `::` stands for declaration and is used as a visual marker throughout the file.
+- `pub` is the exported modifier used in the draft for top-level type declarations.
+- Identifiers are letters followed by letters or digits.
+- `EOS` is a token representing end of statement, which can be `;` or `<carriage return>`.
+    - identations have no semantic meaning, statements are one-per-line or `;` separated.
 
 ## Draft EBNF
 
 ```ebnf
-program        = { declaration } ;
-declaration    = use_decl | function_decl ;
-use_decl       = "use" ident ;
-function_decl  = ("fx" | "fn") ident "(" [ param_list ] ")" [ return_type ] block ;
+program        = { declaration | eos } ;
+declaration    = use_decl | function_decl | struct_decl | enum_decl ;
+use_decl       = "use" ident eos ;
+function_decl  = ("fx" | "fn") ident "(" [ param_list ] ")" [ type ] "::" { statement eos } "end" ;
 param_list     = param { "," param } ;
 param          = type ident ;
-return_type    = type ;
-block          = "{" { statement } "}" ;
+struct_decl    = [ "pub" ] "struct" ident "::" { field_decl eos } "end" ;
+field_decl     = type ident ;
+enum_decl      = [ "pub" ] "enum" ident "::" { enum_item eos } "end" ;
+enum_item      = ident ;
 statement      = return_stmt | expr_stmt ;
-return_stmt    = "ret" expression ;
+return_stmt    = "return" expression ;
 expr_stmt      = expression ;
 expression     = ident | literal | call ;
 call           = ident "(" [ arg_list ] ")" ;
 arg_list       = expression { "," expression } ;
 type           = ident ;
 literal        = int_lit | float_lit | string_lit ;
+eos            = "\n" | ";" ;
 ident          = letter { letter | digit } ;
 ```
 
 ## Reserved Keywords
 
-
-`ns`, `in`, `from`, `use`, `ffi`, `drop`, `as`, `of`, `and`, `or`, `ref`, `struct`, `enum`, `pre`, `post`, `inv`, `if`, `else`, `pub`, `fx`, `fn`, `ret`
+`ns`, `use`, `from`, `ffi`, `as`, `and`, `or`, `struct`, `enum`, `if`, `else`, `end`, `pub`, `fx`, `fn`, `return`
 
 ## Notes
 
 - This is a draft, not a frozen spec.
-- The parser is still incomplete
-- String handling, expression parsing, and statement parsing WIP
-- The sample uses a string literal, but string tokenization WIP
-
+- The parser currently handles `use`, `fx`, and `fn`; `struct`, `enum`, and statement parsing are still WIP.
+- `return` is now the reserved return keyword; `ret` is obsolete in the draft.
+- String literals are tokenized now, but escaping and multiline strings are still TODO.
+- The `while true do ... end` example in `idea.mty` is still exploratory and not tokenized by the lexer yet.