onejs-sl 0.1.4 → 0.1.6

package/src/lang/prelude-source.ts

@@ -0,0 +1,53 @@
+/**
+ * The prelude's source, and what an editor reads from it without parsing it.
+ *
+ * Kept out of `prelude.ts`, which parses it, so that `onejs-sl/tables` can offer
+ * the prelude's names and descriptions with no parser in the bundle. Each
+ * function's description is the comment above it, so there is one place to
+ * write it.
+ */
+
+export const PRELUDE_SOURCE = `
+// Rotate a point about the origin. Translate first if you want another centre.
+float2 rotate(float2 p, float angle) {
+    float c = cos(angle);
+    float s = sin(angle);
+    return float2(p.x * c - p.y * s, p.x * s + p.y * c);
+}
+
+// Cartesian to polar: x is the angle in radians, y is the radius.
+float2 polar(float2 p) {
+    return float2(atan2(p.y, p.x), length(p));
+}
+
+// Signed distance to a circle at the origin. Negative inside.
+float circle(float2 p, float r) {
+    return length(p) - r;
+}
+
+// Signed distance to an axis aligned box of the given half extents.
+float box(float2 p, float2 size) {
+    float2 d = abs(p) - size;
+    return length(max(d, 0)) + min(max(d.x, d.y), 0);
+}
+
+// Repeat a unit cell n times across the input, centred on zero in each cell.
+float2 tile(float2 p, float n) {
+    return frac(p * n) - 0.5;
+}
+
+// Inigo Quilez's cosine palette. Four float3s in, a colour out, no texture.
+float3 palette(float t, float3 a, float3 b, float3 c, float3 d) {
+    return a + b * cos(6.28318530718 * (c * t + d));
+}
+`
+
+/** Each prelude function's name, in the order the source declares them. */
+const DECLARED = /* @__PURE__ */ [...PRELUDE_SOURCE.matchAll(/^\/\/ (.+)\n\w+ (\w+)\(/gm)]
+
+export const PRELUDE_NAMES: ReadonlySet<string> = /* @__PURE__ */ new Set(DECLARED.map((m) => m[2]!))
+
+/** Each prelude function's one line description: the comment above it. */
+export const PRELUDE_DOCS: Readonly<Record<string, string>> = /* @__PURE__ */ Object.fromEntries(
+    DECLARED.map((m) => [m[2]!, m[1]!]),
+)

package/src/lang/prelude.ts

@@ -21,41 +21,9 @@
 import type { FuncDecl } from "./ast"
 import { check } from "./check"
 import { parseUnit } from "./parser"
+import { PRELUDE_SOURCE } from "./prelude-source"
 
-export const PRELUDE_SOURCE = `
-// Rotate a point about the origin. Translate first if you want another centre.
-float2 rotate(float2 p, float angle) {
-    float c = cos(angle);
-    float s = sin(angle);
-    return float2(p.x * c - p.y * s, p.x * s + p.y * c);
-}
-
-// Cartesian to polar: x is the angle in radians, y is the radius.
-float2 polar(float2 p) {
-    return float2(atan2(p.y, p.x), length(p));
-}
-
-// Signed distance to a circle at the origin. Negative inside.
-float circle(float2 p, float r) {
-    return length(p) - r;
-}
-
-// Signed distance to an axis aligned box of the given half extents.
-float box(float2 p, float2 size) {
-    float2 d = abs(p) - size;
-    return length(max(d, 0)) + min(max(d.x, d.y), 0);
-}
-
-// Repeat a unit cell n times across the input, centred on zero in each cell.
-float2 tile(float2 p, float n) {
-    return frac(p * n) - 0.5;
-}
-
-// Inigo Quilez's cosine palette. Four float3s in, a colour out, no texture.
-float3 palette(float t, float3 a, float3 b, float3 c, float3 d) {
-    return a + b * cos(6.28318530718 * (c * t + d));
-}
-`
+export { PRELUDE_SOURCE }
 
 let cached: FuncDecl[] | null = null
 

package/src/lang/words.ts

@@ -0,0 +1,23 @@
+/**
+ * The words the parser reads as syntax, and the value types.
+ *
+ * One list, read by the parser (a name may not be one of these) and by
+ * `classify` (these highlight as keywords and types), so an editor that
+ * highlights with it agrees with the parser by construction rather than by a
+ * list it keeps in step by hand.
+ */
+
+import { TYPE_WIDTH, type TypeName } from "./ast"
+
+/**
+ * Declaration and statement words. `int` is here rather than among the types
+ * because it is only ever a for loop's counter, `for (int i = 0; i < 4; i++)`;
+ * a value cannot be declared as one.
+ */
+export const SL_KEYWORDS = ["uniform", "texture2D", "const", "if", "else", "for", "return", "int"] as const
+
+/** The types a value, a uniform or a function can have. */
+export const SL_TYPES = Object.keys(TYPE_WIDTH) as readonly TypeName[]
+
+export const KEYWORD_SET: ReadonlySet<string> = new Set(SL_KEYWORDS)
+export const TYPE_SET: ReadonlySet<string> = new Set(SL_TYPES)

package/src/params.ts

@@ -20,6 +20,7 @@ import { BUILTINS } from "./lang/builtins"
 import { LIB_FUNCTIONS, SDF_CALLS } from "./lib/table"
 import { LIB_PARAM_NAMES } from "./lib/names"
 import { SL_SDF_PARAMS, SL_SDF_SHAPES, type SlSdfKind } from "./shapes"
+import type { InputName } from "./ir"
 
 /** One function of the helper library, as its source declares it. */
 export interface LibSignature {
@@ -111,3 +112,63 @@ function shapeNames(): Record<SlSdfKind, readonly string[]> {
     }
     return out
 }
+
+/**
+ * One line on what each builtin does, for a completion's tooltip and the docs
+ * page: the other half of `BUILTIN_PARAMS`, and named in its words, so a line
+ * can say `s` and mean the third argument.
+ */
+export const BUILTIN_DOCS: Readonly<Record<string, string>> = {
+    sin: "The sine of x, in radians.",
+    cos: "The cosine of x, in radians.",
+    tan: "The tangent of x, in radians.",
+    asin: "The angle whose sine is x, with x clamped to -1 to 1.",
+    acos: "The angle whose cosine is x, with x clamped to -1 to 1.",
+    exp: "e raised to the power x.",
+    log: "The natural logarithm of x.",
+    sqrt: "The square root of x.",
+    sign: "-1, 0 or 1, by the sign of x.",
+    ceil: "x rounded up to a whole number.",
+    round: "x rounded to the nearest whole number.",
+    toLinear: "A colour as written, in sRGB, converted to the space the target holds; alpha is left alone.",
+    abs: "x without its sign.",
+    floor: "x rounded down to a whole number.",
+    frac: "The part of x after the decimal point, 0 up to 1.",
+    saturate: "x clamped to 0 to 1.",
+    rcp: "1 / x.",
+    normalize: "x scaled to length 1.",
+    pow: "x raised to the power y.",
+    min: "The smaller of x and y, per component.",
+    max: "The larger of x and y, per component.",
+    clamp: "x held between min and max.",
+    atan2: "The angle of the point (x, y) from the positive x axis, in radians.",
+    length: "The length of the vector x.",
+    distance: "The distance between the points x and y.",
+    dot: "The dot product of x and y.",
+    cross: "The cross product of two float3s.",
+    reflect: "The direction i reflected off a surface with normal n.",
+    lerp: "Mixes x into y by s: x at 0, y at 1.",
+    step: "0 where x is below y, else 1.",
+    smoothstep: "0 below min, 1 above max, and a smooth curve between.",
+    remap: "v moved from the range fromMin to fromMax into the range toMin to toMax.",
+    hsv2rgb: "A colour from hue, saturation and value, each 0 to 1.",
+    luminance: "How bright a colour looks, as one number.",
+    noise: "Smooth value noise at p, about 0 to 1. Offset p for a different field.",
+    simplex: "Simplex noise at p, about 0 to 1, with no grid pattern.",
+    voronoi: "The distance from p to the nearest point of a jittered grid: cells.",
+    fbm: "Value noise layered in octaves, 1 to 4 (3 when left out): clouds and terrain.",
+    turbulence: "Simplex creases layered in octaves, 1 to 4: fire, smoke, marble.",
+    ridged: "Turbulence made bright at its creases: ridges, lightning, cracks.",
+    tex2D: "The colour of texture s at the uv t, with straight alpha.",
+    sdf: "The signed distance from p to a shape, negative inside: `sdf.circle(p, r)`.",
+    ramp: "t mapped through evenly spaced colour stops, from the first at 0 to the last at 1.",
+}
+
+/** One line on each input, for the same tooltips. */
+export const INPUT_DOCS: Readonly<Record<InputName, string>> = {
+    uv: "Where this pixel is in the element, 0 to 1 on each axis, with y up.",
+    fragCoord: "Where this pixel is in the element, in pixels, with y up.",
+    resolution: "The element's size in pixels.",
+    time: "Seconds since the effect started.",
+    aspect: "The element's width divided by its height.",
+}

package/src/tables.ts

@@ -2,8 +2,10 @@
  * `onejs-sl/tables`: what completion and highlighting read.
  *
  * The same tables the checker and the emitters use, so an editor offers
- * exactly the builtins that compile, with the arities they take and the names
- * of their parameters (`params.ts`), and the helper library's signatures.
+ * exactly the builtins that compile, with the arities they take, the names of
+ * their parameters and a line on each (`params.ts`), the words the parser
+ * reads as syntax, and the helper library's signatures. `classify`, in the
+ * main entry, is the highlighter built on the same lists.
  */
 export { BUILTINS, NOT_YET } from "./lang/builtins"
 export type { Builtin } from "./lang/builtins"
@@ -13,6 +15,10 @@ export {
 export type { SLSurface } from "./ops"
 export { INPUTS } from "./ir"
 export { SL_SDF_SHAPES, SL_SDF_PARAMS } from "./shapes"
-export { BUILTIN_PARAMS, LIB_SIGNATURES, SL_SDF_PARAM_NAMES } from "./params"
+export { BUILTIN_DOCS, BUILTIN_PARAMS, INPUT_DOCS, LIB_SIGNATURES, SL_SDF_PARAM_NAMES } from "./params"
+export { PRELUDE_DOCS, PRELUDE_NAMES } from "./lang/prelude-source"
+export { SL_KEYWORDS, SL_TYPES } from "./lang/words"
+export { TYPE_WIDTH } from "./lang/ast"
+export type { TypeName } from "./lang/ast"
 export type { LibSignature } from "./params"
 export type { SlSdfKind } from "./shapes"