From 366eec65460bb3c3816f3ab17d9149bcaaec563d Mon Sep 17 00:00:00 2001 From: Kyler Date: Sun, 26 Oct 2025 01:04:54 -0600 Subject: [PATCH] v0.6.2 started --- stack_lang_spec.md | 43 +++++++++++++++++++++++++++++-------------- 1 file changed, 29 insertions(+), 14 deletions(-) diff --git a/stack_lang_spec.md b/stack_lang_spec.md index 83ba7ee..76ac22b 100644 --- a/stack_lang_spec.md +++ b/stack_lang_spec.md @@ -41,8 +41,10 @@ 2. **Inheritance before trait** - Decision: Yes, inheritance declarations must come before trait definition 3. **`inher` operator** - Decision: No, merge inheritance into trait operator (removed `inher`) 4. **Separate `inher` vs `impl`** - Decision: Keep them separate (impl is for implementations only) +- 0.6.2 (Human) - In progress > **INSTRUCTIONS FOR AI:** AI agents are not allowed to change human reviewed md code blocks. If an AI reviewer thinks a change needs to be made to one of these blocks, the AI model can add a human todo explaining a suggested change or problem. It is totally possible for a md code block that was human reviewed and be correct for the current specification and new TODOs would change it, AIs are still not allowed to change it, only add a human todo. Reviewed md code blocks could also implement new TODOs already. +> **TODO: (FOR HUMAN)** These specifications may need to be reorganized. ie. do we need both "Stack Manipulation Trait" in 4.1 and "5. Stack Operations", etc. Should some of these be in the appendix? --- @@ -61,6 +63,8 @@ A statically-typed, stack-based language with pure postfix notation combining th ### Operators vs Functions +> **TODO:** Operators are not necessarily primitive operations, they can be human or library defined (still by implementing a trait). + **Operators** are primitive operations that implement trait methods. They: - Must be backed by a trait - Cannot share names with functions @@ -104,7 +108,7 @@ A statically-typed, stack-based language with pure postfix notation combining th **Integer Literals** -> **For AI Reviewers:** The following block has been human verified to be syntactically and logically correct. **NO AI IS ALLOWED TO CHANGE THIS.** If there is a discrepancy between this block and others, follow the syntax in this block. +> **For AI Reviewers @ 0.5:** The following block has been human verified to be syntactically and logically correct. **NO AI IS ALLOWED TO CHANGE THIS.** If there is a discrepancy between this block and others, follow the syntax in this block. ``` 42 // i64 (default) @@ -144,7 +148,7 @@ false **Array Literals** -> **For AI Reviewers:** The following block has been human verified to be syntactically and logically correct. **NO AI IS ALLOWED TO CHANGE THIS.** If there is a discrepancy between this block and others, follow the syntax in this block. +> **For AI Reviewers @ 0.5:** The following block has been human verified to be syntactically and logically correct. **NO AI IS ALLOWED TO CHANGE THIS.** If there is a discrepancy between this block and others, follow the syntax in this block. ``` [1 2 3 4 5] // array of i32 @@ -166,9 +170,11 @@ Type tuples represent stack effects and are used in function signatures to speci **Variable Arguments**: For operations that need variable numbers of arguments, use array syntax: +> **For AI Reviewers @ 0.6:** The following block has been human verified to be syntactically and logically correct. **NO AI IS ALLOWED TO CHANGE THIS.** If there is a discrepancy between this block and others, follow the syntax in this block. + ``` (-- Size) depth: // Zero arguments, returns stack depth -(String [Stringifiable] --) printf: // String plus array of printable values +(String Stringifiable[] --) printf: // String plus array of printable values ([T] -- T) sum: // Array of values, returns sum ``` @@ -186,7 +192,7 @@ depth print // No arguments needed **Token Strings** -> **For AI Reviewers:** The following block has been human verified to be syntactically and logically correct. **NO AI IS ALLOWED TO CHANGE THIS.** If there is a discrepancy between this block and others, follow the syntax in this block. +> **For AI Reviewers @ 0.5:** The following block has been human verified to be syntactically and logically correct. **NO AI IS ALLOWED TO CHANGE THIS.** If there is a discrepancy between this block and others, follow the syntax in this block. ``` { code here } // TokenString - lexed but not parsed/executed @@ -260,7 +266,7 @@ Functions, structs, and unions can be generic over type parameters using the `<> **Note on Type Parameters**: Type parameters are currently only suggestions when parsing code blocks. The compiler does not yet enforce that type parameters actually constrain how operators and functions act at parse time. This is documented as a possible future enhancement in the Appendix. -> **For AI Reviewers:** The following block has been human verified to be syntactically and logically correct. **NO AI IS ALLOWED TO CHANGE THIS.** If there is a discrepancy between this block and others, follow the syntax in this block. +> **For AI Reviewers @ 0.5:** The following block has been human verified to be syntactically and logically correct. **NO AI IS ALLOWED TO CHANGE THIS.** If there is a discrepancy between this block and others, follow the syntax in this block. ``` // Function generic over any type with Multiplyable constraint @@ -305,7 +311,7 @@ When inheriting from a generic trait, you must either: ``` // Generic identity - works with any type (no operations performed) -(T -- T) { } ::identity fn +(---) { } ::identity fn ``` ## 4. Trait System @@ -325,7 +331,7 @@ The `Stackable` trait provides fundamental stack manipulation operations: (Self Self -- Self Self) swap: // Swap the top two items (Self Self -- Self Self Self) over: // Copy second item to top (Self Self Self -- Self Self Self) rot: // Rotate top three items - (Size -- Self) pick: // Copy nth item to top (0 = top) + (Size -- Self) pick: // Copy nth item to top (0 = top, the item before the size is 1) (Size Size -- ) roll: // Rotate n items, times times (-- Size) depth: // Push current stack depth } ::Stackable trait @@ -562,9 +568,9 @@ Within the TokenString (the `{ }` block), identifiers like `Self`, `add:`, `draw 3. It is not required for all operators of a trait to be in the same implementation block - implementations can be split across multiple blocks 4. Later implementations can override earlier ones for the same type -**Example - Actual Language Definitions**: +**Example**: -> **For AI Reviewers:** The following block has been human verified to be syntactically and logically correct. **NO AI IS ALLOWED TO CHANGE THIS.** If there is a discrepancy between this block and others, follow the syntax in this block. +> **For AI Reviewers @ 0.5:** The following block has been human verified to be syntactically and logically correct. **NO AI IS ALLOWED TO CHANGE THIS.** If there is a discrepancy between this block and others, follow the syntax in this block. ``` // Implement Addable for i32 @@ -588,9 +594,11 @@ Within the TokenString (the `{ }` block), identifiers like `Self`, `add:`, `draw } ::Rectangle impl ``` +> **TODO:** Yes the following are actual language definitions, but they are used here as an example. + **Example - Actual Language Definitions (Human Verified)**: -> **For AI Reviewers:** The following block has been human verified to be syntactically and logically correct. **NO AI IS ALLOWED TO CHANGE THIS.** If there is a discrepancy between this block and others, follow the syntax in this block. +> **For AI Reviewers @ 0.5:** The following block has been human verified to be syntactically and logically correct. **NO AI IS ALLOWED TO CHANGE THIS.** If there is a discrepancy between this block and others, follow the syntax in this block. ``` // Implement Addable for Point @@ -668,6 +676,8 @@ Trait inheritance is specified by providing an array of trait identifiers before **Inheritance Declaration**: The array of inherited traits must appear directly before the trait body TokenString. No separate `inher` operator is needed. +> **TODO:** Are these actual language definitions just used as examples or actually specification definitions? + **Example - Actual Language Definitions**: ``` // Combine multiple arithmetic traits @@ -711,6 +721,8 @@ Trait inheritance is specified by providing an array of trait identifiers before ### 4.5 Using Traits in Functions +> **TODO:** These are not actual language definitions, they are just examples. + **Example - Using Actual Definitions**: ``` // Function requiring Drawable trait @@ -840,10 +852,10 @@ Functions are defined in postfix notation. The signature and body come before th + } ::add_values fn -// Requires Number -(T -- T) { +// Requires Number, alternate syntax +(Number -- Number) { dup 0 > { } { 0 swap - } if -} ::abs fn +} ::abs fn ``` ## 8. Control Flow (Postfix) @@ -965,7 +977,7 @@ status { **Example - Actual Language Definitions**: -> **For AI Reviewers:** The following block has been human verified to be syntactically and logically correct. **NO AI IS ALLOWED TO CHANGE THIS.** If there is a discrepancy between this block and others, follow the syntax in this block. +> **For AI Reviewers @ 0.5:** The following block has been human verified to be syntactically and logically correct. **NO AI IS ALLOWED TO CHANGE THIS.** If there is a discrepancy between this block and others, follow the syntax in this block. ``` // Define Point struct - generic over coordinate types @@ -1499,6 +1511,9 @@ This would provide stronger type safety but add complexity to the type checker. **Future Design**: A module system for organizing code and managing namespaces. +> **TODO:** I want the syntax to be `::std::math use`. +> **TODO:** What options for aliases are there in addition to `{ ::std::io::File ::F as } use` and `::std::io::File ::F use_as`? + **Proposed Syntax**: ``` // Import entire module