423 lines
10 KiB
Markdown
423 lines
10 KiB
Markdown
---
|
|
Title: Missing Features
|
|
Prev:
|
|
Next:
|
|
---
|
|
|
|
## Missing Features
|
|
|
|
### 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:
|
|
|
|
```
|
|
3.1415926535 ::pi const
|
|
9.81 ::gravity const
|
|
```
|
|
|
|
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:
|
|
|
|
```
|
|
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 |
|
|
|
|
---
|