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¶

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: