jade-lang 0.4.0 → 0.6.0

data/docs/json.md

@@ -0,0 +1,163 @@
+# Decoding and encoding
+
+`Decode` turns untyped JSON / Ruby data into typed Jade values; `Encode` turns
+typed values back into JSON. Both are explicit pipelines, and both auto-derive
+for `struct` types so the common case needs no hand-written decoder or encoder.
+
+## Decoding
+
+A decoder is a value; `Decode.decode_string(decoder, json)` runs one and returns
+a `Result(a, DecodeError)`. The combinators compose:
+
+```jade
+module DecodeJson exposing (
+  age,
+  coords,
+  tags,
+  user,
+)
+
+import Decode exposing (DecodeError)
+
+
+struct User = {
+  name: String,
+  age: Int
+}
+
+
+def age(json: String) -> Result(Int, DecodeError)
+  Decode.decode_string(Decode.field("age", Decode.int), json)
+end
+
+
+def tags(json: String) -> Result(List(String), DecodeError)
+  Decode.decode_string(Decode.list(Decode.string), json)
+end
+
+
+def coords(json: String) -> Result(Maybe(Int), DecodeError)
+  Decode.decode_string(Decode.nullable(Decode.int), json)
+end
+
+
+def user(json: String) -> Result(User, DecodeError)
+  decoder = Decode.succeed(User(_, _))
+    |> Decode.required("name", Decode.string)
+    |> Decode.required("age", Decode.int)
+
+  Decode.decode_string(decoder, json)
+end
+```
+
+```ruby
+DecodeJson::Internal.age('{"age":40}')             # => Ok(40)
+DecodeJson::Internal.tags('["a","b"]')             # => Ok(["a", "b"])
+DecodeJson::Internal.coords('null')                # => Ok(Nothing)
+DecodeJson::Internal.coords('7')                   # => Ok(Just(7))
+DecodeJson::Internal.user('{"name":"Ada","age":40}')
+# => Ok(User(name: "Ada", age: 40))
+DecodeJson::Internal.user('{"name":"Ada"}')
+# => Err(MissingField("age"))
+```
+
+The struct decoder is `Decode.succeed(User(_, _))` piped through one
+`Decode.required` per field — the `_` placeholders are the constructor's holes,
+filled left to right as each field decodes.
+
+## Encoding
+
+`Encode.encode_to_string(value)` serializes; the combinators mirror `Decode`:
+
+```jade
+module EncodeJson exposing (n, point, user, xs)
+
+import Encode
+
+
+struct User = {
+  name: String,
+  age: Int
+}
+
+
+def n -> String
+  Encode.encode_to_string(Encode.int(42))
+end
+
+
+def xs -> String
+  Encode.encode_to_string(Encode.list(Encode.int, [1, 2, 3]))
+end
+
+
+def point -> String
+  pairs = [
+    Encode.field("x", Encode.int, 1),
+    Encode.field("y", Encode.int, 2),
+  ]
+
+  Encode.encode_to_string(Encode.object(pairs))
+end
+
+
+def user(u: User) -> String
+  Encode.encode_to_string(Encode.encode(u))
+end
+```
+
+```ruby
+EncodeJson.n                  # => "42"
+EncodeJson.xs                 # => "[1,2,3]"
+EncodeJson.point              # => '{"x":1,"y":2}'
+EncodeJson::Internal.user(user)
+# => '{"name":"Ada","age":40}'
+```
+
+## Auto-derivation
+
+`Encode.encode(value)` derives the encoder from the value's type, and
+`Decode.from_json(json)` derives the decoder from the **return type** — so a
+struct round-trips without writing either by hand:
+
+```jade
+module Api exposing (parse, render)
+
+import Encode
+import Decode exposing (DecodeError)
+
+
+struct User = {
+  name: String,
+  age: Int
+}
+
+
+def parse(json: String) -> Result(User, DecodeError)
+  Decode.from_json(json)
+end
+
+
+def render(user: User) -> String
+  Encode.encode_to_string(Encode.encode(user))
+end
+```
+
+Reach for the explicit combinators above when the JSON shape doesn't match the
+struct one-to-one — renamed keys, nested lookups, optional fields.
+
+Derivation reaches through the structural types to their elements, so anything
+built out of encodable parts is itself encodable:
+
+| Type | Wire form |
+|------|-----------|
+| `List(a)`, `Set(a)` | array — a set drops duplicates on the way back |
+| `Maybe(a)` | the value, or `null` |
+| `(a, b)` … `(a, b, c, d)` | array, positional |
+| `Dict(k, v)` | array of `[key, value]` pairs — a JSON object only admits string keys |
+| a `struct` | object, keyed by field name |
+| a union whose variants take no arguments | string, the variant name in snake_case |
+
+A type outside that list needs its own `implements Encodable(T)` /
+`Decodable(T)` — a union carrying arguments, say, where nothing but you knows
+which shape it should take.

data/docs/lsp.md

@@ -0,0 +1,105 @@
+# Language server
+
+Jade ships a language server, run as `jade lsp`. It speaks LSP over stdio and
+works in any editor with an LSP client.
+
+## What it does
+
+- **Diagnostics.** Type and parse errors are streamed to the editor as you type.
+- **Hover.** Hover any name, local, or expression to see its inferred type.
+- **Go to definition.** Jump from a use site to where a name is declared —
+  across modules, into the stdlib, and to interface implementations.
+- **Find references.** Every use of a name across the project, declaration
+  included.
+- **Document symbols.** The editor's outline ("show all functions in this
+  file") works.
+
+## Editor setup
+
+The server is `jade lsp` on stdio. Point your editor's LSP client at it for
+files matching `*.jd`.
+
+### Neovim
+
+```lua
+-- Treat *.jd files as filetype "jd"
+vim.filetype.add({ extension = { jd = 'jd' } })
+
+vim.lsp.start({
+  name = 'jade-lsp',
+  cmd = { 'jade', 'lsp' },
+  root_dir = vim.fs.dirname(vim.fs.find({ 'Gemfile', '.git' }, { upward = true })[1]),
+  filetypes = { 'jd' },
+})
+```
+
+### VS Code
+
+No published extension yet. The server works with any LSP-client extension that
+lets you point at a custom command (e.g. `vscode-languageclient` with a small
+wrapper that runs `jade lsp`).
+
+### Other editors
+
+If your editor speaks LSP, it'll work — the server depends on no editor-specific
+bridge.
+
+## For agents that don't speak LSP
+
+`jade q` exposes the same compiler intelligence as one-shot JSON over stdout —
+handy for agents and scripts that don't want to manage a JSON-RPC session:
+
+```
+jade q hover    file.jd:LINE:COL   # type info at a position
+jade q defn     file.jd:LINE:COL   # goto-definition target
+jade q refs     file.jd:LINE:COL   # all references (incl. declaration)
+jade q symbols  file.jd            # document outline
+jade q api      [MODULE|NAME]      # signatures, by module or symbol
+jade q find     TERM               # every symbol matching TERM
+jade q syntax   [FORM]             # how a form is written
+```
+
+`LINE` and `COL` are 0-indexed (LSP convention). Paths are relative to the
+project root; compile results are cached at `.jade/cache`, so repeat queries are
+fast.
+
+`api` and `find` cover the stdlib, the project's own modules, and any extension
+gem's — each tagged with its `origin`. Without a `jade.json` they fall back to
+the stdlib alone, so they still answer from any directory. See
+[stdlib.md](stdlib.md#finding-a-function).
+
+`syntax` answers the other half. A signature says a function exists and what it
+takes; it never says how a lambda or an `implements` block is written:
+
+```
+$ jade q syntax lambda
+{ "form": "lambda", "detail": "anonymous function", "source": "(args) -> { body }" }
+```
+
+The forms are `def`, `type`, `struct`, `case`, `if`, `module`, `import`,
+`interface`, `implements`, `uses`, `lambda` — the same corpus the editor
+offers as completions, so the two can't drift. They're templates, not
+compilable programs. It reads no files and needs no project.
+
+## Checking without an editor
+
+`jade check` type-checks and prints diagnostics, generating nothing:
+
+```
+jade check                 # every .jd under the source root
+jade check lib/orders.jd   # that file and everything it imports
+```
+
+Exit 1 if there were errors, 0 otherwise. This is the loop to close after
+editing a file — it's the same front end the LSP runs, so an invented function
+or a wrong argument order surfaces immediately instead of at the next build.
+
+## What it doesn't do yet
+
+- Autocomplete
+- Refactor / rename
+- Code actions (e.g. "add the missing case to this `case`")
+- Workspace-wide symbol search
+
+These are the natural next features; the current server is the minimum useful
+surface.

data/docs/stdlib.md

@@ -0,0 +1,69 @@
+# Standard library
+
+## Finding a function
+
+Ask the compiler, don't grep:
+
+```
+jade q api                 # every module, and where it came from
+jade q api Dict            # one module, with signatures
+jade q api List.fold       # one symbol
+jade q find fold           # everything named `fold`
+```
+
+Grep is the wrong tool here, and quietly so. Stdlib modules are written two
+ways — Jade source in a heredoc (`Maybe`, `Result`, `Decimal`, …) and a Ruby
+DSL (`List`, `String`, `Dict`, `Decode`, …) — so half of them never spell `def`
+at all, and none of them contains the string `List.map` you'd search for.
+Extension modules aren't in your tree at all; they live in a gem. A grep that
+comes back empty means nothing.
+
+`jade q api` reads the registry the compiler itself resolves against, so it
+can't drift from what exists. It answers what grep can't: the argument order
+(`List.fold` folds with `(b, a) -> b`, `Dict.fold` with `(k, v, b) -> b`), the
+interface constraints (`List.sort : Comparable a => …`), a struct's fields
+(`struct Date = { year : Int, month : Month, day : Int }`), and which types
+implement `Decodable` or `Encodable`.
+
+Run inside a project and it covers three origins, each tagged in the output:
+
+| `origin` | what |
+|---|---|
+| `stdlib` | the modules below |
+| `project` | your own `.jd` files, under the source root |
+| `extension` | modules an extension gem ships (`jade-sql`'s `Sql.Query`, …) |
+
+Without a `jade.json` it falls back to the stdlib alone, so the query still
+works from anywhere. A file that won't compile is named under `skipped` rather
+than quietly missing — an absent module reads as "that function doesn't
+exist", which is the failure this is here to prevent.
+
+## What's where
+
+Every module's source lives in [`lib/jade/stdlib/`](../lib/jade/stdlib/) — short,
+readable Ruby. This is a map of the territory; `jade q api` is the atlas.
+
+| Module | What's there |
+|--------|--------------|
+| `Basics` | The built-in interfaces — `Eq`, `Comparable`, `Appendable`, `Mappable`, `Chainable` — plus the `Ordering` type (`LT` / `EQ` / `GT`) and `Never`. `++` works on `String`, `List`, and `Bytes` via `Appendable`. |
+| `Maybe` | Optional values without `nil`: `Just(a)` / `Nothing`, with `map`, `and_then`, `with_default`. |
+| `Result` | Errors as values, no exceptions: `Ok(a)` / `Err(e)`, with `map`, `and_then`, `map_error`, `on_error`, `sequence`. |
+| `List` | Immutable lists: `map`, `filter`, `fold`, `zip`, `sort`, `length`, `range`, `head`, `tail`, `take`, `drop`, … |
+| `String` | Text: `length`, `reverse`, `split`, `trim`, `to_int`, `contains?`, `uncons`, `cons`, `from_char`, `map`. |
+| `Char` | Character predicates and codes: `to_code`, `from_code`, `digit?`, `alpha?`, `alpha_numeric?`, `upper?`, `lower?`. |
+| `Tuple` | Pair accessors: `first`, `second`, `pair`. |
+| `Task` | Side-effecting actions: `succeed`, `fail`, `map`, `and_then`, `on_error`, `sequence`. See [interop.md](interop.md) for how Tasks cross the Ruby boundary. |
+| `Decode` | Parse JSON / Ruby data into typed values: `string`, `int`, `float`, `bool`, `list`, `field`, `index`, `succeed`, `required`, `optional`, `nullable`, `map`, `and_then`. Auto-derived for `struct` types. See [json.md](json.md). |
+| `Decode.Params` | PATCH-style decoders: only fields present in the input appear in the output, missing fields don't error. For partial-update endpoints. |
+| `Encode` | Symmetric to `Decode`: `string`, `int`, `float`, `bool`, `list`, `object`. Auto-derived for `struct` types via `Encodable`. |
+| `Dict` | Immutable key-value map with structural equality: `empty`, `get`, `member?`, `insert`, `update`, `remove`, `keys`, `values`, `to_list`, `from_list`, `map`, `filter`, `fold`, `union`, `merge`. |
+| `Set` | Immutable set: `empty`, `insert`, `remove`, `member?`, `to_list`, `from_list`, `map`, `filter`, `fold`, `union`, `intersect`, `diff`. |
+| `Bytes` | Opaque byte buffer: `empty`, `width`, `from_list` / `to_list`, `from_string` / `to_string`. Implements `Eq` and `Appendable`. |
+| `Calendar` | Dates and date arithmetic: `Date`, `today`. Days, months, years; no time of day — use `Clock`. |
+| `Clock` | Timestamps and monotonic timing: `Instant`, `now`. Sub-second precision; the bridge to wall-clock time. |
+| `Show` | Renders a value the way Jade writes it: `show(Just(7))` is `"Just(7)"`, `show(Point(3, 4))` is `"Point { x: 3, y: 4 }"`. Instances for the primitives; derives for unions, structs, records and lists. A function shows as `<function>`, and `Never` raises — it has no values. |
+| `Debug` | `log(label, value)` prints `label: value` to stderr and returns the value untouched, so it drops into a pipeline. Unconstrained, unlike `Show`. |
+| `Decimal` | Exact base-10 decimals (`coefficient * 10 ^ exponent`) — money and rates without `Float` rounding. Opaque; build with `of` / `scaled` / `parse`. Arithmetic via `Numeric` (`+` `-` `*` `/`), plus `div` (scaled, half-up), `round`, `to_i`, `to_float`. JSON-encodes to a `<mantissa>e<exponent>` string. |
+
+Stdlib operations compile inline rather than through a runtime dispatch layer,
+so the generated Ruby calls the underlying operation directly.