eyeling 1.13.7 → 1.14.0

package/HANDBOOK.md

@@ -1516,6 +1516,41 @@ A tiny `sprintf` subset:
 - Any other specifier (`%d`, `%f`, …) causes the builtin to fail.
 - Missing arguments are treated as empty strings.
 
+### Length and character utilities (Eyeling extensions)
+
+Eyeling also implements a few **non-standard** `string:` helpers that are handy for string-based algorithms. These are **not** part of the SWAP builtin set, so treat them as Eyeling extensions.
+
+#### `string:length`
+
+**Shape:** `s string:length n`
+
+Casts `s` to a string and returns its length as an integer literal token.
+
+#### `string:charAt`
+
+**Shape:** `( s i ) string:charAt ch`
+
+- `i` is a numeric term, truncated to an integer.
+- Indexing is **0-based** (like JavaScript).
+- If `i` is out of range, `ch` is the empty string `""`.
+
+#### `string:setCharAt`
+
+**Shape:** `( s i ch ) string:setCharAt out`
+
+Returns a copy of `s` with the character at index `i` (0-based) replaced by:
+
+- the **first character** of `ch` if `ch` is non-empty, otherwise
+- the empty string.
+
+If `i` is out of range, `out` is the original string.
+
+#### `string:hammingDistance`
+
+**Shape:** `( a b ) string:hammingDistance d`
+
+Returns the number of differing positions between `a` and `b`. Fails if the two strings have different lengths.
+
 ### Containment and prefix/suffix tests
 
 - `string:contains`
@@ -1941,6 +1976,24 @@ References:
 
 If you are running untrusted inputs, consider `--super-restricted` to disable all builtins except implication.
 
+### Eyeling fast-path builtins
+
+Eyeling ships one optional fast-path builtins builtin e.g. used by the genetic-algorithm example:
+
+#### `urn:eyeling:ga:solveString`
+
+**Shape:** `( target mutationProbability samples seed traceEvery maxGenerations ) urn:eyeling:ga:solveString ( generation score value seed )`
+
+- `target` and `value` are `xsd:string` literals.
+- `mutationProbability` is interpreted as a percentage per character (0–100).
+- `traceEvery` controls debug tracing:
+  - `0` disables tracing,
+  - `1` traces every generation,
+  - `N` traces every `N` generations.
+- `maxGenerations` is a safety cap:
+  - `0` means unlimited,
+  - otherwise the builtin stops once `generation >= maxGenerations` (even if not solved).
+
 ### A.6 Skolemization and `log:skolem`
 
 When forward rule heads contain blank nodes (existentials), Eyeling replaces them with generated Skolem IRIs so derived facts are ground.

package/examples/genetic-algorithm.n3

@@ -0,0 +1,63 @@
+# ==========================================================================================
+# Genetic algorithm demo
+#
+# Genetic algorithm (GA) in a nutshell:
+# - Start with a random candidate string of the same length as the target.
+# - Repeatedly create a batch of “children” by copying the current best string and randomly
+#   mutating each character with a small probability.
+# - Score each child by how many positions differ from the target (Hamming distance).
+# - Keep the best-scoring child as the new current string and iterate until the score is 0.
+# This is a simple hill-climbing GA (selection + mutation, no crossover), using a seeded RNG
+# so runs are reproducible.
+#
+# Uses Eyeling's builtin:
+#   urn:eyeling:ga:solveString
+#
+# Configure:
+#   :mutationProbability 5   # percent per character
+#   :samples 80
+#   :seed 100
+#   :traceEvery 0            # 0=off, 1=every generation, 100=every 100 generations
+#   :maxGenerations 0        # 0=unlimited
+# ==========================================================================================
+
+@prefix :       <http://example.org/ga-solve#>.
+@prefix ega:    <urn:eyeling:ga:>.
+@prefix log:    <http://www.w3.org/2000/10/swap/log#>.
+@prefix string: <http://www.w3.org/2000/10/swap/string#>.
+
+:cfg
+  :mutationProbability 5;
+  :samples 80;
+  :seed 100;
+  :traceEvery 1;
+  :maxGenerations 0.
+
+# solveResult(TargetString) = (generation score value seed)
+{ ?TargetString :solveResult ( ?Gen ?Score ?Value ?Seed ) } <= {
+  :cfg :mutationProbability ?MutProb;
+       :samples ?Samples;
+       :seed ?Seed;
+       :traceEvery ?TraceEvery;
+       :maxGenerations ?MaxG.
+
+  ( ?TargetString ?MutProb ?Samples ?Seed ?TraceEvery ?MaxG )
+    ega:solveString
+  ( ?Gen ?Score ?Value ?SeedOut ) .
+
+  # By design, the 4th output is the (input) seed.
+  ?SeedOut log:equalTo ?Seed
+}.
+
+# Boolean-ish API for querying success
+{ ?TargetString :solved true } <= {
+  ?TargetString :solveResult ( ?Gen 0 ?TargetString ?Seed )
+}.
+
+# --------------------------------------------------------
+# Requested output: solve('METHINKS IT IS LIKE A WEASEL').
+# --------------------------------------------------------
+
+{ "METHINKS IT IS LIKE A WEASEL" :solved true .
+  ( "solve('%s').\n" "METHINKS IT IS LIKE A WEASEL" ) string:format ?Line
+} => { 1 log:outputString ?Line }.

package/examples/output/genetic-algorithm.n3

@@ -0,0 +1,3 @@
+@prefix log: <http://www.w3.org/2000/10/swap/log#> .
+
+1 log:outputString "solve('METHINKS IT IS LIKE A WEASEL').\n" .

package/eyeling-builtins.ttl

@@ -5,6 +5,7 @@
 @prefix list: <http://www.w3.org/2000/10/swap/list#> .
 @prefix log: <http://www.w3.org/2000/10/swap/log#> .
 @prefix string: <http://www.w3.org/2000/10/swap/string#> .
+@prefix ega: <urn:eyeling:ga:> .
 @prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
 @prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
 @prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
@@ -333,3 +334,19 @@ string:scrape a ex:Builtin ; ex:kind ex:Function ;
 string:format a ex:Builtin ; ex:kind ex:Function ;
   rdfs:comment "Simple formatter: (fmt arg1 ... argN) -> output string. Only %s and %% are supported; other specifiers fail." .
 
+string:length a ex:Builtin ; ex:kind ex:Function ;
+  rdfs:comment "Function: binds/unifies object with the character length of the subject after string-casting. Output is an integer literal token." .
+
+string:charAt a ex:Builtin ; ex:kind ex:Function ;
+  rdfs:comment "Function: subject is a 2-item list (string idx). Binds/unifies object with the 1-character string at 0-based idx; out-of-range yields the empty string." .
+
+string:setCharAt a ex:Builtin ; ex:kind ex:Function ;
+  rdfs:comment "Function: subject is a 3-item list (string idx ch). Returns a copy of the string with position idx (0-based) replaced by the first character of ch; out-of-range returns the original string." .
+
+string:hammingDistance a ex:Builtin ; ex:kind ex:Function ;
+  rdfs:comment "Function: subject is a 2-item list (a b). Binds/unifies object with the number of differing positions (Hamming distance). Fails if lengths differ." .
+
+# --- eyeling fast path builtins ------------------------------
+
+ega:solveString a ex:Builtin ; ex:kind ex:Function ;
+  rdfs:comment "Eyeling extension: GA solver on strings. Subject list: (target mutationProbability samples seed traceEvery maxGenerations). Object list: (generation score value seed). traceEvery=0 disables tracing; maxGenerations=0 means unlimited." .

package/eyeling.js

@@ -3463,6 +3463,209 @@ function evalBuiltin(goal, subst, facts, backRules, depth, varGen, maxResults) {
     return sStr.startsWith(oStr) ? [{ ...subst }] : [];
   }
 
+  // -----------------------------------------------------------------
+  // 4.6.1 extended string: builtins (Eyeling extensions)
+  // -----------------------------------------------------------------
+
+  // string:length
+  // Schema: $s+ string:length $o?
+  // $o is an integer literal (untyped numeric token).
+  if (pv === STRING_NS + 'length') {
+    const sStr = termToJsString(g.s);
+    if (sStr === null) return [];
+    const lit = internLiteral(String(sStr.length));
+    if (g.o instanceof Var) {
+      const s2 = { ...subst };
+      s2[g.o.name] = lit;
+      return [s2];
+    }
+    const s2 = unifyTerm(g.o, lit, subst);
+    return s2 !== null ? [s2] : [];
+  }
+
+  // string:charAt
+  // Schema: ( $str $idx ) string:charAt $ch
+  // $ch is a (possibly empty) string literal.
+  if (pv === STRING_NS + 'charAt') {
+    if (!(g.s instanceof ListTerm) || g.s.elems.length !== 2) return [];
+    const sStr = termToJsString(g.s.elems[0]);
+    const idxNum = parseNum(g.s.elems[1]);
+    if (sStr === null || idxNum === null) return [];
+    const idx = Math.trunc(idxNum);
+    const ch = idx < 0 || idx >= sStr.length ? '' : sStr.charAt(idx);
+    const lit = makeStringLiteral(ch);
+    if (g.o instanceof Var) {
+      const s2 = { ...subst };
+      s2[g.o.name] = lit;
+      return [s2];
+    }
+    const s2 = unifyTerm(g.o, lit, subst);
+    return s2 !== null ? [s2] : [];
+  }
+
+  // string:setCharAt
+  // Schema: ( $str $idx $ch ) string:setCharAt $out
+  // If idx out of range, returns the original string.
+  if (pv === STRING_NS + 'setCharAt') {
+    if (!(g.s instanceof ListTerm) || g.s.elems.length !== 3) return [];
+    const sStr = termToJsString(g.s.elems[0]);
+    const idxNum = parseNum(g.s.elems[1]);
+    const chStr = termToJsString(g.s.elems[2]);
+    if (sStr === null || idxNum === null || chStr === null) return [];
+    const idx = Math.trunc(idxNum);
+    const rep = chStr.length ? chStr[0] : '';
+    let out = sStr;
+    if (idx >= 0 && idx < sStr.length) out = sStr.slice(0, idx) + rep + sStr.slice(idx + 1);
+    const lit = makeStringLiteral(out);
+    if (g.o instanceof Var) {
+      const s2 = { ...subst };
+      s2[g.o.name] = lit;
+      return [s2];
+    }
+    const s2 = unifyTerm(g.o, lit, subst);
+    return s2 !== null ? [s2] : [];
+  }
+
+  // string:hammingDistance
+  // Schema: ( $a $b ) string:hammingDistance $d
+  // Fails if strings have different length.
+  if (pv === STRING_NS + 'hammingDistance') {
+    if (!(g.s instanceof ListTerm) || g.s.elems.length !== 2) return [];
+    const a = termToJsString(g.s.elems[0]);
+    const b = termToJsString(g.s.elems[1]);
+    if (a === null || b === null) return [];
+    if (a.length !== b.length) return [];
+    let diffs = 0;
+    for (let i = 0; i < a.length; i++) if (a[i] !== b[i]) diffs++;
+    const lit = internLiteral(String(diffs));
+    if (g.o instanceof Var) {
+      const s2 = { ...subst };
+      s2[g.o.name] = lit;
+      return [s2];
+    }
+    const s2 = unifyTerm(g.o, lit, subst);
+    return s2 !== null ? [s2] : [];
+  }
+
+  // -----------------------------------------------------------------
+  // 4.6.2 urn:eyeling:ga: builtins (fast GA on *strings*)
+  // -----------------------------------------------------------------
+
+  // urn:eyeling:ga:solveString
+  // Schema: ( $target $mutProb $samples $seed $traceEvery $maxGenerations ) :solveString ( $gen $score $value $seed )
+  // Side effect: if traceEvery > 0, prints: <gen> TRACE (<score> "<value>")
+  if (pv === 'urn:eyeling:ga:solveString') {
+    if (!(g.s instanceof ListTerm) || g.s.elems.length != 6) return [];
+
+    const target = termToJsXsdStringNoLang(g.s.elems[0]);
+    const mutProbNum = parseNum(g.s.elems[1]);
+    const samplesNum = parseNum(g.s.elems[2]);
+    const seedNum = parseNum(g.s.elems[3]);
+    const traceEveryNum = parseNum(g.s.elems[4]);
+    const maxGenNum = parseNum(g.s.elems[5]);
+
+    if (target === null || mutProbNum === null || samplesNum === null || seedNum === null) return [];
+    if (traceEveryNum === null || maxGenNum === null) return [];
+
+    const mutProb = Math.max(0, Math.trunc(mutProbNum));
+    const samples = Math.max(1, Math.trunc(samplesNum));
+    const seed0 = Math.trunc(seedNum);
+
+    const traceEvery = Math.max(0, Math.trunc(traceEveryNum));
+    const maxGenerations = Math.max(0, Math.trunc(maxGenNum));
+
+    // Deterministic 31-bit LCG using BigInt arithmetic (matches the N3 version)
+    let state = BigInt(seed0);
+    const MOD = 2147483648n; // 2^31
+    const A = 1103515245n;
+    const C = 12345n;
+
+    function rnd() {
+      state = (A * state + C) % MOD;
+      return Number(state) / 2147483648;
+    }
+
+    function randRound(N) {
+      return Math.round(rnd() * N);
+    }
+
+    function randomAlpha() {
+      const p = randRound(26);
+      return p === 0 ? ' ' : String.fromCharCode(64 + p);
+    }
+
+    function randomText(len) {
+      let out = '';
+      for (let i = 0; i < len; i++) out += randomAlpha();
+      return out;
+    }
+
+    function mutate(str) {
+      let out = '';
+      for (let i = 0; i < str.length; i++) {
+        const p = randRound(100);
+        if (p > mutProb) out += str[i];
+        else out += randomAlpha();
+      }
+      return out;
+    }
+
+    function score(str) {
+      let diffs = 0;
+      for (let i = 0; i < target.length; i++) if (str[i] !== target[i]) diffs++;
+      return diffs;
+    }
+
+    const pref = trace.getTracePrefixes() || PrefixEnv.newDefault();
+    function doTrace(gen, sc, val) {
+      const genLit = internLiteral(String(gen));
+      const scLit = internLiteral(String(sc));
+      const valLit = makeStringLiteral(val);
+      const obj = new ListTerm([scLit, valLit]);
+      const xStr = termToN3(genLit, pref);
+      const yStr = termToN3(obj, pref);
+      trace.writeTraceLine(`${xStr} TRACE ${yStr}`);
+    }
+
+    let generation = 0;
+    let current = randomText(target.length);
+    let currentScore = score(current);
+
+    if (traceEvery > 0 && generation % traceEvery === 0) doTrace(generation, currentScore, current);
+
+    while (currentScore !== 0) {
+      if (maxGenerations > 0 && generation >= maxGenerations) break;
+
+      let best = '';
+      let bestScore = Infinity;
+
+      for (let i = 0; i < samples; i++) {
+        const cand = mutate(current);
+        const candScore = score(cand);
+        if (candScore < bestScore) {
+          best = cand;
+          bestScore = candScore;
+        }
+      }
+
+      generation += 1;
+      current = best;
+      currentScore = bestScore;
+
+      if (traceEvery > 0 && generation % traceEvery === 0) doTrace(generation, currentScore, current);
+    }
+
+    const outList = new ListTerm([
+      internLiteral(String(generation)),
+      internLiteral(String(currentScore)),
+      makeStringLiteral(current),
+      internLiteral(String(seed0)),
+    ]);
+
+    const s2 = unifyTerm(g.o, outList, subst);
+    return s2 !== null ? [s2] : [];
+  }
+
   // Unknown builtin
   return [];
 }
@@ -3483,6 +3686,11 @@ function isBuiltinPred(p) {
     return true;
   }
 
+  // Eyeling extension: GA demo builtins
+  if (v === 'urn:eyeling:ga:solveString') {
+    return true;
+  }
+
   return (
     v.startsWith(CRYPTO_NS) ||
     v.startsWith(MATH_NS) ||

package/lib/builtins.js

@@ -3451,6 +3451,209 @@ function evalBuiltin(goal, subst, facts, backRules, depth, varGen, maxResults) {
     return sStr.startsWith(oStr) ? [{ ...subst }] : [];
   }
 
+  // -----------------------------------------------------------------
+  // 4.6.1 extended string: builtins (Eyeling extensions)
+  // -----------------------------------------------------------------
+
+  // string:length
+  // Schema: $s+ string:length $o?
+  // $o is an integer literal (untyped numeric token).
+  if (pv === STRING_NS + 'length') {
+    const sStr = termToJsString(g.s);
+    if (sStr === null) return [];
+    const lit = internLiteral(String(sStr.length));
+    if (g.o instanceof Var) {
+      const s2 = { ...subst };
+      s2[g.o.name] = lit;
+      return [s2];
+    }
+    const s2 = unifyTerm(g.o, lit, subst);
+    return s2 !== null ? [s2] : [];
+  }
+
+  // string:charAt
+  // Schema: ( $str $idx ) string:charAt $ch
+  // $ch is a (possibly empty) string literal.
+  if (pv === STRING_NS + 'charAt') {
+    if (!(g.s instanceof ListTerm) || g.s.elems.length !== 2) return [];
+    const sStr = termToJsString(g.s.elems[0]);
+    const idxNum = parseNum(g.s.elems[1]);
+    if (sStr === null || idxNum === null) return [];
+    const idx = Math.trunc(idxNum);
+    const ch = idx < 0 || idx >= sStr.length ? '' : sStr.charAt(idx);
+    const lit = makeStringLiteral(ch);
+    if (g.o instanceof Var) {
+      const s2 = { ...subst };
+      s2[g.o.name] = lit;
+      return [s2];
+    }
+    const s2 = unifyTerm(g.o, lit, subst);
+    return s2 !== null ? [s2] : [];
+  }
+
+  // string:setCharAt
+  // Schema: ( $str $idx $ch ) string:setCharAt $out
+  // If idx out of range, returns the original string.
+  if (pv === STRING_NS + 'setCharAt') {
+    if (!(g.s instanceof ListTerm) || g.s.elems.length !== 3) return [];
+    const sStr = termToJsString(g.s.elems[0]);
+    const idxNum = parseNum(g.s.elems[1]);
+    const chStr = termToJsString(g.s.elems[2]);
+    if (sStr === null || idxNum === null || chStr === null) return [];
+    const idx = Math.trunc(idxNum);
+    const rep = chStr.length ? chStr[0] : '';
+    let out = sStr;
+    if (idx >= 0 && idx < sStr.length) out = sStr.slice(0, idx) + rep + sStr.slice(idx + 1);
+    const lit = makeStringLiteral(out);
+    if (g.o instanceof Var) {
+      const s2 = { ...subst };
+      s2[g.o.name] = lit;
+      return [s2];
+    }
+    const s2 = unifyTerm(g.o, lit, subst);
+    return s2 !== null ? [s2] : [];
+  }
+
+  // string:hammingDistance
+  // Schema: ( $a $b ) string:hammingDistance $d
+  // Fails if strings have different length.
+  if (pv === STRING_NS + 'hammingDistance') {
+    if (!(g.s instanceof ListTerm) || g.s.elems.length !== 2) return [];
+    const a = termToJsString(g.s.elems[0]);
+    const b = termToJsString(g.s.elems[1]);
+    if (a === null || b === null) return [];
+    if (a.length !== b.length) return [];
+    let diffs = 0;
+    for (let i = 0; i < a.length; i++) if (a[i] !== b[i]) diffs++;
+    const lit = internLiteral(String(diffs));
+    if (g.o instanceof Var) {
+      const s2 = { ...subst };
+      s2[g.o.name] = lit;
+      return [s2];
+    }
+    const s2 = unifyTerm(g.o, lit, subst);
+    return s2 !== null ? [s2] : [];
+  }
+
+  // -----------------------------------------------------------------
+  // 4.6.2 urn:eyeling:ga: builtins (fast GA on *strings*)
+  // -----------------------------------------------------------------
+
+  // urn:eyeling:ga:solveString
+  // Schema: ( $target $mutProb $samples $seed $traceEvery $maxGenerations ) :solveString ( $gen $score $value $seed )
+  // Side effect: if traceEvery > 0, prints: <gen> TRACE (<score> "<value>")
+  if (pv === 'urn:eyeling:ga:solveString') {
+    if (!(g.s instanceof ListTerm) || g.s.elems.length != 6) return [];
+
+    const target = termToJsXsdStringNoLang(g.s.elems[0]);
+    const mutProbNum = parseNum(g.s.elems[1]);
+    const samplesNum = parseNum(g.s.elems[2]);
+    const seedNum = parseNum(g.s.elems[3]);
+    const traceEveryNum = parseNum(g.s.elems[4]);
+    const maxGenNum = parseNum(g.s.elems[5]);
+
+    if (target === null || mutProbNum === null || samplesNum === null || seedNum === null) return [];
+    if (traceEveryNum === null || maxGenNum === null) return [];
+
+    const mutProb = Math.max(0, Math.trunc(mutProbNum));
+    const samples = Math.max(1, Math.trunc(samplesNum));
+    const seed0 = Math.trunc(seedNum);
+
+    const traceEvery = Math.max(0, Math.trunc(traceEveryNum));
+    const maxGenerations = Math.max(0, Math.trunc(maxGenNum));
+
+    // Deterministic 31-bit LCG using BigInt arithmetic (matches the N3 version)
+    let state = BigInt(seed0);
+    const MOD = 2147483648n; // 2^31
+    const A = 1103515245n;
+    const C = 12345n;
+
+    function rnd() {
+      state = (A * state + C) % MOD;
+      return Number(state) / 2147483648;
+    }
+
+    function randRound(N) {
+      return Math.round(rnd() * N);
+    }
+
+    function randomAlpha() {
+      const p = randRound(26);
+      return p === 0 ? ' ' : String.fromCharCode(64 + p);
+    }
+
+    function randomText(len) {
+      let out = '';
+      for (let i = 0; i < len; i++) out += randomAlpha();
+      return out;
+    }
+
+    function mutate(str) {
+      let out = '';
+      for (let i = 0; i < str.length; i++) {
+        const p = randRound(100);
+        if (p > mutProb) out += str[i];
+        else out += randomAlpha();
+      }
+      return out;
+    }
+
+    function score(str) {
+      let diffs = 0;
+      for (let i = 0; i < target.length; i++) if (str[i] !== target[i]) diffs++;
+      return diffs;
+    }
+
+    const pref = trace.getTracePrefixes() || PrefixEnv.newDefault();
+    function doTrace(gen, sc, val) {
+      const genLit = internLiteral(String(gen));
+      const scLit = internLiteral(String(sc));
+      const valLit = makeStringLiteral(val);
+      const obj = new ListTerm([scLit, valLit]);
+      const xStr = termToN3(genLit, pref);
+      const yStr = termToN3(obj, pref);
+      trace.writeTraceLine(`${xStr} TRACE ${yStr}`);
+    }
+
+    let generation = 0;
+    let current = randomText(target.length);
+    let currentScore = score(current);
+
+    if (traceEvery > 0 && generation % traceEvery === 0) doTrace(generation, currentScore, current);
+
+    while (currentScore !== 0) {
+      if (maxGenerations > 0 && generation >= maxGenerations) break;
+
+      let best = '';
+      let bestScore = Infinity;
+
+      for (let i = 0; i < samples; i++) {
+        const cand = mutate(current);
+        const candScore = score(cand);
+        if (candScore < bestScore) {
+          best = cand;
+          bestScore = candScore;
+        }
+      }
+
+      generation += 1;
+      current = best;
+      currentScore = bestScore;
+
+      if (traceEvery > 0 && generation % traceEvery === 0) doTrace(generation, currentScore, current);
+    }
+
+    const outList = new ListTerm([
+      internLiteral(String(generation)),
+      internLiteral(String(currentScore)),
+      makeStringLiteral(current),
+      internLiteral(String(seed0)),
+    ]);
+
+    const s2 = unifyTerm(g.o, outList, subst);
+    return s2 !== null ? [s2] : [];
+  }
+
   // Unknown builtin
   return [];
 }
@@ -3471,6 +3674,11 @@ function isBuiltinPred(p) {
     return true;
   }
 
+  // Eyeling extension: GA demo builtins
+  if (v === 'urn:eyeling:ga:solveString') {
+    return true;
+  }
+
   return (
     v.startsWith(CRYPTO_NS) ||
     v.startsWith(MATH_NS) ||

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eyeling",
-  "version": "1.13.7",
+  "version": "1.14.0",
   "description": "A minimal Notation3 (N3) reasoner in JavaScript.",
   "main": "./index.js",
   "keywords": [