Updated and expanded missing features document

2025-11-02 15:00:28 -07:00 · 2025-11-02 15:00:28 -07:00 · 216e37210e
parent 63d7af7100
commit 216e37210e
1 changed files with 409 additions and 24 deletions
--- a/docs/missing_features.md
+++ b/docs/missing_features.md
@ -6,38 +6,423 @@ Next:

 ## Missing Features

-The following sections and language features are known to be missing from the
-current version of the language specification, but are intended to be added and
-implemented. These are not future plans, but rather features that have been
-identified as necessary for a complete language specification.
+### AI Prompt

- Complete Type Reference
- The `sqrt` operator
- Constants
- Arrays of structs
- Arrays of non-default types
- Identifiers can be any ascii (or possibly unicode) string without whitespace,
-that doesn't start with a digit (`0-9`), `.`, or `:`, and doesn't include `::`
- Integers and floats are allowed to use `_` as deliminator, they are ignored
-after lexing, they are just for the programer
-
-### Arrays of non-default types and structs
-
-Array of signed 64-bit integers
 ```
-[1 1 2 3 5 8]
+Can you apply these changes? Please do not add a new missing features appendix, apply the changes to the existing document. An added Appendix H Complete Type Reference. Please keep the links as they are to separate html files (another program with split and convert the markdown after you're done) but you can add appropriate links as well. List the changes you make as v0.8.2 (AI). Return the entire document. I would prefer it as a markdown artifact instead of directly in chat. Begin with an overview of the changes you are going to make, then after I approve, create the artifact with the improved version.
 ```

-Array of signed 16-bit integers
+### Overview
+
+This addendum describes the **features that should be added** to complete the Stack Language Specification.
+Unlike future features, these are not speculative; they represent missing or incomplete elements that must be implemented for the language to reach functional and structural completeness.
+
+The first section lists all missing areas as of version 0.8.1. Subsequent sections describe **what should be added** and **how** each feature should integrate into the language and specification.
+
+### Missing Feature Summary
+
+| Area                  | Missing Elements                                                   |
+| --------------------- | ------------------------------------------------------------------ |
+| **Core Syntax**       | Constants, numeric underscores, char literals                      |
+| **Type System**       | Pointer types, generic enforcement                                 |
+| **Math Library**      | `sqrt`, `sin`, `cos`, `tan`, rounding, `abs`, `min`, `max`, `rand` |
+| **Data Structures**   | Arrays of structs, typed arrays, maps, tuples                      |
+| **Traits & Generics** | Generic enforcement                                                |
+| **Runtime**           | Memory management model                                            |
+| **Standard Library**  | Math, string, and collection utilities                             |
+| **Meta Features**     | Documentation comments, testing, compiler directives               |
+| **References**        | Complete Operator, Type, and Grammar summaries                     |
+
+### 1. Core Language and Syntax
+
+#### 1.1 Constants
+
+**Should:**
+Add a mechanism for defining compile-time constants available at both global and module scope.
+
+**How:**
+Introduce a `const` keyword with syntax mirroring function or variable definitions:
+
 ```
-[1 1 2 3 5 8 :i16]
+3.1415926535 ::pi const
+9.81 ::gravity const
 ```

-Array of points
-```
-(i32 i32 --) { x: y: } ::Point struct
+Constants should be immutable and resolved at parse time.
+Constants defined at module scope should be accessible via `Module::CONST_NAME`.
+Include mathematical constants (`pi`, `e`, `tau`, `phi`) in the standard library.
+
+#### 1.2 Numeric Literals
+
+**Should:**
+Support enhanced numeric literal syntax.
+
+**How:**
+
+* Permit underscores (`_`) as digit separators, ignored during lexing.
+  Example: `1_000_000` → `1000000`.
+* Add character literal syntax: `'A'`, `'\\n'`.
+* Define octal syntax (`0o755`) alongside existing binary and hex.
+* Specify overflow handling: integers wrap, floats saturate or signal error.
+* Extend grammar accordingly in **Appendix D**.
+
+#### 1.3 Identifiers
+
+**Should:**
+Clarify and enforce identifier lexing rules for ASCII and Unicode.
+
+**How:**
+Update the lexical grammar:

-[ {1 0} {2 1} {0 2} {1 2} {2 2} :Point]
 ```
+identifier → [a-zA-Z_][a-zA-Z0-9_]* | <unicode letters>
+```
+
+Explicitly forbid: whitespace, `{}`, `[]`, `()`, `.`, `'`, `"`, `//`.
+Permit `::` only when prefixed for literals or namespaces.
+
+#### 1.4 Grammar and References
+
+**Should:**
+Complete the missing formal grammar and operator references.
+
+**How:**
+
+* Expand **Appendix D** into a full EBNF grammar covering all literal, type, and declaration syntax.
+* Finalize **Appendix C** with a complete operator list and stack signatures.
+* Link all examples and traits to defined operators for cross-reference integrity.
+
+### 2. Type System
+
+#### 2.1 Type Reference
+
+**Should:**
+Add a **Complete Type Reference** summarizing all primitive, composite, and generic types.
+
+**How:**
+Create **Appendix H: Complete Type Reference**, formatted as:
+
+```
+##### i64
+Signed 64-bit integer.
+Implements ::Stackable, ::Addable, ::Subtractive, ::Multiplicable, ::Divisible, ::Comparable traits.
+
+##### Array<T>
+Homogeneous collection type implementing ArrayOf<T>.
+Implements ::Stackable, ::Iterable<T>, ::Indexable<T> traits.
+
+##### Option<T>
+Union representing an optional value.
+Implements ::Stackable trait.
+```
+
+Each entry should define default values, size, traits, and conversion behaviors.
+
+#### 2.2 Pointer Types
+
+*Future Feature*
+
+**Should:**
+Implement explicit pointer support for heap and stack memory operations.
+
+**How:**
+Define a `ptr<T>` type and `@` operator for referencing:
+
+*Note: This is in contradiction of the previous design decision to not have variables on the heap*
+
+```
+x @ ::p ptr_store
+p ptr_load
+```
+
+Add traits:
+
+* `::Dereferenceable`
+* `::Addressable`
+
+Extend **Appendix F (Memory Management)** to specify ownership and safety model (manual free or borrow semantics).
+
+#### 2.3 Constant Expressions
+
+**Should:**
+Allow constants in heap or data block.
+
+**How:**
+Support syntax like:
+
+```
+10 ::N const
+5 N + // evaluates to 15
+```
+
+Add evaluation rules for constant folding within type signatures and expressions.
+
+#### 2.4 Generic Enforcement
+
+*Future Feature*
+
+**Should:**
+Add compile-time enforcement of trait constraints on generic parameters.
+
+**How:**
+The parser or type checker must validate that generic parameters implement required traits before operator expansion.
+Emit compile-time errors when a generic type is used without satisfying trait requirements.
+
+### 3. Operators and Mathematical Functions
+
+#### 3.1 Mathematical Operators
+
+**Should:**
+Add a complete set of mathematical operators to the standard library.
+
+**How:**
+Define these as trait-backed operators under `::Math`:
+
+```
+(Self -- Self) sqrt:
+(Self -- Self) abs:
+(Self -- Self) sin:
+(Self -- Self) cos:
+(Self -- Self) tan:
+(Self -- Self) asin:
+(Self -- Self) acos:
+(Self -- Self) atan:
+(Self Self -- Self) atan2:
+(Self -- Self) exp:
+(Self -- Self) floor:
+(Self -- Self) ceil:
+(Self -- Self) round:
+(Self Self -- Self) min:
+(Self Self -- Self) max:
+```
+
+Each maps to standard library implementations for numeric types.
+Add constants (`pi`, `e`) and import from `::Math`.
+
+As the standard library is automatically in scope until modules are implemented, which operators are "built-in" vs "standard library" are not yet firmly distinguished.
+
+#### 3.2 Numeric Utilities
+
+**Should:**
+Add randomness, range generation, and overflow handling.
+
+**How:**
+Implement standard functions:
+
+```
+(-- f64) rand
+(f64 --) seed
+(i64 i64 -- Array<i64>) range
+```
+
+Define overflow behavior as *wrapping* for integers and *IEEE-compliant* for floats.
+Optionally include a compiler flag for saturation mode.
+
+### 4. Data Structures
+
+#### 4.1 Arrays
+
+**Should:**
+Support syntax for typed arrays and arrays of structs.
+
+**How:**
+Permit post-type annotations:
+
+```
+[1 2 3 4 :i16]
+[ [1 1] [2 3] :f32]
+[{1 2} {3 4} :Point]
+```
+
+The type annotation should determine both storage and element typing.
+Extend array parsing rules to allow element struct literals and optional explicit types.
+
+#### 4.2 Dictionaries and Maps
+
+*Future Feature*
+
+**Should:**
+Introduce a map data structure and `::Map<K V>` trait implementation.
+
+**How:**
+Define trait:
+
+```
+{
+    (Self K -- V) get:
+    (Self K V -- Self) set:
+} ::Map<K V> trait
+```
+
+Provide built-in type `Map<K V>` with literal syntax:
+
+```
+{ "x" 1, "y" 2 }
+```
+
+#### 4.3 Tuples
+
+*Future Feature*
+
+**Should:**
+Add runtime tuple values separate from type tuples.
+
+**How:**
+Use parentheses for tuple literals:
+
+```
+(1, 2, 3)
+```
+
+Internally represented as anonymous structs with positional fields.
+
+### 5. Runtime and Memory Model
+
+*Future Feature*
+
+**Should:**
+Formalize manual and optional automatic memory management.
+
+**How:**
+Define `alloc`, `free`, and pointer semantics in **Appendix F**:
+
+```
+(i64 -- ptr<i64>) alloc
+(ptr<i64> --) free
+```
+
+Optionally define ownership flags (`borrow`, `move`) for static analysis.
+
+### 6. Standard Library
+
+#### 6.1 Math and Numeric
+
+**Should:**
+Add complete numeric suite.
+
+**How:**
+
+* `sqrt`, `pow`, `exp`, `logb`
+* `clamp`, `sign`, `sum`, `mean`
+
+Implemented via the `::Math` module.
+
+#### 6.2 Collections
+
+**Should:**
+Add higher-order and structural functions.
+
+**How:**
+
+* `zip`, `enumerate`, `foldl`, `foldr`
+* Extend `Iterable` and `ArrayOf` traits to include them.
+
+#### 6.3 Strings
+
+**Should:**
+Add comprehensive string manipulation utilities.
+
+**How:**
+Implement and define `::StringOps` trait with:
+
+* `replace`, `trim`, `find`, `format`
+* `starts_with`, `ends_with`
+
+#### 6.4 Date and Time
+
+**Should:**
+Introduce time and duration utilities.
+
+**How:**
+
+```
+(-- Timestamp) now
+(Timestamp Timestamp -- Duration) diff
+(Duration --) sleep
+```
+
+### 7. Meta-Language and Tooling
+
+#### 7.1 Documentation
+
+*Future Feature*
+
+**Should:**
+Add `///` for documentation comments and module metadata extraction.
+
+**How:**
+
+```
+/// Adds two numbers.
+(i64 i64 -- i64) add:
+```
+
+Comments beginning with `///` should be associated with the following declaration and exportable via tooling.
+
+#### 7.2 Testing
+
+Add `assert` operator for inline assertions:
+
+```
+{ 2 3 + } { 5 == } assert
+```
+
+#### 7.3 Testing
+
+*Future Feature*
+
+Add `test` and `test_error` operators for unit testing:
+
+```
+{ { 2 3 + } { 5 == } assert } "Addition test" test
+{ 1 0 / } "Division by zero test" test_error
+```
+
+
+Document these under **Appendix I: Testing Reference**.
+
+#### 7.4 Compiler Directives
+
+**Should:**
+Add directives for interpreter and compiler configuration.
+
+**How:**
+
+```
+#!/usr/bin/sls
+#require "0.9"
+```
+
+This disallows `#` from appearing in identifiers and reserves it for directives.
+
+#### 7.5 Reflection
+
+**Should:**
+Add runtime type and trait introspection.
+
+**How:**
+
+```
+(x -- IdentifierLiteral) type_of
+(T IdentifierLiteral -- bool) implements
+```
+
+These should expose runtime type and trait information for debugging or metaprogramming.
+
+### 8. Reference Completion
+
+**Should:**
+Finalize all reference appendices with consistent format and hyperlinks.
+
+**How:**
+
+| Appendix | Description                                | Action                                               |
+| -------- | ------------------------------------------ | ---------------------------------------------------- |
+| **C**    | Operator Reference                         | Populate with all built-in and math operators        |
+| **D**    | Grammar Summary                            | Add formal EBNF grammar                              |
+| **F**    | Memory Management (Future)                 | Expand with pointer and heap semantics               |
+| **H**    | Type Reference                             | Add unified type listing                             |
+| **I**    | Testing Reference (Future)                 | Document testing operators and usage                 |
+| **J**    | Map, Dictionary, Tuple References (Future) | Document map, dictionary, and tuple types and traits |

 ---