@tsplc/build 0.0.0-stage → 0.2.0

package/src/st/declarations.ts

@@ -0,0 +1,229 @@
+import type { Token } from "./lexer";
+import type { TokenReader } from "./reader";
+
+export const objectKinds = {
+  PROGRAM: "program",
+  FUNCTION_BLOCK: "function_block",
+  FUNCTIONBLOCK: "function_block",
+  FUNCTION: "function",
+  METHOD: "method",
+  INTERFACE: "interface",
+  PROPERTY: "property",
+} as const;
+
+const modifiers = new Set([
+  "PUBLIC",
+  "PRIVATE",
+  "PROTECTED",
+  "INTERNAL",
+  "FINAL",
+  "ABSTRACT",
+  "OVERRIDE",
+]);
+export const globalSections = new Set(["VAR_GLOBAL", "VAR_CONFIG"]);
+export const variableSections = new Set([
+  ...globalSections,
+  "VAR",
+  "VAR_INPUT",
+  "VAR_OUTPUT",
+  "VAR_IN_OUT",
+  "VAR_TEMP",
+  "VAR_STAT",
+  "VAR_INST",
+  "VAR_EXTERNAL",
+  "VAR_ACCESS",
+  "VAR_GENERIC",
+]);
+const closingObjects = new Set(Object.keys(objectKinds).map((kind) => `END_${kind}`));
+export const declarationKeywords = new Set([
+  ...Object.keys(objectKinds),
+  ...closingObjects,
+  ...variableSections,
+  "END_VAR",
+  "TYPE",
+  "END_TYPE",
+  "STRUCT",
+  "END_STRUCT",
+  "UNION",
+  "END_UNION",
+  "ACTION",
+  "END_ACTION",
+  "CONFIGURATION",
+  "END_CONFIGURATION",
+]);
+
+const conditionalDirective = (token?: Token) => {
+  if (token?.kind === "pragma") {
+    return /^\{\s*(IF|ELSIF|ELSE|END_IF)\b/i.exec(token.value)?.[1]?.toUpperCase();
+  }
+};
+const isDeclarationPragma = (token?: Token) =>
+  token?.kind === "pragma" && !conditionalDirective(token);
+
+export const readDeclarationPragmas = (reader: TokenReader) => {
+  while (isDeclarationPragma(reader.peek())) {
+    reader.take();
+  }
+};
+
+export const readDeclarationSemicolon = (reader: TokenReader) => {
+  const token = reader.peek();
+  // A semicolon on the next line may be the body's first empty statement.
+  // Only attach it to a declaration when it terminates that same line.
+  if (token?.value === ";" && !/[\r\n]/.test(reader.source.slice(reader.end, token.start))) {
+    reader.take();
+  }
+};
+
+export const readIdentifier = (reader: TokenReader) => {
+  const token = reader.take();
+  if (token.kind !== "word" || declarationKeywords.has(token.value)) {
+    reader.fail("Expected an IEC identifier", token);
+  }
+  return reader.source.slice(token.start, token.end);
+};
+
+const isOverrideModifier = (reader: TokenReader) => {
+  // OVERRIDE is also an established IEC name (e.g. OSCAT's function).
+  // A modifier needs a following name on the same line, not a body statement.
+  const name = reader.peek(1);
+  return (
+    name?.kind === "word" &&
+    !declarationKeywords.has(name.value) &&
+    !["(", "[", ":=", ".", "^"].includes(reader.peek(2)?.value ?? "") &&
+    !/[\r\n]/.test(reader.source.slice(reader.peek()?.end, name.start))
+  );
+};
+
+export const readModifiers = (reader: TokenReader) => {
+  while (modifiers.has(reader.peek()?.value ?? "")) {
+    if (reader.peek()?.value === "OVERRIDE" && !isOverrideModifier(reader)) {
+      return;
+    }
+    reader.take();
+  }
+};
+
+const typeDelimiters = { "(": ")", "[": "]", "<": ">" } as const;
+
+const readDelimitedType = (reader: TokenReader, open: keyof typeof typeDelimiters) => {
+  reader.expect(open);
+  const closings = [typeDelimiters[open]];
+  while (closings.length) {
+    const token = reader.take();
+    if (token.kind === "string" || token.kind === "pragma") {
+      continue;
+    }
+    if (token.value === "(" || token.value === "[") {
+      closings.push(typeDelimiters[token.value]);
+    } else if (token.value === ")" || token.value === "]") {
+      if (closings.pop() !== token.value) {
+        reader.fail(`Mismatched delimiter ${token.value}`, token);
+      }
+    } else if (open === "<" && closings.at(-1) === ">") {
+      // Inside parentheses, < and > are comparisons, not generic delimiters:
+      // FB_Base<(Size := BOOL_TO_INT(1 < 2))>.
+      if (token.value === "<") {
+        closings.push(">");
+      }
+      if (token.value === ">") {
+        closings.pop();
+      }
+    }
+    if (declarationKeywords.has(token.value) || token.value === ";") {
+      reader.fail(`Unclosed ${open}`, token);
+    }
+  }
+};
+
+export const readType = (reader: TokenReader): string => {
+  const start = reader.peek()?.start ?? reader.source.length;
+  // Prefix types can nest arbitrarily; iteration avoids a JavaScript stack limit.
+  while (true) {
+    if (["POINTER", "REFERENCE", "REF_TO"].includes(reader.peek()?.value ?? "")) {
+      if (reader.take().value !== "REF_TO") {
+        reader.expect("TO");
+      }
+      continue;
+    }
+    if (reader.consume("ARRAY")) {
+      readDelimitedType(reader, "[");
+      reader.expect("OF");
+      continue;
+    }
+    break;
+  }
+  readIdentifier(reader);
+  while (reader.consume(".")) {
+    readIdentifier(reader);
+  }
+  for (const open of ["(", "[", "<"] as const) {
+    if (reader.peek()?.value === open) {
+      readDelimitedType(reader, open);
+    }
+  }
+  return reader.source.slice(start, reader.end);
+};
+
+export const readVariableSection = (reader: TokenReader) => {
+  reader.take();
+  const conditionals: { hasElse: boolean }[] = [];
+  while (reader.peek()?.value !== "END_VAR") {
+    const token = reader.take();
+    if (variableSections.has(token.value) || closingObjects.has(token.value)) {
+      reader.fail("Missing END_VAR", token);
+    }
+    const directive = conditionalDirective(token);
+    if (!directive) {
+      continue;
+    }
+    if (directive === "IF") {
+      conditionals.push({ hasElse: false });
+      continue;
+    }
+    const current = conditionals.at(-1);
+    if (!current) {
+      return reader.fail("Unmatched conditional pragma", token);
+    }
+    if (directive === "END_IF") {
+      conditionals.pop();
+      continue;
+    }
+    if (current.hasElse) {
+      reader.fail("Conditional branch after ELSE", token);
+    }
+    current.hasElse = directive === "ELSE";
+  }
+  if (conditionals.length) {
+    reader.fail("Conditional pragmas must remain inside one variable section");
+  }
+  reader.take();
+  readDeclarationSemicolon(reader);
+};
+
+export const readDeclarationSections = (reader: TokenReader) => {
+  while (reader.peek()) {
+    // Pragmas belong to the declaration only when another declaration follows.
+    // Look ahead without consuming them so a pragma-only body stays intact.
+    let ahead = 0;
+    while (isDeclarationPragma(reader.peek(ahead))) {
+      ahead++;
+    }
+    const next = reader.peek(ahead)?.value ?? "";
+    if (variableSections.has(next)) {
+      readDeclarationPragmas(reader);
+      readVariableSection(reader);
+      continue;
+    }
+    if (next !== "EXTENDS" && next !== "IMPLEMENTS") {
+      return;
+    }
+    // CODESYS generic FBs can place these clauses after VAR_GENERIC.
+    readDeclarationPragmas(reader);
+    reader.take();
+    readType(reader);
+    while (reader.consume(",")) {
+      readType(reader);
+    }
+  }
+};

package/src/st/lexer.ts

@@ -0,0 +1,125 @@
+export type Token = {
+  kind: "word" | "string" | "pragma" | "symbol";
+  value: string;
+  start: number;
+  end: number;
+};
+
+export class StSyntaxError extends Error {
+  constructor(source: string, offset: number, filename: string, message: string) {
+    const lines = source.slice(0, offset).split(/\r\n|\r|\n/);
+    super(`${filename}:${lines.length}:${(lines.at(-1)?.length ?? 0) + 1}: ${message}`);
+    this.name = "StSyntaxError";
+  }
+}
+
+/** Keep original offsets: splitting must preserve comments, pragmas and source spelling. */
+export const tokenize = (source: string, filename = "<source>"): Token[] => {
+  const tokens: Token[] = [];
+  let offset = 0;
+  const fail = (start: number, message: string): never => {
+    throw new StSyntaxError(source, start, filename, message);
+  };
+  const quoted = () => {
+    const start = offset;
+    const quote = source[offset++];
+    while (offset < source.length) {
+      // IEC strings escape characters (including quotes and $ itself) with $.
+      if (source[offset] === "$") {
+        offset += 2;
+      } else if (source[offset++] === quote) {
+        return;
+      }
+    }
+    fail(start, "Unterminated string");
+  };
+  while (offset < source.length) {
+    const start = offset;
+    const character = source[offset] ?? "";
+    if (/\s|\uFEFF/.test(character)) {
+      offset++;
+      continue;
+    }
+    if (source.startsWith("//", offset)) {
+      while (offset < source.length && !/[\r\n]/.test(source[offset] ?? "")) {
+        offset++;
+      }
+      continue;
+    }
+    if (source.startsWith("(*", offset)) {
+      offset += 2;
+      let depth = 1;
+      while (offset < source.length && depth > 0) {
+        if (source.startsWith("(*", offset)) {
+          depth++;
+          offset += 2;
+        } else if (source.startsWith("*)", offset)) {
+          depth--;
+          offset += 2;
+        } else {
+          offset++;
+        }
+      }
+      if (depth) {
+        fail(start, "Unterminated block comment");
+      }
+      continue;
+    }
+    if (character === "'" || character === '"') {
+      quoted();
+      tokens.push({
+        kind: "string",
+        value: source.slice(start, offset),
+        start,
+        end: offset,
+      });
+      continue;
+    }
+    if (character === "{") {
+      offset++;
+      while (offset < source.length && source[offset] !== "}") {
+        if (source[offset] === "'" || source[offset] === '"') {
+          quoted();
+        } else {
+          offset++;
+        }
+      }
+      if (offset === source.length) {
+        fail(start, "Unterminated pragma");
+      }
+      offset++;
+      tokens.push({
+        kind: "pragma",
+        value: source.slice(start, offset),
+        start,
+        end: offset,
+      });
+      continue;
+    }
+    if (/[A-Za-z_]/.test(character)) {
+      offset++;
+      while (/[A-Za-z_0-9]/.test(source[offset] ?? "")) {
+        offset++;
+      }
+      tokens.push({
+        kind: "word",
+        value: source.slice(start, offset).toUpperCase(),
+        start,
+        end: offset,
+      });
+      continue;
+    }
+    offset++;
+    const pair = source.slice(start, offset + 1);
+    if ([":=", "=>", "..", "<=", ">=", "<>", "**"].includes(pair)) {
+      offset++;
+    }
+    tokens.push({
+      kind: "symbol",
+      value: source.slice(start, offset),
+      start,
+      end: offset,
+    });
+  }
+  return tokens;
+};

package/src/st/parse.ts

@@ -0,0 +1,202 @@
+import { basename } from "node:path";
+import {
+  declarationKeywords,
+  globalSections,
+  objectKinds,
+  readDeclarationPragmas,
+  readDeclarationSections,
+  readDeclarationSemicolon,
+  readIdentifier,
+  readModifiers,
+  readType,
+  readVariableSection,
+  variableSections,
+} from "./declarations";
+import type { Token } from "./lexer";
+import { createTokenReader, type TokenReader } from "./reader";
+
+export type ObjectKind =
+  (typeof objectKinds)[keyof typeof objectKinds] | "dut" | "gvl" | "action" | "get" | "set";
+export type ParsedSource = {
+  kind: ObjectKind;
+  name: string;
+  declaration: string;
+  implementation?: string;
+  returnType?: string;
+  dutType?: "structure" | "enumeration" | "union" | "alias";
+  persistent?: boolean;
+};
+
+type ParseOptions = {
+  filename?: string;
+  declarationOnly?: boolean;
+  name?: string;
+};
+
+const dutTypes: Record<string, NonNullable<ParsedSource["dutType"]>> = {
+  STRUCT: "structure",
+  UNION: "union",
+  "(": "enumeration",
+};
+
+const parseDut = (reader: TokenReader): ParsedSource => {
+  reader.expect("TYPE");
+  readModifiers(reader);
+  const name = readIdentifier(reader);
+  if (reader.consume("EXTENDS")) {
+    readType(reader);
+  }
+  reader.expect(":");
+  readDeclarationPragmas(reader);
+  const dutType = dutTypes[reader.peek()?.value ?? ""] ?? "alias";
+  while (reader.peek()?.value !== "END_TYPE") {
+    if (reader.peek()?.value === "TYPE") {
+      reader.fail("Only one TYPE declaration is allowed per file");
+    }
+    reader.take();
+  }
+  reader.take();
+  reader.consume(";");
+  if (reader.peek()) {
+    reader.fail("Unexpected content after END_TYPE");
+  }
+  return { kind: "dut", name, declaration: reader.source, dutType };
+};
+
+const parseGlobals = (reader: TokenReader, options: ParseOptions): ParsedSource => {
+  const header = reader.peek();
+  let persistent = false;
+  while (reader.peek()) {
+    readDeclarationPragmas(reader);
+    if (!reader.peek()) {
+      break;
+    }
+    if (!globalSections.has(reader.peek()?.value ?? "")) {
+      reader.fail("Expected a global variable section");
+    }
+    const start = reader.index;
+    readVariableSection(reader);
+    // Only the section modifiers select the CODESYS persistent-list object.
+    // Comments, pragma strings, and variable names cannot select this role.
+    for (const token of reader.tokens.slice(start + 1, reader.index)) {
+      if (
+        token.kind !== "word" ||
+        !["CONSTANT", "RETAIN", "PERSISTENT", "NON_RETAIN"].includes(token.value)
+      ) {
+        break;
+      }
+      persistent ||= token.value === "PERSISTENT";
+    }
+  }
+  const name = options.name ?? basename(reader.filename, ".st");
+  if (!/^[A-Za-z_][A-Za-z_0-9]*$/.test(name)) {
+    reader.fail("Global list requires an IEC filename or an explicit name", header);
+  }
+  return {
+    kind: "gvl",
+    name,
+    declaration: reader.source,
+    ...(persistent && { persistent: true }),
+  };
+};
+
+const validateImplementation = (reader: TokenReader, tokens: Token[]) => {
+  for (const token of tokens) {
+    if (token.kind !== "word") {
+      continue;
+    }
+    if (variableSections.has(token.value) || token.value === "END_VAR") {
+      reader.fail(
+        "Variable declaration outside the declaration section; conditional declaration envelopes are not supported",
+        token,
+      );
+    }
+    if (declarationKeywords.has(token.value)) {
+      reader.fail(
+        "Nested objects must be separate child files, or the object terminator is mismatched",
+        token,
+      );
+    }
+  }
+};
+
+const splitObject = (
+  reader: TokenReader,
+  header: Token,
+  kind: ObjectKind,
+  options: ParseOptions,
+): Pick<ParsedSource, "declaration" | "implementation"> => {
+  const terminator =
+    header.value === "FUNCTIONBLOCK" ? "END_FUNCTION_BLOCK" : `END_${header.value}`;
+  const remaining = reader.tokens.slice(reader.index);
+  const terminatorIndex = remaining.findIndex(
+    (token) => token.kind === "word" && token.value === terminator,
+  );
+  // Even interfaces and properties need END_* in combined files. Only an explicit
+  // declaration-only input (e.g. a paired declaration.st) may omit it.
+  if (terminatorIndex < 0 && !options.declarationOnly) {
+    reader.fail(`Missing ${terminator}`);
+  }
+  const bodyTokens = terminatorIndex < 0 ? remaining : remaining.slice(0, terminatorIndex);
+  const [endToken, next, afterSemicolon] =
+    terminatorIndex < 0 ? [] : remaining.slice(terminatorIndex);
+  const semicolon = next?.value === ";" ? next : undefined;
+  const unexpected = semicolon ? afterSemicolon : next;
+  if (unexpected) {
+    reader.fail(`Unexpected content after ${terminator}`, unexpected);
+  }
+  validateImplementation(reader, bodyTokens);
+
+  const declarationOnly = options.declarationOnly || kind === "interface" || kind === "property";
+  if (declarationOnly && bodyTokens.length) {
+    reader.fail("Unexpected implementation in a declaration-only object", bodyTokens[0]);
+  }
+
+  const declaration = reader.source.slice(0, reader.end);
+  // Remove only END_* and its optional semicolon. Keep whitespace and trailing
+  // comments in the body, or in the declaration for objects without a body.
+  const body =
+    reader.source.slice(reader.end, endToken?.start) +
+    (endToken ? reader.source.slice((semicolon ?? endToken).end) : "");
+  if (declarationOnly) {
+    return { declaration: declaration + body };
+  }
+  return { declaration, implementation: body };
+};
+
+const parsePou = (reader: TokenReader, options: ParseOptions): ParsedSource => {
+  const header = reader.take();
+  if (!(header.value in objectKinds)) {
+    reader.fail(`Unsupported object header ${header.value}`, header);
+  }
+  const kind = objectKinds[header.value as keyof typeof objectKinds];
+  readModifiers(reader);
+  const name = readIdentifier(reader);
+  const returnType = reader.consume(":") ? readType(reader) : undefined;
+  if (returnType === undefined && kind === "property") {
+    reader.fail(`${header.value} requires a return type`);
+  }
+  // Exported declarations may terminate the header itself with a semicolon.
+  readDeclarationSemicolon(reader);
+  readDeclarationSections(reader);
+  return {
+    kind,
+    name,
+    ...(returnType === undefined ? {} : { returnType }),
+    ...splitObject(reader, header, kind, options),
+  };
+};
+
+/** Parse only the object envelope and declarations. CODESYS validates executable ST. */
+export const parseSource = (source: string, options: ParseOptions = {}): ParsedSource => {
+  const reader = createTokenReader(source, options.filename ?? "<source>");
+  readDeclarationPragmas(reader);
+  const header = reader.peek();
+  if (header?.value === "TYPE") {
+    return parseDut(reader);
+  }
+  if (header && globalSections.has(header.value)) {
+    return parseGlobals(reader, options);
+  }
+  return parsePou(reader, options);
+};

package/src/st/reader.ts

@@ -0,0 +1,50 @@
+import { StSyntaxError, type Token, tokenize } from "./lexer";
+
+/** Traverse tokens without losing the source offsets needed for an exact split. */
+export const createTokenReader = (source: string, filename: string) => {
+  const tokens = tokenize(source, filename);
+  let index = 0;
+  const peek = (ahead = 0) => tokens[index + ahead];
+  const fail = (message: string, token = peek()): never => {
+    throw new StSyntaxError(source, token?.start ?? source.length, filename, message);
+  };
+  const take = (): Token => {
+    const token = peek();
+    if (!token) {
+      return fail("Unexpected end of declaration");
+    }
+    index++;
+    return token;
+  };
+  const expect = (value: string) => {
+    if (peek()?.value !== value) {
+      fail(`Expected ${value}`);
+    }
+    return take();
+  };
+  const consume = (value: string) => {
+    if (peek()?.value === value) {
+      return take();
+    }
+  };
+
+  return {
+    source,
+    filename,
+    tokens,
+    peek,
+    take,
+    expect,
+    consume,
+    fail,
+    get index() {
+      return index;
+    },
+    // The declaration ends at the last consumed token, before any body whitespace.
+    get end() {
+      return tokens[index - 1]?.end ?? 0;
+    },
+  };
+};
+
+export type TokenReader = ReturnType<typeof createTokenReader>;