Add changelog, map matching reference, and embedding doc cookbook

Author: pchalamet

CHANGELOG.md

@@ -0,0 +1,78 @@
+# Changelog
+
+All notable changes to FScript are documented in this file.
+
+## [Unreleased]
+
+### Documentation
+- Added dedicated map matching reference: `docs/map-matching-reference.md`.
+- Added include-resolution details (path normalization, root confinement, include deduplication, file-aware errors) in `docs/syntax-and-indentation.md`.
+- Added embedding cookbook section to `docs/embedding-fscript-language.md`.
+- Added and expanded onboarding tutorial and README navigation polish.
+
+## [0.23.1]
+
+### Documentation
+- Refined onboarding tutorial and prioritized tutorial-first navigation in `README.md`.
+
+## [0.23.0]
+
+### Documentation
+- Added progressive getting-started tutorial and linked it from docs/README.
+
+## [0.22.0]
+
+### Documentation
+- Updated docs and samples for `int` + `string` map keys.
+
+## [0.21.0]
+
+### Language
+- Added `int` and `string` map key support with inferred polymorphic empty maps.
+
+## [0.20.0]
+
+### Language
+- Improved map pattern matching semantics.
+
+## [0.19.0]
+
+### Language
+- Added `when` guards in match cases.
+
+## [0.18.0]
+
+### Language
+- Added map spread syntax (`{ [k] = v; ..tail }`).
+- Restricted append operator `@` to list-only usage.
+
+## [0.17.0]
+
+### Language and stdlib
+- Added map pattern matching.
+- Moved collection helpers to stdlib-first model.
+
+## [0.16.0]
+
+### Language
+- Added qualified discriminated union constructors/pattern support.
+
+## [0.15.2]
+
+### Packaging
+- Stopped packing `FScript.png` in NuGet packages.
+
+## [0.15.1]
+
+### Documentation
+- Updated README content.
+
+## [0.15.0]
+
+### Packaging
+- Added NuGet package icon and branding assets.
+
+## [0.14.0]
+
+### Language
+- Improved indentation diagnostics for misindented expressions.

README.md

@@ -120,6 +120,7 @@ See [`docs/sandbox-and-security.md`](docs/sandbox-and-security.md) for the full
 
 - [`docs/syntax-and-indentation.md`](docs/syntax-and-indentation.md)
 - [`docs/supported-types.md`](docs/supported-types.md)
+- [`docs/map-matching-reference.md`](docs/map-matching-reference.md)
 - [`docs/function-annotations.md`](docs/function-annotations.md)
 - [`docs/external-functions.md`](docs/external-functions.md)
 - [`docs/stdlib-functions.md`](docs/stdlib-functions.md)
@@ -128,6 +129,10 @@ See [`docs/sandbox-and-security.md`](docs/sandbox-and-security.md) for the full
 - [`docs/fsharp-ocaml-differences.md`](docs/fsharp-ocaml-differences.md)
 - [`docs/assemblies-and-roles.md`](docs/assemblies-and-roles.md)
 
+## Changelog
+
+- [`CHANGELOG.md`](CHANGELOG.md)
+
 ## License
 
 This project is licensed under the MIT License.  

docs/embedding-fscript-language.md

@@ -185,3 +185,71 @@ Use `Pretty.valueToString` for a readable string form.
 Each error contains:
 - `Message`
 - `Span` (`Line`/`Column` information)
+
+## Embedding cookbook
+
+### 1. Parse/eval a file with `#include`
+Use include-aware parsing when executing scripts from disk.
+
+```fsharp
+open FScript.Language
+
+let root = "/path/to/workspace"
+let entry = "/path/to/workspace/main.fss"
+
+let program = FScript.parseFileWithIncludes root entry
+let typed = FScript.infer program
+let value = FScript.eval typed
+```
+
+### 2. Load once, invoke many times
+Use `ScriptHost` when you want to invoke exported functions repeatedly.
+
+```fsharp
+open FScript.Language
+open FScript.Runtime
+
+let hostContext = { RootDirectory = "." }
+let externs = Registry.all hostContext
+
+let loaded =
+    ScriptHost.loadFile externs "./script.fss" "."
+
+let r1 = ScriptHost.invoke loaded "run" [ VString "build" ]
+let r2 = ScriptHost.invoke loaded "run" [ VString "test" ]
+```
+
+### 3. Add one custom extern
+Define a typed external function and pass it to inference/evaluation.
+
+```fsharp
+open FScript.Language
+
+let envExtern =
+    { Name = "Env.get"
+      Scheme = Forall([], TFun(TString, TOption TString))
+      Arity = 1
+      Impl =
+        function
+        | [ VString key ] ->
+            System.Environment.GetEnvironmentVariable(key)
+            |> Option.ofObj
+            |> VOption
+        | _ ->
+            raise (EvalException { Message = "Env.get expects one string"; Span = Span.mk (Span.pos 0 0) (Span.pos 0 0) }) }
+
+let src = "Env.get \"HOME\""
+let program = FScript.parse src
+let typed = FScript.inferWithExterns [ envExtern ] program
+let value = FScript.evalWithExterns [ envExtern ] typed
+```
+
+### 4. Export descriptor discovery
+After inference, get function descriptors to expose callable surface in hosts.
+
+```fsharp
+open FScript.Language
+
+let typed = "[<export>] let run x = x" |> FScript.parse |> FScript.infer
+let descriptors = Descriptor.describeFunctions typed Map.empty
+```

docs/map-matching-reference.md

@@ -0,0 +1,92 @@
+# FScript Map Matching Reference
+
+## Purpose
+This document is a focused reference for `match` patterns on maps.
+
+## Map pattern basics
+Map patterns use brace + keyed clauses:
+
+```fsharp
+match values with
+| { ["name"] = v } -> v
+| _ -> ""
+```
+
+Keys can be `string` or `int`:
+
+```fsharp
+match codes with
+| { [200] = label } -> label
+| _ -> "missing"
+```
+
+## Supported forms
+
+### Single key
+```fsharp
+| { ["a"] = x } -> ...
+```
+
+### Multiple keys
+```fsharp
+| { ["a"] = x; ["b"] = y } -> ...
+```
+
+### Tail capture
+```fsharp
+| { ["a"] = x; ..rest } -> ...
+```
+
+### Dynamic key extraction
+```fsharp
+| { [k] = v; ..rest } -> ...
+```
+
+### Guarded key checks
+Use `when` for key equality checks (instead of pinning syntax):
+
+```fsharp
+| { [current] = v; ..rest } when current = key -> ...
+```
+
+## Partial matching semantics
+Map matching is partial:
+- a pattern only requires the listed keys to exist,
+- additional keys in the matched value are allowed.
+
+Example:
+
+```fsharp
+match values with
+| { ["name"] = name } -> $"name={name}"
+| _ -> "no match"
+```
+
+This still matches if `values` has extra keys.
+
+## Practical examples
+
+### Remove one key
+```fsharp
+let remove key values =
+  match values with
+  | { [current] = _; ..rest } when current = key -> rest
+  | _ -> values
+```
+
+### Match two required keys
+```fsharp
+let describe values =
+  match values with
+  | { ["name"] = name; ["owner"] = owner } -> $"{name} by {owner}"
+  | _ -> "unknown"
+```
+
+## Notes
+- Map literals:
+  - `{}` empty map
+  - `{ ["k"] = v }`
+  - `{ [1] = v }`
+  - `{ ["k"] = v; ..tail }`
+- For map construction/update rules, see `docs/supported-types.md`.
+- For full syntax/layout rules, see `docs/syntax-and-indentation.md`.

docs/supported-types.md

@@ -31,6 +31,7 @@ This document specifies the value and type system used by the interpreter.
   - record entries use `Field = value`
   - `{}` denotes an empty map.
 - Values are inferred and unified to a single value type.
+- See `./map-matching-reference.md` for focused map-pattern examples.
 
 ## Function types
 - Functions use curried arrow types:

docs/syntax-and-indentation.md

@@ -214,3 +214,13 @@ All of the following map literal layouts are valid:
 - Include loading is recursive.
 - Cycles are fatal and reported as parse errors.
 - File paths in includes must be `.fss`.
+- Include resolution is file-relative:
+  - `#include "x.fss"` resolves from the directory of the file containing the directive.
+- Paths are normalized before loading:
+  - relative segments like `.` and `..` are collapsed.
+- Resolved files must stay inside the configured sandbox root (`RootDirectory`).
+  - escaping the root is a parse error.
+- A file already loaded once in the include graph is skipped on subsequent includes.
+  - includes are effectively deduplicated.
+- `#include` must appear before module declarations and executable/type code in a file.
+- Parse/type/eval errors include file-aware spans (`file`, `line`, `column`) so failures in included files point to the offending source.