From b0c7e26e639754fa4c8e9a7527e5025c12710c17 Mon Sep 17 00:00:00 2001 From: Kyler Date: Sun, 26 Oct 2025 17:22:01 -0600 Subject: [PATCH] Updated ideas --- human_todos_ideas.md | 289 ---------------------------------------- ideas.md | 310 +++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 310 insertions(+), 289 deletions(-) delete mode 100644 human_todos_ideas.md create mode 100644 ideas.md diff --git a/human_todos_ideas.md b/human_todos_ideas.md deleted file mode 100644 index 2db4764..0000000 --- a/human_todos_ideas.md +++ /dev/null @@ -1,289 +0,0 @@ -Perfect! I've completed all the non-human TODOs. Now let me discuss the human TODOs with detailed suggestions: - ---- - -## Human TODOs - Discussion & Recommendations - -### 1. **How to identify an unspecified number of arguments?** - -**The Problem**: Some operations need variable numbers of arguments: -- `depth` consumes the entire stack to count it -- `printf` might take a format string + arbitrary values - -**Options:** - -**A) Ellipsis notation: `...`** -``` -(... -- Size) depth: // Entire stack -(String ... --) printf: // String + any number of args -``` -- **Pros**: Common in many languages, intuitive, clear intent -- **Cons**: Ambiguous about types, makes type checking harder - -**B) Array-based variadic: `[T]`** -``` -([T] -- Size) depth: // Takes array of any type -(String [T] --) printf: // String + array of values -``` -- **Pros**: Type-safe, forces bundling arguments, easier to implement -- **Cons**: Requires wrapping args in array syntax, less ergonomic - -**C) Special stack type: `Stack`** -``` -(Stack -- Size) depth: // Full stack reference -(String Stack --) printf: // String + stack reference -``` -- **Pros**: Explicit that it operates on the stack itself, type-safe -- **Cons**: Adds conceptual complexity, what does consuming `Stack` mean? - -**D) Constraint-based: `T...` (typed variadic)** -``` -(T... -- Size) depth: // Homogeneous variadics -(String Stringifiable... --) printf: // Constrained variadics -``` -- **Pros**: Type-safe, clear constraints, flexible -- **Cons**: More complex type system, harder to implement - -**E) Just use current system (no variadic syntax)** -``` -// For depth: it actually just returns depth, doesn't consume -(-- Size) depth: // Just pushes depth - -// For printf: use array -(String [Stringifiable] --) printf: -"x=%d y=%d" [x y] printf -``` -- **Pros**: Simplest, no language changes needed -- **Cons**: `depth` semantics unclear, printf less ergonomic - -**My Recommendation**: **Option E + D (hybrid)** -- For now, don't add variadic syntax - use arrays -- Document that `depth` is a special zero-argument operator that just pushes depth -- If variadics become essential later, add **Option D** (typed variadics with `T...`) - -### 2. **Do all inheritances need to be defined before the trait is?** - -**Options:** - -**A) Yes, inheritance must be before trait** -``` -[ ::Addable ::Multiplyable ] ::Number inher -{ } ::Number trait -``` -- **Pros**: Clear declaration order, simpler parser, inheritance is explicit -- **Cons**: Separates related declarations, two statements needed - -**B) No, allow inline inheritance** -``` -{ } ::Number<::Addable ::Multiplyable> trait -``` -- **Pros**: Single statement, more compact -- **Cons**: Confusing syntax, inheritance looks like generics - -**C) Inheritance in trait body** -``` -{ - inherits: Addable Multiplyable - // methods here -} ::Number trait -``` -- **Pros**: Single statement, clear syntax -- **Cons**: Breaks postfix philosophy, special syntax inside trait body - -**My Recommendation**: **Option A (current design)** -- Keeps declarations explicit and ordered -- Maintains postfix consistency -- Parser knows about inheritance before processing trait body - -### 3. **Is the `inher` operator required?** - -**The Question**: Can empty inheritance work without `inher`? - -**Options:** - -**A) Yes, `inher` is required** (current) -``` -[ ::Addable ::Multiplyable ] ::Number inher -{ } ::Number trait -``` -- **Pros**: Explicit, clear intent, separates inheritance declaration -- **Cons**: Extra operator, more verbose - -**B) No, merge into `trait` operator** -``` -[ ::Addable ::Multiplyable ] { } ::Number trait -``` -- **Pros**: More concise, fewer operators, still clear -- **Cons**: Array prefix becomes ambiguous - is it inheritance or something else? - -**My Recommendation**: **Option A (keep `inher`)** -- Makes inheritance explicit and unambiguous -- Allows future extensions (diamond inheritance rules, conflict resolution) -- Parser can validate inheritance separately from trait definition - -### 4. **Consider removing `inher` and replacing with `impl`?** -### 4. **Consider removing `inher` and replacing with `impl`?** - -**The Idea**: Could trait inheritance use the same mechanism as trait implementation? - -**Current System**: -``` -// Inheritance -[ ::Addable ::Multiplyable ] ::Number inher -{ } ::Number trait - -// Implementation -::Addable { ... } ::i32 impl -``` - -**Options:** - -**A) Keep separate `inher` and `impl`** (current) -- **Pros**: - - Clear distinction between "is-a" (inheritance) and "implements" relationships - - Inheritance affects trait definition itself, impl affects types - - Easier to reason about: traits inherit, types implement - - Can have different rules and semantics for each -- **Cons**: - - Two operators with similar-sounding purposes - - More language constructs to learn - -**B) Use `impl` for both** -``` -// Trait inherits from other traits -::Addable { } ::Number impl -::Multiplyable { } ::Number impl - -// Type implements trait -::Addable { ... } ::i32 impl -``` -- **Pros**: - - Fewer operators - - Unified concept: "X implements Y" - - Simpler mental model -- **Cons**: - - Ambiguous: does `::Addable { } ::Number impl` mean Number implements Addable or inherits from it? - - Can't declare multiple inheritance in one statement - - Would need different semantics based on whether target is a trait or type - - Loses the clear "combine these traits" semantics - -**C) Use `impl` with array syntax** -``` -// Multiple inheritance -[ ::Addable ::Multiplyable ] { } ::Number impl - -// Single inheritance -::Drawable { } ::GameObject impl - -// Type implementation (unchanged) -::Addable { ... } ::i32 impl -``` -- **Pros**: - - Unified operator, but array syntax distinguishes inheritance - - Still allows single-statement multiple inheritance - - Semantics clear from syntax -- **Cons**: - - Array prefix is overloaded (sometimes inheritance, sometimes not) - - Potential ambiguity: is `[::Trait1 ::Trait2]` always inheritance? - -**D) Different syntax entirely** -``` -// Inheritance with "extends" -::Number extends [ ::Addable ::Multiplyable ] { } trait - -// Keep impl for implementations -::Addable { ... } ::i32 impl -``` -- **Pros**: - - Very explicit and clear - - Familiar to OOP programmers - - No ambiguity -- **Cons**: - - Breaks postfix notation (extends comes before trait) - - Adds keyword/operator that's not fully postfix - -**My Recommendation**: **Option A (keep separate)** - -Here's why: -1. **Semantic Clarity**: Inheritance and implementation are fundamentally different: - - Inheritance: `Number` **is composed of** `Addable` + `Multiplyable` + more - - Implementation: `i32` **provides behavior for** `Addable` operations - -2. **Different Use Cases**: - - `inher`: Declares trait relationships at trait definition time - - `impl`: Provides implementations for types (or default implementations for traits) - -3. **Implementation Flexibility**: Keeping them separate allows: - - Different resolution rules for inherited methods - - Diamond inheritance handling - - Multiple inheritance from many traits in one statement - -4. **Parser Benefits**: The `inher` operator clearly signals "the next trait declaration will inherit from these" - ---- - -## Summary of Recommendations - -| TODO | Recommendation | Rationale | -|------|---------------|-----------| -| **Variadic arguments** | **Don't add special syntax yet**. Use arrays for now, document `depth` as zero-arg. Consider `T...` syntax only if truly needed later. | Keeps language simple, arrays work for most cases, can add later if needed | -| **Inheritance before trait?** | **Yes, keep current requirement**. `inher` must come before `trait` definition. | Clear ordering, simpler parser, explicit dependencies | -| **Is `inher` required?** | **Yes, keep `inher` operator**. It makes inheritance explicit and unambiguous. | Clear intent, allows future extensions, parser can validate separately | -| **Replace `inher` with `impl`?** | **No, keep them separate**. They represent different relationships with different semantics. | Semantic clarity, different use cases, better tooling support | - ---- - -## Additional Considerations - -### For Variadic Arguments - -If you later decide you *do* need variadic syntax, I'd suggest this progression: - -**Phase 1 (Current)**: No variadic syntax -``` -(-- Size) depth: // Just returns depth -(String [Stringifiable] --) printf: // Use arrays -``` - -**Phase 2 (If needed)**: Add typed variadics -``` -(String Stringifiable... --) printf: // Zero or more Stringifiable values -``` - -This gives you a simple starting point with a clear upgrade path. - -### For Inheritance Syntax - -The current design is actually quite elegant: - -``` -[ ::Trait1 ::Trait2 ::Trait3 ] ::NewTrait inher -{ - // Additional methods -} ::NewTrait trait -``` - -This clearly shows: -1. What we're inheriting from (the array) -2. That we're declaring inheritance (the `inher` operator) -3. The trait being defined (the `trait` operator) - -It's verbose but crystal clear, which is good for a systems language. - ---- - -Would you like me to add any of these design discussions to the specification document itself, or would you like to explore any of these options in more detail? - ---- - ---- - -My choices for 0.6.1: -Following your suggestions: -- **Variadic arguments** - Don't add special syntax *yet* -- **Inheritance before trait?** - Yes, keep current requirement -- **Replace `inher` with `impl`?** - No, keep them separate -My own choice: -- **Is `inher` required?** - No, merge into trait operator - -And for Variadic arguments do add the array of stuff that will be the current system diff --git a/ideas.md b/ideas.md new file mode 100644 index 0000000..a723525 --- /dev/null +++ b/ideas.md @@ -0,0 +1,310 @@ +Perfect! I've completed version 0.7 with all the non-human TODOs addressed. Now let me discuss the document organization question with you. + +--- + +## Discussion: Document Reorganization for v0.8 + +> **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. What is the best structure for this document? + +### Current Structure Issues + +1. **Duplication**: Section 4.1 defines the `Stackable` trait, then Section 5 describes the same operations from a usage perspective +2. **Mixed Audiences**: Some sections are for language implementers (trait definitions), others for users (how to use operators) +3. **Appendix Bloat**: Appendix A repeats all the trait definitions with more detail + +### Proposed Reorganization Options + +**Option A: User-Focused Main Document, Implementer Appendix** + +``` +Main Document: +1. Overview +2. Lexical Structure +3. Type System (high-level) +4. Using Traits (not defining them) +5. Stack Operations (usage examples) +6. Built-in Operators (by category) +7. Functions +8. Control Flow +9. Data Structures +10. Standard Library + +Appendices: +A. Complete Trait Definitions (for implementers) +B. Grammar Reference +C. Future Features +D. Examples & Tutorials +``` + +**Pros**: Clear separation, main doc is user-friendly +**Cons**: Implementers have to jump to appendix frequently + +--- + +**Option B: Three-Part Structure** + +``` +Part I: Language Basics (for users) +1. Overview +2. Getting Started +3. Lexical Structure +4. Basic Operations +5. Control Flow +6. Data Structures + +Part II: Advanced Features +7. Type System +8. Trait System +9. Generic Programming +10. Standard Library + +Part III: Reference +A. Complete Trait Definitions +B. Grammar +C. Future Features +D. Examples +``` + +**Pros**: Progressive disclosure, easier learning curve +**Cons**: More complex structure, harder to navigate + +--- + +**Option C: Consolidated Single-Topic Sections** + +``` +1. Overview +2. Lexical Structure +3. Type System & Traits (combined) + 3.1 Types + 3.2 Traits + 3.3 Defining Traits + 3.4 Implementing Traits + 3.5 Using Traits +4. Stack Operations (includes trait def + usage) +5. Operators (includes trait defs + usage) +6. Functions +7. Control Flow +8. Data Structures +``` +9. Standard Library + +Appendices: +A. Complete Trait Reference (comprehensive) +B. Grammar Summary +C. Future Features +D. Examples & Tutorials +``` + +**Pros**: Everything about a topic in one place, less jumping around +**Cons**: Sections can get very long, harder to find specific info + +--- + +**Option D: Reference Manual Style** + +``` +1. Overview & Philosophy +2. Lexical Structure +3. Type System +4. Expressions & Operators + 4.1 Stack Operations + 4.2 Arithmetic + 4.3 Comparison + 4.4 Logical + 4.5 Bitwise +5. Statements + 5.1 Functions + 5.2 Control Flow +6. Definitions + 6.1 Traits + 6.2 Structs + 6.3 Unions + 6.4 Enums +7. Standard Library + +Appendices: +A. Trait Reference (all traits alphabetically) +B. Operator Reference (all operators alphabetically) +C. Grammar +D. Future Features +E. Tutorial & Examples +``` + +**Pros**: Traditional reference manual format, easy lookup +**Cons**: Less narrative flow, might be dry + +--- + +**Option E: Minimal Main Doc + Comprehensive Appendix** + +``` +Main Document: +1. Overview +2. Quick Start Guide +3. Lexical Structure +4. Language Constructs + 4.1 Expressions + 4.2 Functions + 4.3 Control Flow + 4.4 Data Structures +5. Type System Overview +6. Trait System Overview + +Appendices: +A. Complete Operator Reference +B. Complete Trait Reference +C. Grammar Reference +D. Standard Library Reference +E. Examples & Patterns +F. Future Features +``` + +**Pros**: Main doc is concise tutorial, appendices are comprehensive reference +**Cons**: Need to consult appendices for detailed info + +--- + +### My Recommendation: **Option C with Modifications** + +I suggest **Option C** because it addresses the duplication issue while keeping related information together. Here's a refined version: + +``` +1. Overview + - Design Principles + - Operators vs Functions + +2. Lexical Structure + - Comments + - Identifiers + - Literals + - Type Tuples + - Token Strings + +3. Type System + - Primitive Types + - Types vs Traits + - Generic Constructs + +4. Trait System + - What are Traits + - Defining Traits + - Implementing Traits + - Trait Inheritance + - Using Traits + +5. Stack Operations + - The Stackable Trait (definition) + - Using Stack Operations (examples) + - Advanced Stack Manipulation + +6. Operators + - Arithmetic (trait def + examples) + - Comparison (trait def + examples) + - Logical (trait def + examples) + - Bitwise (trait def + examples) + +7. Functions + - Defining Functions + - Generic Functions + - Function Examples + +8. Control Flow + - Conditionals + - Loops + - Pattern Matching + +9. Data Structures + - Structs + - Unions + - Enums + - Arrays + +10. Standard Library + - I/O + - String Operations + - Type Conversion + - Container Operations + +Appendices: +A. Complete Trait Reference (alphabetically organized, comprehensive) +B. Complete Operator Reference (alphabetically organized) +C. Grammar Summary +D. Module System (Future) +E. Memory Management (Future) +F. Examples & Tutorials +``` + +**Key Changes**: +1. **Merge trait definitions with usage** - Section 5 and 6 would show trait definition THEN usage examples +2. **Move comprehensive reference to Appendix A** - For implementers who need all details +3. **Keep main sections narrative** - Walk through how to use the language +4. **Appendix A is the "implementer's guide"** - Has every trait with full documentation + +### Specific Section Example: Section 5 (Stack Operations) + +``` +5. Stack Operations + +Stack operations manipulate the runtime stack. All stack operations +implement the Stackable trait: + +5.1 The Stackable Trait + +{ + (Self -- Self Self) dup: + (Self -- ) drop: + (Self Self -- Self Self) swap: + // ... etc +} ::Stackable trait + +5.2 Basic Stack Manipulation + +dup // Duplicate top item + // Example: 5 dup => 5 5 + +drop // Remove top item + // Example: 5 10 drop => 5 + +swap // Swap top two items + // Example: 5 10 swap => 10 5 + +5.3 Advanced Stack Inspection + +pick // Copy nth item to top + // Example: 1 2 3 4 2 pick => 1 2 3 4 2 + +roll // Rotate n items + // Example: 1 2 3 4 3 1 roll => 1 3 4 2 + +5.4 Implementing Stackable for Custom Types + +[examples of custom implementations] +``` + +--- + +### Questions for You + +1. **Which option appeals to you most?** (A, B, C, D, E, or my modified C) + +2. **Primary audience priority?** + - Language learners/users? + - Language implementers? + - Both equally? + +3. **Duplication preference?** + - Minimal duplication (more cross-references) + - Some strategic duplication (easier to read) + +4. **Appendix philosophy?** + - Appendices for reference only + - Appendices for "advanced/future" content + - Appendices for detailed specifications + +5. **Section length preference?** + - Shorter sections (5-10 pages) with more sections + - Longer comprehensive sections + - No preference + +Please let me know your thoughts, and I can create v0.8 with the reorganization you prefer!