lineputscript 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 YIYuNCU
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,347 @@
+# LinePutScript
+
+TypeScript SDK for the LinePutScript (LPS) data format — a text-based hierarchical key-value storage format.
+
+LPS is a simple, human-readable structured data format used by the [VPet](https://github.com/LorisYounger/VPet) virtual pet simulator and other applications. It represents nested key-value pairs, typed values, multi-line text, and comments in a compact line-oriented syntax.
+
+## Installation
+
+```bash
+npm install lineputscript
+```
+
+Requires Node.js >= 18.
+
+## LPS Format Overview
+
+A LinePutScript document consists of **Lines**, each containing an optional **Info** value, zero or more **Subs** (nested key-value pairs), and optional **Text** content.
+
+```
+Name#Info:||Sub1#Val1:||Sub2#Val2:||TextContent
+```
+
+- `#` separates the line name from its info value
+- `:|` separates subs within a line, and precedes the text content
+- Subs have the same `Name#Value` structure as lines
+- Lines are separated by newlines
+
+### Example
+
+```
+note#greeting:|sub#hello:|world
+config#settings:|timeout#30:|enabled#true:|production
+```
+
+This document has two lines:
+- `note` with info `greeting`, one sub (`sub` = `hello`), and text `world`
+- `config` with info `settings`, two subs (`timeout` = `30`, `enabled` = `true`), and text `production`
+
+### Escape Sequences
+
+Characters with special meaning in LPS are escaped in storage and unescaped on display:
+
+| Character | Stored As |
+|-----------|-----------|
+| `\|` | `/\|` |
+| `/` | `/!` |
+| `:\|` | `/stop` |
+| `\t` | `/tab` |
+| `\n` | `/n` |
+| `\r` | `/r` |
+| `#` | `/id` |
+| `,` | `/com` |
+
+Use `textReplace()` to convert display text → storage format, and `textDeReplace()` to convert storage → display format.
+
+## Quick Start
+
+```typescript
+import { LPS, Line, Sub } from 'lineputscript';
+
+// Parse a document
+const doc = new LPS(`name#value:|subkey#subval:|extra text`);
+
+// Read values
+const line = doc.findLine('name');
+console.log(line?.infoDisplay); // 'value'
+console.log(line?.textDisplay); // 'extra text'
+console.log(line?.find('subkey')?.infoDisplay); // 'subval'
+
+// Typed access
+doc.setLineInt('count', 42);
+console.log(doc.getLineInt('count')); // 42
+
+doc.setLineBool('flag', true);
+console.log(doc.getLineBool('flag')); // true
+
+// Modify
+const vupmod = doc.findorAddLine('vupmod');
+vupmod.findorAdd('author').infoDisplay = 'LorisYounger';
+
+// Serialize back to string
+const output = doc.toString();
+```
+
+## API Reference
+
+### `Sub`
+
+The base unit — a named value pair.
+
+```typescript
+new Sub()                           // Empty sub
+new Sub('name#value')               // Parse from LPS string
+new Sub('name', 'value')            // Name + info
+new Sub('tags', 'a', 'b', 'c')      // Multiple infos (comma-joined, escape-aware)
+
+// Properties
+sub.name               // string
+sub.info               // Raw storage-escaped info string
+sub.infoDisplay        // Display-unescaped info string
+sub.infoToInt          // number
+sub.infoToInt64        // bigint
+sub.infoToDouble       // number
+sub.infoToBoolean      // boolean
+sub.infos              // StringStructure (comma-separated values as key-value pairs)
+
+// Methods
+sub.getString()        // Display-unescaped string
+sub.getInteger()       // Parse as int
+sub.getInteger64()     // Parse as bigint
+sub.getDouble()        // Parse as float
+sub.getBoolean()       // Parse as bool ('true'/'t'/'1' → true)
+sub.getDateTime()      // Parse as Date (.NET ticks or ISO string)
+sub.getFloat()         // Parse as FInt64
+sub.setString(val)     // Set from display string (auto-escapes)
+sub.setInteger(val)    // Set from number
+sub.setInteger64(val)  // Set from bigint
+sub.setDouble(val)     // Set from number
+sub.setBoolean(val)    // Set from boolean
+sub.setDateTime(val)   // Set from Date (.NET ticks)
+sub.setFloat(val)      // Set from FInt64
+sub.getInfos()         // Get comma-separated values as string[]
+sub.first()            // First comma-separated value or null
+sub.last()             // Last comma-separated value or null
+sub.load(lpsString)    // Parse from LPS string
+sub.set(other)         // Copy from another ISub
+sub.toString()         // Serialize to 'name#info:|' format
+```
+
+### `Line` (extends `Sub`)
+
+A Sub with child subs, text content, and comments.
+
+```typescript
+new Line()                              // Empty line
+new Line('name#info:||sub#val:||text')  // Parse from LPS string
+new Line('name', 'info', 'text', [sub1, sub2])
+
+// Properties (in addition to Sub)
+line.text          // Raw storage-escaped text
+line.textDisplay   // Display-unescaped text
+line.textToInt     // number
+line.textToInt64   // bigint
+line.textToDouble  // number
+line.comments      // String after /// marker
+line.texts         // StringStructure over text content
+line.subs          // ISub[] — ordered list of child subs
+
+// Sub management
+line.addSub(sub)
+line.addorReplaceSub(sub)
+line.addRange([sub1, sub2])
+line.insertSub(index, sub)
+line.remove(sub)           // boolean
+line.removeByName(name)    // boolean
+line.removeAll(name)
+line.removeAt(index)
+line.contains(sub)         // boolean
+line.containsByName(name)  // boolean
+line.find(name)            // ISub | null
+line.find(name, info)      // ISub | null (match name + info)
+line.findInfo(info)        // ISub | null (match info only)
+line.findAll(name)         // ISub[]
+line.findorAdd(name)       // Find existing or create new
+line.search(value)         // ISub | null (substring match on name)
+line.searchAll(value)      // ISub[] (substring match on name)
+line.indexOf(name)         // number
+line.indexsOf(name)        // number[] (all indices)
+
+// Typed shorthands on subs (find-or-create, then get/set typed value)
+line.getSubBool(name)         // boolean
+line.setSubBool(name, val)
+line.getSubInt(name, default?)   // number
+line.setSubInt(name, val)
+line.getSubInt64(name, default?) // bigint
+line.setSubInt64(name, val)
+line.getSubDouble(name, default?) // number
+line.setSubDouble(name, val)
+line.getSubString(name, default?) // string | null
+line.setSubString(name, val)
+line.getSubFloat(name, default?)  // FInt64
+line.setSubFloat(name, val)
+line.getSubDateTime(name, default?) // Date | null
+line.setSubDateTime(name, val)
+```
+
+### `LineDict` (extends `Sub`)
+
+Same interface as `Line` but backed by a `Map<string, ISub>` for unique-name fast O(1) lookup. When duplicate names are added, the last one wins.
+
+### `LPS` / `LpsDocument`
+
+A document containing an ordered collection of lines.
+
+```typescript
+new LPS()                        // Empty document
+new LPS(lpsString)               // Parse from LPS string
+new LPS([line1, line2])          // From array of lines
+
+// Properties
+doc.assemblage      // ILine[]
+doc.count           // number of lines
+doc.length          // Estimated serialized byte length
+
+// Line management
+doc.addLine(line)
+doc.addorReplaceLine(line)
+doc.addRange([line1, line2])
+doc.insertLine(index, line)
+doc.remove(line)             // boolean (by reference or name)
+doc.removeAll(target)        // by reference or name
+doc.removeAt(index)
+doc.contains(line)           // boolean (line or sub)
+doc.containsLine(name)       // boolean
+doc.containsSub(name)        // boolean
+
+// Querying
+doc.findLine(name)           // ILine | null
+doc.findLine(name, info)     // ILine | null (match name + info)
+doc.findLineInfo(info)       // ILine | null
+doc.findorAddLine(name)      // Find existing or create new
+doc.findAllLine(name)        // ILine[]
+doc.findAllLineInfo(info)    // ILine[]
+
+// Cross-line sub search
+doc.findSub(name)            // ISub | null (first match across all lines)
+doc.findSub(name, info)      // ISub | null
+doc.findSubInfo(info)        // ISub | null
+doc.findAllSub(name)         // ISub[]
+
+// Text search (substring match on name)
+doc.searchLine(value)        // ILine | null
+doc.searchAllLine(value)     // ILine[]
+doc.searchSub(value)         // ISub | null
+doc.searchAllSub(value)      // ISub[]
+
+doc.indexOf(name)            // number
+doc.first()                  // ILine | null
+doc.last()                   // ILine | null
+doc.load(lpsString)          // Parse/replace content
+doc.toString()               // Serialize to LPS string
+
+// Typed shorthands on lines (find-or-add-line, then get/set typed info)
+doc.getLineBool(name)
+doc.setLineBool(name, val)
+doc.getLineInt(name, default?)
+doc.setLineInt(name, val)
+doc.getLineInt64(name, default?)
+doc.setLineInt64(name, val)
+doc.getLineDouble(name, default?)
+doc.setLineDouble(name, val)
+doc.getLineString(name, default?)
+doc.setLineString(name, val)
+doc.getLineFloat(name, default?)
+doc.setLineFloat(name, val)
+doc.getLineDateTime(name, default?)
+doc.setLineDateTime(name, val)
+```
+
+#### `LpsDocument` extends `LPS` — adds cursor operations
+
+```typescript
+const doc = new LpsDocument(lpsString);
+
+doc.readNext()       // ILine | null — reads and advances cursor
+doc.read()           // ILine | null — reads without advancing
+doc.append(line)     // Inserts line after current cursor position
+doc.append(name, info, text, ...subs)  // Create and insert
+doc.appendSub(...subs)      // Add subs to current line
+doc.appendSubByName(name, info)
+doc.readReset()      // Reset cursor to start
+doc.readEnd()        // Move cursor past end
+doc.readCanNext()    // boolean
+doc.lineNode         // get/set cursor position (0-based, clamped)
+```
+
+### `StringStructure`
+
+A dictionary view over a string encoded as `/n`-delimited `key=value` pairs, with caching.
+
+```typescript
+const ss = new StringStructure(
+  (val) => { /* setter — called when cache flushes */ },
+  () => /* getter — returns raw string */
+);
+
+ss.setString('key', 'value')
+ss.getString('key')           // string | null
+ss.getBool('key')             // boolean
+ss.setBool('key', true)
+ss.getInt('key', default?)    // number
+ss.setInt('key', 42)
+ss.getInt64('key')            // bigint
+ss.getDouble('key')           // number
+ss.getFloat('key')            // FInt64
+ss.getDateTime('key')         // Date | null
+ss.containsKey('key')         // boolean
+ss.remove('key')              // boolean
+ss.clear()
+ss.keys, ss.values, ss.count
+ss[Symbol.iterator]()         // Iterate [key, value] pairs
+```
+
+### `FInt64`
+
+Fixed-precision 64-bit decimal using `bigint` internally (Anchor = 1e9). Provides exact decimal arithmetic without floating-point rounding errors.
+
+```typescript
+FInt64.fromInt(42)             // Integer → FInt64
+FInt64.fromDouble(3.14)        // Double → FInt64
+FInt64.fromLong(1000000000n)   // Raw bigint
+FInt64.parse('3.14')           // Parse string
+
+a.add(b)            // a + b
+a.sub(b)            // a - b
+a.mul(b)            // a * b
+a.div(b)            // a / b
+a.compareTo(b)      // -1, 0, or 1
+a.equals(b)         // boolean
+a.toDouble()        // number
+a.toInt32()         // number (truncated)
+a.toInt64()         // bigint (truncated)
+
+FInt64.Zero, FInt64.One, FInt64.NaN
+FInt64.MinValue, FInt64.MaxValue
+FInt64.PositiveInfinity, FInt64.NegativeInfinity
+```
+
+### Utility Functions
+
+```typescript
+import { textReplace, textDeReplace, getHashCode, getHashCode32, splitLimited } from 'lineputscript';
+
+textReplace('hello|world')    // → 'hello/!|world' (display → storage)
+textDeReplace('hello/!|world') // → 'hello|world' (storage → display)
+getHashCode('text')           // → bigint (SHA-512 based, 64-bit LE)
+getHashCode32('text')         // → number (32-bit)
+splitLimited('a:b:c', ':', 1) // → ['a', 'b:c']
+```
+
+## TypeScript
+
+This package is written in TypeScript and ships with type declarations. All public APIs are fully typed.
+
+## License
+
+MIT

package/dist/chunk-4R46Q3P5.js

@@ -0,0 +1,2 @@
+'use strict';
+

package/dist/chunk-4RRNVMEO.mjs

@@ -0,0 +1,233 @@
+// src/utils/escaping.ts
+function textReplace(text) {
+  if (text === null || text === void 0) return "";
+  let result = text;
+  result = result.replace(/\|/g, "/|");
+  result = result.replace(/\//g, "/!");
+  result = result.replace(/:\|/g, "/stop");
+  result = result.replace(/\t/g, "/tab");
+  result = result.replace(/\n/g, "/n");
+  result = result.replace(/\r/g, "/r");
+  result = result.replace(/#/g, "/id");
+  result = result.replace(/,/g, "/com");
+  return result;
+}
+function textDeReplace(text) {
+  if (text === null || text === void 0) return "";
+  let result = text;
+  result = result.replace(/\/stop/g, ":|");
+  result = result.replace(/\/equ/g, "=");
+  result = result.replace(/\/tab/g, "	");
+  result = result.replace(/\/n/g, "\n");
+  result = result.replace(/\/r/g, "\r");
+  result = result.replace(/\/id/g, "#");
+  result = result.replace(/\/com/g, ",");
+  result = result.replace(/\/!/g, "/");
+  result = result.replace(/\/\|/g, "|");
+  return result;
+}
+
+// src/utils/fint64.ts
+var Anchor = 1000000000n;
+var Anchord = 1e9;
+var NaNValue = 9223372036854775807n - 1n;
+var NegativeInfinityValue = -9223372036854775807n + 1n;
+var PositiveInfinityValue = 9223372036854775807n;
+var _FInt64 = class _FInt64 {
+  constructor(value) {
+    this.m_value = value;
+  }
+  static fromLong(value) {
+    return new _FInt64(value);
+  }
+  static fromDouble(value) {
+    return new _FInt64(BigInt(Math.round(value * Anchord)));
+  }
+  static fromNumber(value) {
+    return _FInt64.fromDouble(value);
+  }
+  static fromInt(value) {
+    return new _FInt64(BigInt(value) * Anchor);
+  }
+  static fromObject(value) {
+    if (value instanceof _FInt64) return value;
+    if (typeof value === "bigint") return new _FInt64(value);
+    if (typeof value === "number") {
+      if (Number.isInteger(value)) return _FInt64.fromInt(value);
+      return _FInt64.fromDouble(value);
+    }
+    if (typeof value === "string") return _FInt64.parse(value);
+    return _FInt64.NaN;
+  }
+  toDouble() {
+    if (this.isNaN()) return NaN;
+    return Number(this.m_value) / Anchord;
+  }
+  toStoreString() {
+    return this.m_value.toString();
+  }
+  toString() {
+    return this.toDouble().toString();
+  }
+  isNaN() {
+    return this.m_value === NaNValue;
+  }
+  isNegativeInfinity() {
+    return this.m_value === NegativeInfinityValue;
+  }
+  isPositiveInfinity() {
+    return this.m_value === PositiveInfinityValue;
+  }
+  isFinite() {
+    return !this.isNaN() && !this.isNegativeInfinity() && !this.isPositiveInfinity();
+  }
+  isInfinity() {
+    return this.isPositiveInfinity() || this.isNegativeInfinity();
+  }
+  isNegative() {
+    return this.m_value < 0n;
+  }
+  isNormal() {
+    return this.m_value !== 0n && this.isFinite();
+  }
+  toBoolean() {
+    return this.m_value > Anchor;
+  }
+  toInt32() {
+    return Math.trunc(this.toDouble());
+  }
+  toInt64() {
+    return this.m_value / Anchor;
+  }
+  // Arithmetic
+  add(other) {
+    return new _FInt64(this.m_value + other.m_value);
+  }
+  sub(other) {
+    return new _FInt64(this.m_value - other.m_value);
+  }
+  mul(other) {
+    return new _FInt64(this.m_value / 1000n * (other.m_value / 1000n) / 1000n);
+  }
+  div(other) {
+    return new _FInt64(this.m_value * 100000n / other.m_value * 10000n);
+  }
+  addDouble(other) {
+    return new _FInt64(this.m_value + BigInt(Math.round(other * Anchord)));
+  }
+  subDouble(other) {
+    return new _FInt64(this.m_value - BigInt(Math.round(other * Anchord)));
+  }
+  mulDouble(other) {
+    return new _FInt64(BigInt(Math.round(Number(this.m_value) * other)));
+  }
+  divDouble(other) {
+    return new _FInt64(BigInt(Math.round(Number(this.m_value) / other)));
+  }
+  negate() {
+    return new _FInt64(-this.m_value);
+  }
+  increment() {
+    return new _FInt64(this.m_value + Anchor);
+  }
+  decrement() {
+    return new _FInt64(this.m_value - Anchor);
+  }
+  // Bitwise
+  and(other) {
+    return new _FInt64(this.m_value & other.m_value);
+  }
+  or(other) {
+    return new _FInt64(this.m_value | other.m_value);
+  }
+  xor(other) {
+    return new _FInt64(this.m_value ^ other.m_value);
+  }
+  not() {
+    return new _FInt64(~this.m_value);
+  }
+  // Comparison
+  compareTo(other) {
+    if (this.isNaN()) return -1;
+    if (other.isNaN()) return 1;
+    if (this.m_value < other.m_value) return -1;
+    if (this.m_value > other.m_value) return 1;
+    return 0;
+  }
+  equals(other) {
+    if (this.isNaN() || other.isNaN()) return false;
+    return this.m_value === other.m_value;
+  }
+  // Parse
+  static parse(s) {
+    if (s === null || s === void 0) return _FInt64.NaN;
+    const longMatch = /^-?\d+$/.test(s);
+    if (longMatch) {
+      try {
+        const bi = BigInt(s);
+        return new _FInt64(bi);
+      } catch {
+      }
+    }
+    const d = Number(s);
+    if (!isNaN(d)) {
+      return _FInt64.fromDouble(d);
+    }
+    return _FInt64.NaN;
+  }
+  static tryParse(s) {
+    if (s === null || s === void 0) return { result: _FInt64.Zero, success: false };
+    const parsed = _FInt64.parse(s);
+    if (parsed.isNaN()) return { result: _FInt64.Zero, success: false };
+    return { result: parsed, success: true };
+  }
+  // Static helpers
+  static isFinite(d) {
+    return d.isFinite();
+  }
+  static isInfinity(d) {
+    return d.isInfinity();
+  }
+  static isNaNStatic(d) {
+    return d.isNaN();
+  }
+  static isNegative(d) {
+    return d.isNegative();
+  }
+  static isNormal(d) {
+    return d.isNormal();
+  }
+};
+// Constants
+_FInt64.Anchor = Anchor;
+_FInt64.Anchord = Anchord;
+_FInt64.MinValue = new _FInt64(-9223372036854775807n - 1n);
+_FInt64.MaxValue = new _FInt64(9223372036854775807n);
+_FInt64.NaN = new _FInt64(NaNValue);
+_FInt64.NegativeInfinity = new _FInt64(NegativeInfinityValue);
+_FInt64.PositiveInfinity = new _FInt64(PositiveInfinityValue);
+_FInt64.Zero = new _FInt64(0n);
+_FInt64.One = new _FInt64(Anchor);
+_FInt64.NegativeOne = _FInt64.fromDouble(-1);
+_FInt64.AdditiveIdentity = new _FInt64(0n);
+_FInt64.MultiplicativeIdentity = new _FInt64(Anchor);
+var FInt64 = _FInt64;
+
+// src/utils/parsing.ts
+function splitLimited(text, separator, count = -1) {
+  if (count === -1) {
+    return text.split(separator);
+  }
+  const result = [];
+  let remaining = text;
+  for (let i = 0; i < count; i++) {
+    const idx = remaining.indexOf(separator);
+    if (idx === -1) break;
+    result.push(remaining.substring(0, idx));
+    remaining = remaining.substring(idx + separator.length);
+  }
+  result.push(remaining);
+  return result;
+}
+
+export { FInt64, splitLimited, textDeReplace, textReplace };