YREA-SLS/docs/missing_features.md

Title	Prev	Next
Missing Features

Missing Features

AI Prompt

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.

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

---