@tsplc/debug 0.2.17 → 0.2.19

package/src/jobs.ts

@@ -6,22 +6,25 @@ const scalar = (iec: string): DebugType => ({ kind: "scalar", iec });
 
 /** What the trace said of a job: whether it is running, and when it last started. */
 export interface TracedJob {
-  busy: boolean;
-  startedAt?: string;
+	busy: boolean;
+	startedAt?: string;
 }
 
 /** The job's `busy` flag, read while a page shows the job and the trace says nothing of it. */
 export const busyRead = (job: DebugJob): TargetRead => ({
-  target: `${job.target}.busy`,
-  type: scalar("BOOL"),
+	target: `${job.target}.busy`,
+	type: scalar("BOOL"),
 });
 
 /** What a busy job shows: where it waits, since when, and its latest request. */
 export const detailReads = (job: DebugJob): TargetRead[] => [
-  { target: `${job.target}.step`, type: scalar("UINT") },
-  { target: `${job.target}.cancelling`, type: scalar("BOOL") },
-  ...(job.startedAt ? [{ target: job.startedAt, type: scalar("UDINT") }] : []),
-  ...job.requests.map(({ sequence }) => ({ target: sequence, type: scalar("UDINT") })),
+	{ target: `${job.target}.step`, type: scalar("UINT") },
+	{ target: `${job.target}.cancelling`, type: scalar("BOOL") },
+	...(job.startedAt ? [{ target: job.startedAt, type: scalar("UDINT") }] : []),
+	...job.requests.map(({ sequence }) => ({
+		target: sequence,
+		type: scalar("UDINT"),
+	})),
 ];
 
 /**
@@ -29,16 +32,20 @@ export const detailReads = (job: DebugJob): TargetRead[] => [
  * stops running it once it finishes, so the trace can miss the finish.
  */
 export const busyOf = (
-  job: DebugJob,
-  value: (target: string) => TargetSample | undefined,
-  traced: TracedJob | undefined,
+	job: DebugJob,
+	value: (target: string) => TargetSample | undefined,
+	traced: TracedJob | undefined,
 ) => {
-  const read = value(busyRead(job).target);
-  return read?.quality === "good" ? read.value === true : (traced?.busy ?? null);
+	const read = value(busyRead(job).target);
+	return read?.quality === "good"
+		? read.value === true
+		: (traced?.busy ?? null);
 };
 
 const numberOf = (sample: TargetSample | undefined) =>
-  sample?.quality === "good" && typeof sample.value === "number" ? sample.value : undefined;
+	sample?.quality === "good" && typeof sample.value === "number"
+		? sample.value
+		: undefined;
 
 /**
  * A job as the debugger shows it at host time `now`. Details are shown only while it is busy;
@@ -46,70 +53,88 @@ const numberOf = (sample: TargetSample | undefined) =>
  * clock estimate there is no start time from the PLC's own `startedAt`.
  */
 export const jobState = (
-  job: DebugJob,
-  inputs: {
-    value: (target: string) => TargetSample | undefined;
-    traced: TracedJob | undefined;
-    failure: JobState["failure"];
-    /** Busy, but its details aren't read for want of room in the poll. */
-    unread: boolean;
-    clock: Session["clock"];
-    now: number;
-    /** The server's trace of a call, which the PLC tags with its job and the call site's count. */
-    request: (call: { job: number; service: string; sequence: number }) => RequestTrace | undefined;
-  },
+	job: DebugJob,
+	inputs: {
+		value: (target: string) => TargetSample | undefined;
+		traced: TracedJob | undefined;
+		failure: JobState["failure"];
+		/** Busy, but its details aren't read for want of room in the poll. */
+		unread: boolean;
+		clock: Session["clock"];
+		now: number;
+		/** The server's trace of a call, which the PLC tags with its job and the call site's count. */
+		request: (call: {
+			job: number;
+			service: string;
+			sequence: number;
+		}) => RequestTrace | undefined;
+	},
 ): JobState => {
-  const { value, traced, clock, now } = inputs;
-  const busy = busyOf(job, value, traced);
-  const startedPlc = job.startedAt === undefined ? undefined : numberOf(value(job.startedAt));
-  const startedAt =
-    traced?.startedAt ??
-    (clock && startedPlc !== undefined
-      ? new Date(startedPlc - clock.offsetMs).toISOString()
-      : undefined);
-  const base: JobState = {
-    id: job.id,
-    quality: value(busyRead(job).target)?.quality ?? (traced ? "good" : "unavailable"),
-    busy,
-    ...(startedAt && { startedAt }),
-    ...(inputs.failure && { failure: inputs.failure }),
-  };
-  if (!busy) return base;
-  if (inputs.unread) return { ...base, unread: true };
+	const { value, traced, clock, now } = inputs;
+	const busy = busyOf(job, value, traced);
+	const startedPlc =
+		job.startedAt === undefined ? undefined : numberOf(value(job.startedAt));
+	const startedAt =
+		traced?.startedAt ??
+		(clock && startedPlc !== undefined
+			? new Date(startedPlc - clock.offsetMs).toISOString()
+			: undefined);
+	const base: JobState = {
+		id: job.id,
+		quality:
+			value(busyRead(job).target)?.quality ?? (traced ? "good" : "unavailable"),
+		busy,
+		...(startedAt && { startedAt }),
+		...(inputs.failure && { failure: inputs.failure }),
+	};
+	if (!busy) {
+		return base;
+	}
+	if (inputs.unread) {
+		return { ...base, unread: true };
+	}
 
-  const step = numberOf(value(`${job.target}.step`));
-  const current = job.steps.find((candidate) => candidate.step === step);
-  // Each call site counts its own requests, so the latest is the one the server saw start last,
-  // or the one counted furthest while the server has yet to report them.
-  const calls = job.requests
-    .map((call) => {
-      const sequence = numberOf(value(call.sequence)) ?? 0;
-      const trace = inputs.request({ job: call.job ?? job.id, service: call.service, sequence });
-      return { service: call.service, sequence, trace };
-    })
-    .filter(({ sequence }) => sequence > 0);
-  const later = (call: (typeof calls)[number], than: (typeof calls)[number]) =>
-    call.trace && than.trace
-      ? call.trace.startedAt > than.trace.startedAt
-      : call.sequence > than.sequence;
-  const latest = calls.reduce<(typeof calls)[number] | undefined>(
-    (latest, call) => (latest && !later(call, latest) ? latest : call),
-    undefined,
-  );
-  const cancelling = value(`${job.target}.cancelling`);
+	const step = numberOf(value(`${job.target}.step`));
+	const current = job.steps.find((candidate) => candidate.step === step);
+	// Each call site counts its own requests, so the latest is the one the server saw start last,
+	// or the one counted furthest while the server has yet to report them.
+	const calls = job.requests
+		.map((call) => {
+			const sequence = numberOf(value(call.sequence)) ?? 0;
+			const trace = inputs.request({
+				job: call.job ?? job.id,
+				service: call.service,
+				sequence,
+			});
+			return { service: call.service, sequence, trace };
+		})
+		.filter(({ sequence }) => sequence > 0);
+	const later = (call: (typeof calls)[number], than: (typeof calls)[number]) =>
+		call.trace && than.trace
+			? call.trace.startedAt > than.trace.startedAt
+			: call.sequence > than.sequence;
+	const latest = calls.reduce<(typeof calls)[number] | undefined>(
+		(latest, call) => (latest && !later(call, latest) ? latest : call),
+		undefined,
+	);
+	const cancelling = value(`${job.target}.cancelling`);
 
-  return {
-    ...base,
-    ...(cancelling?.quality === "good" && { cancelling: cancelling.value === true }),
-    ...(step !== undefined && { step }),
-    ...(current && { current: { kind: current.kind, range: current.range, text: current.text } }),
-    ...(startedAt && { elapsedMs: Math.max(0, now - Date.parse(startedAt)) }),
-    ...(latest && {
-      request: {
-        service: latest.service,
-        sequence: latest.sequence,
-        ...(latest.trace && { trace: latest.trace }),
-      },
-    }),
-  };
+	return {
+		...base,
+		...(cancelling?.quality === "good" && {
+			cancelling: cancelling.value === true,
+		}),
+		...(step !== undefined && { step }),
+		...(current && {
+			current: { kind: current.kind, range: current.range, text: current.text },
+		}),
+		...(startedAt && { elapsedMs: Math.max(0, now - Date.parse(startedAt)) }),
+		...(latest && {
+			request: {
+				service: latest.service,
+				sequence: latest.sequence,
+				...(latest.trace && { trace: latest.trace }),
+			},
+		}),
+	};
 };

package/src/login-value.ts

@@ -0,0 +1,165 @@
+import { elementaryType } from "@tsplc/iec";
+import type { DebugType } from "./manifest.ts";
+
+/** CODESYS's `TRUE`/`FALSE`, and the digits a BOOL may also read as. */
+const booleans: Record<string, boolean> = {
+	TRUE: true,
+	FALSE: false,
+	"1": true,
+	"0": false,
+};
+
+const radixPrefixes: Record<string, string> = { 2: "0b", 8: "0o", 16: "0x" };
+
+const timeUnits: Record<string, number> = {
+	d: 86_400_000,
+	h: 3_600_000,
+	m: 60_000,
+	s: 1000,
+	ms: 1,
+	us: 0.001,
+	ns: 0.000_001,
+};
+
+/** IEC's `$` escapes by letter; `$$`, `$'` and `$"` stand for themselves. */
+const stringEscapes: Record<string, string> = {
+	l: "\n",
+	n: "\n",
+	p: "\f",
+	r: "\r",
+	t: "\t",
+};
+
+/** Typed literals such as `INT#5`, without their type; TIME's own `T#` prefix is kept. */
+const withoutTypePrefix = (text: string) =>
+	text.replace(/^(?!L?T(?:IME)?#)[a-z_]+#(?=.)/i, "");
+
+/** `16#FF`, `2#1010`, `-42`, with IEC's digit separators, as a BigInt literal. */
+const bigIntLiteral = (text: string) => {
+	const [, radix, digits] = /^(2|8|16)#([0-9a-f_]+)$/i.exec(text) ?? [];
+	if (radix !== undefined && digits !== undefined) {
+		return `${radixPrefixes[radix]}${digits.replaceAll("_", "")}`;
+	}
+	const decimal = text.replaceAll("_", "");
+	return /^[+-]?\d+$/.test(decimal) ? decimal : undefined;
+};
+
+/** An integer literal; beyond doubles' exact range, a string. */
+const integer = (text: string) => {
+	const literal = bigIntLiteral(text);
+	if (literal === undefined) {
+		return undefined;
+	}
+	const value = BigInt(literal);
+	return Number.isSafeInteger(Number(value)) ? Number(value) : String(value);
+};
+
+const real = (text: string) => {
+	const number = Number(text);
+	return text !== "" && !Number.isNaN(number) ? number : undefined;
+};
+
+/** `T#1h2m3s4ms`, `TIME#-1.5s`, `LTIME#5us`, in milliseconds. */
+const duration = (text: string) => {
+	const [, sign, body] = /^L?T(?:IME)?#(-?)(.+)$/i.exec(text) ?? [];
+	if (body === undefined) {
+		return undefined;
+	}
+	const units = body.replaceAll("_", "");
+	const parts = [...units.matchAll(/(\d+(?:\.\d+)?)(ms|us|ns|d|h|m|s)/gi)];
+	if (parts.map(([part]) => part).join("") !== units) {
+		return undefined;
+	}
+	const ms = parts.reduce(
+		(total, [, amount, unit]) =>
+			total + Number(amount) * timeUnits[unit!.toLowerCase()]!,
+		0,
+	);
+	return sign ? -ms : ms;
+};
+
+/** `'it$'s'` or `"wide"`, with IEC's `$` escapes. */
+const quoted = (text: string) => {
+	const [, , body] = /^(['"])(.*)\1$/s.exec(text) ?? [];
+	return body?.replace(/\$([0-9a-f]{2}|[$'"lnprt])/gi, (_, code: string) =>
+		code.length === 2
+			? String.fromCharCode(parseInt(code, 16))
+			: (stringEscapes[code.toLowerCase()] ?? code),
+	);
+};
+
+/** A member's number, or the name the login gave when the manifest doesn't list it. */
+const enumValue = (
+	type: Extract<DebugType, { kind: "enum" }>,
+	text: string,
+) => {
+	const number = integer(text);
+	if (typeof number === "number") {
+		return number;
+	}
+	// `E_Bin.Present`, `Present`, or a member the manifest lacks with its number: `Missing (7)`.
+	const [, name, value] =
+		/^(?:\w+\.)*(\w+)(?:\s*\((-?\d+)\))?$/.exec(text) ?? [];
+	if (name === undefined) {
+		return undefined;
+	}
+	return type.members[name] ?? (value === undefined ? name : Number(value));
+};
+
+/** Only raw assembly bytes are read whole; their elements are scalars named by IEC type. */
+const arrayValue = (
+	type: Extract<DebugType, { kind: "array" }>,
+	text: string,
+) => {
+	const items = text.replace(/^\[/, "").replace(/\]$/, "").trim();
+	if (!items) {
+		return [];
+	}
+	const values = items
+		.split(/\s*,\s*/)
+		.map((item) => scalarValue(type.element, item));
+	return values.length === type.length &&
+		values.every((value) => value !== undefined)
+		? values
+		: undefined;
+};
+
+const scalarValue = (iec: string, text: string): unknown => {
+	const untyped = withoutTypePrefix(text);
+	const name = iec.toUpperCase();
+	switch (elementaryType(name)?.family) {
+		case "bool":
+			return booleans[untyped.toUpperCase()];
+		case "integer":
+		case "bits":
+			return integer(untyped);
+		case "real":
+			return real(untyped);
+		case "duration":
+			return duration(text);
+	}
+	if (/^W?STRING\b/.test(name)) {
+		return quoted(text) ?? text;
+	}
+	return text;
+};
+
+/**
+ * A value as `read_value` returns it, in the form the debugger decodes: BOOL as a boolean,
+ * numbers and TIME (in ms) as numbers, enums as their member's number (or its name when the
+ * manifest doesn't list it), STRING unquoted, and arrays read whole as arrays. Undefined when the
+ * text doesn't fit the type.
+ */
+export const parseLoginValue = (type: DebugType, text: string): unknown => {
+	const trimmed = text.trim();
+	switch (type.kind) {
+		case "enum":
+			return enumValue(type, withoutTypePrefix(trimmed));
+		case "array":
+			return arrayValue(type, withoutTypePrefix(trimmed));
+		case "record":
+			return undefined;
+		case "scalar":
+			return scalarValue(type.iec, trimmed);
+	}
+};