Add map pattern matching and move collections to stdlib

Author: pchalamet

docs/assemblies-and-roles.md

@@ -44,7 +44,7 @@ Role:
 
 Responsibilities:
 - Host context model (`RootDirectory` and related host constraints).
-- Built-in external function modules (`List.*`, `Map.*`, `Option.*`, filesystem, JSON/XML, regex, hash, GUID, print).
+- Built-in external function modules (filesystem, JSON/XML, regex, hash, GUID, print).
 - Extern registry composition.
 - Host-oriented decoding helpers and sandbox-aware path checks.
 

docs/external-functions.md

@@ -19,7 +19,7 @@ Interpreter integration:
 - Extern values are injected into runtime environment as curried `VExternal`.
 
 ## Higher-order extern execution
-Higher-order externs (for example `List.map`, `Map.fold`, `Option.map`) are implemented in runtime extern modules and receive an `ExternalCallContext`.
+Higher-order externs are implemented in runtime extern modules and receive an `ExternalCallContext`.
 
 `ExternalCallContext.Apply` is a function pointer provided by the evaluator so extern code can apply script closures and curried functions without re-implementing evaluation.
 
@@ -49,47 +49,9 @@ Higher-order externs (for example `List.map`, `Map.fold`, `Option.map`) are impl
 - `Hash.md5 : string -> string option`
 - `Guid.new : 'a -> string option` (dummy argument to preserve call shape)
 
-### Map (`'a map`)
-- `Map.empty`
-- `Map.add`
-- `Map.ofList`
-- `Map.tryGet`
-- `Map.count`
-- `Map.filter`
-- `Map.fold`
-- `Map.choose`
-- `Map.map`
-- `Map.iter`
-- `Map.containsKey`
-- `Map.remove`
-
-`Map.empty` is an arity-0 value (`'a map`), not an invokable function.
-
-### List
-- `List.empty`
-- `List.map`
-- `List.choose`
-- `List.collect`
-- `List.contains`
-- `List.distinct`
-- `List.exists`
-- `List.fold`
-- `List.filter`
-- `List.iter`
-- `List.rev`
-- `List.length`
-- `List.tryFind`
-- `List.tryGet`
-- `List.tryHead`
-- `List.tail`
-- `List.append`
-
-### Option
-- `Option.defaultValue`
-- `Option.defaultWith`
-- `Option.isNone`
-- `Option.isSome`
-- `Option.map`
+### Collections and prelude
+- `List.*`, `Option.*`, and `Map.*` helpers are provided by the embedded prelude in `FScript.Language`.
+- Runtime externs focus on host/system capabilities.
 
 ### Typed decoders
 - `Json.deserialize : type -> string -> 'a option`

docs/fsharp-ocaml-differences.md

@@ -6,7 +6,7 @@ This document is a quick comparison guide. It highlights intentional differences
 ## Scope of the language
 - FScript is a small interpreted subset, not a full compiler language.
 - FScript supports a focused core: `let`, `let rec` (functions), `if/elif/else`, `for`, `match`, lists, tuples, options, records, discriminated unions, pipelines, and extern calls.
-- Many F#/OCaml features are intentionally absent today (modules, classes, interfaces, computation expressions, etc.).
+- Many F#/OCaml features are intentionally absent today (classes, interfaces, computation expressions, etc.). `module` declarations are supported only in included files.
 
 ## Syntax differences
 
@@ -81,7 +81,7 @@ let x =
 
 ### Standard library model
 - F#/OCaml ship large standard libraries.
-- FScript has a smaller built-in surface and relies on host-provided externs (for example `List.*`, `Map.*`, `Option.*`, `Fs.*`, `Json.*`, `Xml.*`, `Regex.*`).
+- FScript has a smaller built-in surface and relies on host-provided externs for host/system capabilities (for example `Fs.*`, `Json.*`, `Xml.*`, `Regex.*`), while collection helpers are provided by the embedded prelude.
 
 ### Reflection-style type tokens
 - FScript provides `typeof Name` tokens for host extern workflows (for example JSON/XML decode helpers).

samples/types-showcase.fss

@@ -60,6 +60,13 @@ let mathScore =
 let hasScience = updated.Scores |> Map.containsKey "science"
 let formatAddressKey = "format_address"
 
+let mapPreview =
+    match updated.Scores with
+    | {} ->
+        "empty"
+    | { [subject] = score; ..remaining } ->
+        $"first={subject}:{score}, remaining={Map.count remaining}"
+
 let monthlyPrice =
     match subscription with
     | Free -> 0
@@ -71,6 +78,7 @@ print $"User: {updated.Name}"
 print $"City: {city}"
 print $"Math score: {mathScore}"
 print $"Has 'science': {hasScience}"
+print $"Map preview: {mapPreview}"
 print $"Subscription price: {monthlyPrice}"
 
 // Structural record equivalence showcase:

src/FScript.Language/Ast.fs

@@ -33,6 +33,8 @@ and Pattern =
     | PCons of Pattern * Pattern * Span
     | PTuple of Pattern list * Span
     | PRecord of (string * Pattern) list * Span
+    | PMapEmpty of Span
+    | PMapCons of Pattern * Pattern * Pattern * Span
     | PSome of Pattern * Span
     | PNone of Span
     | PUnionCase of string option * string * Pattern option * Span
@@ -57,6 +59,7 @@ and Expr =
     | EMap of (Expr * Expr) list * Span
     | ERecordUpdate of Expr * (string * Expr) list * Span
     | EFieldGet of Expr * string * Span
+    | EIndexGet of Expr * Expr * Span
     | ECons of Expr * Expr * Span
     | EAppend of Expr * Expr * Span
     | EBinOp of string * Expr * Expr * Span
@@ -90,6 +93,8 @@ module Ast =
         | PCons (_, _, s) -> s
         | PTuple (_, s) -> s
         | PRecord (_, s) -> s
+        | PMapEmpty s -> s
+        | PMapCons (_, _, _, s) -> s
         | PSome (_, s) -> s
         | PNone s -> s
         | PUnionCase (_, _, _, s) -> s
@@ -115,6 +120,7 @@ module Ast =
         | EMap (_, s) -> s
         | ERecordUpdate (_, _, s) -> s
         | EFieldGet (_, _, s) -> s
+        | EIndexGet (_, _, s) -> s
         | ECons (_, _, s) -> s
         | EAppend (_, _, s) -> s
         | EBinOp (_, _, _, s) -> s

src/FScript.Language/Eval.fs

@@ -109,6 +109,22 @@ module Eval =
                     | Some next -> Some (Map.fold (fun state k v -> Map.add k v state) acc next)
                     | None -> None
                 | _ -> None)
+        | PMapEmpty _, VStringMap values when values.IsEmpty ->
+            Some Map.empty
+        | PMapCons (keyPattern, valuePattern, tailPattern, _), VStringMap values when not values.IsEmpty ->
+            let key, value =
+                values
+                |> Seq.head
+                |> fun kv -> kv.Key, kv.Value
+            let tail = VStringMap (values.Remove key)
+            match patternMatch keyPattern (VString key), patternMatch valuePattern value, patternMatch tailPattern tail with
+            | Some keyEnv, Some valueEnv, Some tailEnv ->
+                Some
+                    (Map.empty
+                     |> Map.fold (fun acc k v -> Map.add k v acc) keyEnv
+                     |> Map.fold (fun acc k v -> Map.add k v acc) valueEnv
+                     |> Map.fold (fun acc k v -> Map.add k v acc) tailEnv)
+            | _ -> None
         | PSome (p, _), VOption (Some v) ->
             patternMatch p v
         | PNone _, VOption None -> Some Map.empty
@@ -292,6 +308,16 @@ module Eval =
                     | Some value -> value
                     | None -> raise (EvalException { Message = sprintf "Record field '%s' not found" fieldName; Span = span })
                 | _ -> raise (EvalException { Message = "Field access requires a record value"; Span = span })
+        | EIndexGet (target, keyExpr, span) ->
+            let targetValue = evalExpr typeDefs env target
+            let keyValue = evalExpr typeDefs env keyExpr
+            match targetValue, keyValue with
+            | VStringMap mapValue, VString key ->
+                VOption (mapValue.TryFind key)
+            | VStringMap _, _ ->
+                raise (EvalException { Message = "Map index key must be string"; Span = span })
+            | _ ->
+                raise (EvalException { Message = "Index access requires a map value"; Span = span })
         | ECons (head, tail, span) ->
             let h = evalExpr typeDefs env head
             let t = evalExpr typeDefs env tail
@@ -303,7 +329,10 @@ module Eval =
             let bv = evalExpr typeDefs env b
             match av, bv with
             | VList xs, VList ys -> VList (xs @ ys)
-            | _ -> raise (EvalException { Message = "Both sides of '@' must be lists"; Span = span })
+            | VStringMap left, VStringMap right ->
+                let merged = Map.fold (fun acc key value -> Map.add key value acc) right left
+                VStringMap merged
+            | _ -> raise (EvalException { Message = "Both sides of '@' must be lists or maps"; Span = span })
         | EBinOp (op, a, b, span) ->
             let av = evalExpr typeDefs env a
             let bv = evalExpr typeDefs env b
@@ -362,7 +391,10 @@ module Eval =
             | "@" ->
                 match av, bv with
                 | VList xs, VList ys -> VList (xs @ ys)
-                | _ -> raise (EvalException { Message = "Both sides of '@' must be lists"; Span = span })
+                | VStringMap left, VStringMap right ->
+                    let merged = Map.fold (fun acc key value -> Map.add key value acc) right left
+                    VStringMap merged
+                | _ -> raise (EvalException { Message = "Both sides of '@' must be lists or maps"; Span = span })
             | _ -> raise (EvalException { Message = sprintf "Unknown operator %s" op; Span = span })
         | ESome (value, _) -> VOption (Some (evalExpr typeDefs env value))
         | ENone _ -> VOption None
@@ -409,7 +441,7 @@ module Eval =
         |> Option.iter (fun name ->
             raise (EvalException { Message = $"Top-level binding '{name}' collides with reserved stdlib symbol"; Span = unknownSpan }))
 
-        let stdlibTyped = TypeInfer.inferProgramWithExternsRaw externs (Stdlib.loadProgram())
+        let stdlibTyped = TypeInfer.inferProgramWithExternsRaw externs (Stdlib.loadProgram ())
         let combinedProgram = stdlibTyped @ program
 
         let decls =

src/FScript.Language/FScript.Language.fsproj

@@ -38,6 +38,7 @@
   <ItemGroup>
     <EmbeddedResource Include="Stdlib/List.fss" />
     <EmbeddedResource Include="Stdlib/Option.fss" />
+    <EmbeddedResource Include="Stdlib/Map.fss" />
     <Content Include="..\..\LICENSE" Pack="true" PackagePath="\" />
     <None Include="..\..\README.md" Pack="true" PackagePath="\" Link="README.md" />
     <None Include="..\..\FScriptIcon.png" Pack="true" PackagePath="\" Link="FScriptIcon.png" />

src/FScript.Language/IncludeResolver.fs

@@ -49,6 +49,9 @@ module IncludeResolver =
             | PCons (head, tail, _) -> loop (loop acc head) tail
             | PTuple (patterns, _) -> patterns |> List.fold loop acc
             | PRecord (fields, _) -> fields |> List.fold (fun s (_, p) -> loop s p) acc
+            | PMapEmpty _ -> acc
+            | PMapCons (keyPattern, valuePattern, tailPattern, _) ->
+                loop (loop (loop acc keyPattern) valuePattern) tailPattern
             | PSome (inner, _) -> loop acc inner
             | PUnionCase (_, _, payload, _) ->
                 match payload with
@@ -128,6 +131,8 @@ module IncludeResolver =
                 ERecordUpdate(rewriteExpr boundNames target, updates |> List.map (fun (name, valueExpr) -> name, rewriteExpr boundNames valueExpr), span)
             | EFieldGet (target, fieldName, span) ->
                 EFieldGet(rewriteExpr boundNames target, fieldName, span)
+            | EIndexGet (target, keyExpr, span) ->
+                EIndexGet(rewriteExpr boundNames target, rewriteExpr boundNames keyExpr, span)
             | ECons (head, tail, span) ->
                 ECons(rewriteExpr boundNames head, rewriteExpr boundNames tail, span)
             | EAppend (left, right, span) ->
@@ -149,10 +154,10 @@ module IncludeResolver =
             | SLet(name, args, valueExpr, isRec, isExported, span) ->
                 let qualifiedName = qualifyName moduleName name
                 let bound = args |> List.fold (fun s p -> Set.add p.Name s) Set.empty
-                let bodyBound = if isRec then Set.add name bound else bound
+                let bodyBound = if isRec then Set.add qualifiedName bound else bound
                 SLet(qualifiedName, args, rewriteExpr bodyBound valueExpr, isRec, isExported, span)
             | SLetRecGroup(bindings, isExported, span) ->
-                let names = bindings |> List.map (fun (name, _, _, _) -> name) |> Set.ofList
+                let names = bindings |> List.map (fun (name, _, _, _) -> qualifyName moduleName name) |> Set.ofList
                 let rewrittenBindings =
                     bindings
                     |> List.map (fun (name, args, valueExpr, bindingSpan) ->

src/FScript.Language/Parser.fs

@@ -475,27 +475,47 @@ module Parser =
                     first
             | LBrace ->
                 let lb = stream.Next()
-                let fields = ResizeArray<string * Pattern>()
-                let seen = System.Collections.Generic.HashSet<string>()
-                let parseField () =
+                stream.SkipNewlines()
+                if stream.Match(RBrace) then
+                    PMapEmpty (mkSpanFrom lb.Span lb.Span)
+                elif stream.Peek().Kind = LBracket then
+                    stream.Next() |> ignore // '['
+                    let keyPattern = parsePatternCons()
+                    stream.Expect(RBracket, "Expected ']' in map pattern") |> ignore
                     stream.SkipNewlines()
-                    let nameTok = stream.ExpectIdent("Expected field name in record pattern")
-                    let name =
-                        match nameTok.Kind with
-                        | Ident n -> n
-                        | _ -> ""
-                    if not (seen.Add name) then
-                        raise (ParseException { Message = $"Duplicate field '{name}' in record pattern"; Span = nameTok.Span })
+                    stream.Expect(Equals, "Expected '=' after map key pattern") |> ignore
+                    let valuePattern = parsePatternCons()
                     stream.SkipNewlines()
-                    stream.Expect(Equals, "Expected '=' in record pattern field") |> ignore
-                    let p = parsePatternCons()
-                    fields.Add(name, p)
-                parseField()
-                while stream.Match(Semicolon) do
-                    if stream.Peek().Kind <> RBrace then
-                        parseField()
-                let rb = stream.Expect(RBrace, "Expected '}' in record pattern")
-                PRecord(fields |> Seq.toList, mkSpanFrom lb.Span rb.Span)
+                    if not (stream.Match(Semicolon)) then
+                        raise (ParseException { Message = "Expected ';' before '..' in map pattern"; Span = stream.Peek().Span })
+                    stream.SkipNewlines()
+                    stream.Expect(RangeDots, "Expected '..' in map pattern tail") |> ignore
+                    let tailPattern = parsePatternCons()
+                    stream.SkipNewlines()
+                    let rb = stream.Expect(RBrace, "Expected '}' in map pattern")
+                    PMapCons(keyPattern, valuePattern, tailPattern, mkSpanFrom lb.Span rb.Span)
+                else
+                    let fields = ResizeArray<string * Pattern>()
+                    let seen = System.Collections.Generic.HashSet<string>()
+                    let parseField () =
+                        stream.SkipNewlines()
+                        let nameTok = stream.ExpectIdent("Expected field name in record pattern")
+                        let name =
+                            match nameTok.Kind with
+                            | Ident n -> n
+                            | _ -> ""
+                        if not (seen.Add name) then
+                            raise (ParseException { Message = $"Duplicate field '{name}' in record pattern"; Span = nameTok.Span })
+                        stream.SkipNewlines()
+                        stream.Expect(Equals, "Expected '=' in record pattern field") |> ignore
+                        let p = parsePatternCons()
+                        fields.Add(name, p)
+                    parseField()
+                    while stream.Match(Semicolon) do
+                        if stream.Peek().Kind <> RBrace then
+                            parseField()
+                    let rb = stream.Expect(RBrace, "Expected '}' in record pattern")
+                    PRecord(fields |> Seq.toList, mkSpanFrom lb.Span rb.Span)
             | _ -> raise (ParseException { Message = "Unexpected token in pattern"; Span = t.Span })
 
         and parsePatternCons () : Pattern =
@@ -746,6 +766,20 @@ module Parser =
                         | Ident n -> n
                         | _ -> ""
                     expr <- EFieldGet(expr, fieldName, mkSpanFrom (Ast.spanOfExpr expr) fieldTok.Span)
+                elif stream.Peek().Kind = LBracket then
+                    let lb = stream.Peek()
+                    let targetSpan = Ast.spanOfExpr expr
+                    let isAdjacent =
+                        lb.Span.Start.Line = targetSpan.End.Line
+                        && lb.Span.Start.Column = targetSpan.End.Column
+                    let hasIndexerPayload = stream.PeekAt(1).Kind <> RBracket
+                    if isAdjacent && hasIndexerPayload then
+                        stream.Next() |> ignore
+                        let keyExpr = parseExpr()
+                        let rb = stream.Expect(RBracket, "Expected ']' after index expression")
+                        expr <- EIndexGet(expr, keyExpr, mkSpanFrom targetSpan rb.Span)
+                    else
+                        keepGoing <- false
                 else
                     keepGoing <- false
             expr

src/FScript.Language/Stdlib.fs

@@ -6,7 +6,8 @@ open System.Reflection
 module Stdlib =
     let private stdlibResourceNames =
         [ "FScript.Language.Stdlib.List.fss"
-          "FScript.Language.Stdlib.Option.fss" ]
+          "FScript.Language.Stdlib.Option.fss"
+          "FScript.Language.Stdlib.Map.fss" ]
 
     let private readResourceText (assembly: Assembly) (resourceName: string) =
         use stream = assembly.GetManifestResourceStream(resourceName)