docs: document extern keyword arguments (#22)

* examples/interop: document extern keyword arguments

The cookbook's pattern catalogue covered instance access, class targets and
extern import, but never keyword arguments on a target. One bullet now covers
both forms: a literal pinned at the declaration, and a `...` slot taking its
value from the caller.

* docs: lesson 23, keyword arguments at the boundary

A Going further lesson covering both forms of extern keyword argument: a
literal pinned at the declaration, and a `...` slot taking its value from
the caller. Walks the binding rule, the emitted Python, and the fact that
currying holds across the boundary; the exercise collapses two rigid externs
into one slot extern.

Verified by docs/verify_lessons.py (deep link, solution output, and every
worked-example block).

Author: simontreanor

docs/src/SUMMARY.md

@@ -30,6 +30,7 @@
 - [Build your own computation expression](learn/20-build-your-own-ce.md)
 - [Strings and numbers, in detail](learn/21-strings-and-numbers.md)
 - [Opaque types](learn/22-opaque-types.md)
+- [Keyword arguments at the boundary](learn/23-keyword-arguments.md)
 
 # For educators
 

docs/src/learn/23-keyword-arguments.md

@@ -0,0 +1,132 @@
+# 23. Keyword arguments at the boundary
+
+Python functions lean on keyword arguments with defaults. `int` takes a `base`, `open` takes an
+`encoding`, and `requests.get` takes a `timeout`. A Pyfun arrow is positional, so an `extern` needs a
+way to say which keyword a value belongs to. A trailing `(kw = value, …)` on the target says it, and
+the value comes in two kinds.
+
+The first kind is a literal, fixed once at the declaration:
+
+```pyfun
+extern parseHex: string -> int = int(base = 16)
+
+let raw = "ff"
+
+raw |> parseHex |> print
+```
+
+```console
+255
+```
+
+`parseHex` reads hexadecimal and nothing else, because the `16` belongs to the declaration rather
+than the call. The emitted Python puts the keyword back where Python wants it:
+
+```python
+raw = "ff"
+print(int(raw, base=16))
+```
+
+That suits a value which never changes. When it does change, `...` in place of the literal takes the
+value from the caller:
+
+```pyfun
+extern parseIn: string -> int -> int = int(base = ...)
+
+let fromHex s = parseIn s 16
+let fromBinary s = parseIn s 2
+
+let a = "ff"
+let b = "1011"
+
+a |> fromHex |> print
+b |> fromBinary |> print
+```
+
+```console
+255
+11
+```
+
+One extern now covers every base. The type gained an argument for the slot to claim, and
+`parseIn : string -> int -> int` is an ordinary curried arrow, so inference, effects, and the checker
+treat it like any other function. What changes is where the argument lands in the emitted call:
+
+```python
+def fromHex(s):
+    return int(s, base=16)
+def fromBinary(s):
+    return int(s, base=2)
+```
+
+The binding rule reads the way a Python call reads. The target takes the leading arguments
+positionally, and the slots take the trailing ones in the order the keywords are written. A pinned
+literal claims no argument, so the two mix freely: `builtins.open(mode = "rt", encoding = ...)` takes
+a path first and an encoding second. Slots also work on the instance-access targets from lesson 12,
+where the receiver claims the first argument, as in `= .write_text(encoding = ...)`.
+
+Currying holds across the boundary. A slot extern applied to some of its arguments is a function
+awaiting the rest, like any other Pyfun function:
+
+```pyfun
+extern parseIn: string -> int -> int = int(base = ...)
+
+let ff = parseIn "ff"
+
+ff 16 |> print
+```
+
+```console
+255
+```
+
+The spelling comes from Python's own stub files, where `def get(url, timeout=...)` marks a value the
+signature declines to spell out. Reach for a pinned literal when every call wants the same value, and
+for a slot when the caller decides.
+
+## Exercise
+
+The program below declares two externs that differ only in the base each one pins. Replace them with
+a single extern whose base comes from the caller, and keep the output the same.
+
+```pyfun
+# Two externs that differ only in the base each one pins.
+extern parseHex: string -> int = int(base = 16)
+extern parseBinary: string -> int = int(base = 2)
+
+let hex = "ff"
+let binary = "1011"
+
+hex |> parseHex |> print
+binary |> parseBinary |> print
+```
+
+Expected output:
+
+```console
+255
+11
+```
+
+[Open in the playground](https://simontreanor.github.io/Pyfun/playground/#code=IyBUd28gZXh0ZXJucyB0aGF0IGRpZmZlciBvbmx5IGluIHRoZSBiYXNlIGVhY2ggb25lIHBpbnMuCmV4dGVybiBwYXJzZUhleDogc3RyaW5nIC0-IGludCA9IGludChiYXNlID0gMTYpCmV4dGVybiBwYXJzZUJpbmFyeTogc3RyaW5nIC0-IGludCA9IGludChiYXNlID0gMikKCmxldCBoZXggPSAiZmYiCmxldCBiaW5hcnkgPSAiMTAxMSIKCmhleCB8PiBwYXJzZUhleCB8PiBwcmludApiaW5hcnkgfD4gcGFyc2VCaW5hcnkgfD4gcHJpbnQK)
+
+<details>
+<summary>Show solution</summary>
+
+```pyfun
+extern parseIn: string -> int -> int = int(base = ...)
+
+let fromHex s = parseIn s 16
+let fromBinary s = parseIn s 2
+
+let hex = "ff"
+let binary = "1011"
+
+hex |> fromHex |> print
+binary |> fromBinary |> print
+```
+
+One declaration replaces both, and the base moves from the declaration to the call. The two named
+helpers keep the call sites reading as pipelines, and either one can be passed around on its own,
+because `parseIn s` is a function awaiting a base.
+</details>

docs/src/learn/README.md

@@ -46,5 +46,5 @@ measure, multi-file projects, and a capstone that puts everything together.
 
 After the capstone, a **Going further** set digs into topics the core path skips: recursion,
 async, active patterns, building your own computation expression, the fine print of strings and
-numbers, and opaque types. Take them in any order once you have finished the core lessons they
-build on.
+numbers, opaque types, and keyword arguments at the Python boundary. Take them in any order once
+you have finished the core lessons they build on.

examples/interop/README.md

@@ -78,6 +78,16 @@ The honest headline is therefore **not** "rewrite the popular libraries in Pyfun
   wrapper is needed. And where a library defines its API on `+`/`-` (as `datetime` does),
   Python's `operator` module exposes every operator as a plain function: `= operator.add`
   is a ready-made extern target (`datetime.pyfun`).
+- **Keyword arguments on the target.** A trailing `(kw = value, …)` puts Python keyword
+  arguments on every emitted call, reaching keyword-only and deep-positional parameters
+  without the positional fillers needed to skip past them. A literal is pinned at the
+  declaration (`extern openText : string -> a = builtins.open(mode = "rt")`), and `...`
+  takes the value from the caller, so one extern covers every call shape instead of one per
+  fixed value: `extern parseInt : string -> int -> int = int(base = ...)` lowers
+  `parseInt "ff" 16` to `int("ff", base=16)`. Pinned literals consume no argument, so the
+  two mix (`= builtins.open(mode = "rt", encoding = ...)`), and both work on a receiver
+  method (`= .write_text(encoding = ...)`). A partially applied slot extern keeps working:
+  `parseInt "ff"` is a function awaiting the base.
 - **`extern import` when the heuristic can't see the module.** A dotted target's module is
   guessed by its lowercase prefix, which mis-reads a lowercase *class* (or value attribute)
   as a submodule. Declare it explicitly — Python's own import statement, `as` and all: