lmxopcua/src/ZB.MOM.WW.OtOpcUa.Driver.S7/S7AddressParser.cs

using S7NetCpuType = global::S7.Net.CpuType;

namespace ZB.MOM.WW.OtOpcUa.Driver.S7;

/// <summary>
///     Siemens S7 memory area. The driver's tag-address parser maps every S7 tag string into
///     exactly one of these + an offset. Values match the on-wire S7 area codes only
///     incidentally — S7.Net uses its own <c>DataType</c> enum (<c>DataBlock</c>, <c>Memory</c>,
///     <c>Input</c>, <c>Output</c>, <c>Timer</c>, <c>Counter</c>) so the adapter layer translates.
/// </summary>
public enum S7Area
{
    DataBlock,
    Memory,  // M (Merker / marker byte)
    Input,   // I (process-image input)
    Output,  // Q (process-image output)
    Timer,
    Counter,
}

/// <summary>
///     Access width for a DB / M / I / Q address. Timers and counters are always 16-bit
///     opaque (not user-addressable via size suffixes).
/// </summary>
public enum S7Size
{
    Bit,     // X
    Byte,    // B
    Word,    // W — 16-bit
    DWord,   // D — 32-bit
    LWord,   // LD / DBL — 64-bit (LInt/ULInt/LReal). S7.Net has no native size suffix; the
             // driver issues an 8-byte ReadBytes and converts big-endian in-process.
}

/// <summary>
///     Parsed form of an S7 tag-address string. Produced by <see cref="S7AddressParser.Parse(string)"/>.
/// </summary>
/// <param name="Area">Memory area (DB, M, I, Q, T, C).</param>
/// <param name="DbNumber">Data block number; only meaningful when <paramref name="Area"/> is <see cref="S7Area.DataBlock"/>.</param>
/// <param name="Size">Access width. Always <see cref="S7Size.Word"/> for Timer and Counter.</param>
/// <param name="ByteOffset">Byte offset into the area (for DB/M/I/Q) or the timer/counter number.</param>
/// <param name="BitOffset">Bit position 0-7 when <paramref name="Size"/> is <see cref="S7Size.Bit"/>; 0 otherwise.</param>
public readonly record struct S7ParsedAddress(
    S7Area Area,
    int DbNumber,
    S7Size Size,
    int ByteOffset,
    int BitOffset);

/// <summary>
///     Parses Siemens S7 address strings into <see cref="S7ParsedAddress"/>. Accepts the
///     Siemens TIA-Portal / STEP 7 Classic syntax documented in <c>docs/v2/driver-specs.md</c> §5:
///     <list type="bullet">
///         <item><c>DB{n}.DB{X|B|W|D}{offset}[.bit]</c> — e.g. <c>DB1.DBX0.0</c>, <c>DB1.DBW0</c>, <c>DB1.DBD4</c></item>
///         <item><c>DB{n}.{DBLD|DBL}{offset}</c> — 64-bit (LInt / ULInt / LReal) e.g. <c>DB1.DBLD0</c>, <c>DB1.DBL8</c></item>
///         <item><c>M{B|W|D}{offset}</c> or <c>M{offset}.{bit}</c> — e.g. <c>MB0</c>, <c>MW0</c>, <c>MD4</c>, <c>M0.0</c></item>
///         <item><c>M{LD}{offset}</c> — 64-bit Merker, e.g. <c>MLD0</c></item>
///         <item><c>I{B|W|D}{offset}</c> or <c>I{offset}.{bit}</c> — e.g. <c>IB0</c>, <c>IW0</c>, <c>ID0</c>, <c>I0.0</c></item>
///         <item><c>Q{B|W|D}{offset}</c> or <c>Q{offset}.{bit}</c> — e.g. <c>QB0</c>, <c>QW0</c>, <c>QD0</c>, <c>Q0.0</c></item>
///         <item><c>I{LD}{offset}</c> / <c>Q{LD}{offset}</c> — 64-bit Input/Output, e.g. <c>ILD0</c>, <c>QLD0</c></item>
///         <item><c>T{n}</c> — e.g. <c>T0</c>, <c>T15</c></item>
///         <item><c>C{n}</c> — e.g. <c>C0</c>, <c>C10</c></item>
///     </list>
///     Grammar is case-insensitive. Leading/trailing whitespace tolerated. Bit specifiers
///     must be 0-7; byte offsets must be non-negative; DB numbers must be &gt;= 1.
/// </summary>
/// <remarks>
///     Parse is deliberately strict — the parser rejects syntactic garbage up-front so a bad
///     tag config fails at driver init time instead of surfacing as a misleading
///     <c>BadInternalError</c> on every Read against that tag.
/// </remarks>
public static class S7AddressParser
{
    /// <summary>
    ///     Parse an S7 address. Throws <see cref="FormatException"/> on any syntax error with
    ///     the offending input echoed in the message so operators can correlate to the tag
    ///     config that produced the fault.
    /// </summary>
    /// <remarks>
    ///     The CPU-agnostic overload rejects the <c>V</c> area letter; <c>V</c> is only
    ///     meaningful on S7-200 / S7-200 Smart / LOGO! where it maps to a fixed DB number
    ///     (DB1 by convention) — call <see cref="Parse(string, S7NetCpuType?)"/> with the
    ///     device's CPU family for V-memory tags.
    /// </remarks>
    public static S7ParsedAddress Parse(string address) => Parse(address, cpuType: null);

    /// <summary>
    ///     Parse an S7 address with knowledge of the device's CPU family. Required for the
    ///     <c>V</c> area letter (S7-200 / S7-200 Smart / LOGO! V-memory), which maps to
    ///     DataBlock DB1 on those families. On S7-300 / S7-400 / S7-1200 / S7-1500 the
    ///     <c>V</c> letter is rejected because it has no equivalent — those families use
    ///     explicit <c>DB{n}.DB...</c> addressing.
    /// </summary>
    /// <remarks>
    ///     LOGO! firmware bands map V-memory to different underlying DB numbers in some
    ///     0BA editions; the driver currently uses DB1 (the most common LOGO! 8 / 0BA8
    ///     mapping). If a future site ships a firmware band where VM lives in a different
    ///     DB, the mapping table in <see cref="VMemoryDbNumberFor"/> is the single point
    ///     to extend. Live LOGO! testing is out of scope for the initial PR.
    /// </remarks>
    public static S7ParsedAddress Parse(string address, S7NetCpuType? cpuType)
    {
        if (string.IsNullOrWhiteSpace(address))
            throw new FormatException("S7 address must not be empty");
        var s = address.Trim().ToUpperInvariant();

        // --- DB{n}.DB{X|B|W|D}{offset}[.bit] ---
        if (s.StartsWith("DB") && TryParseDataBlock(s, out var dbResult))
            return dbResult;

        if (s.Length < 2)
            throw new FormatException($"S7 address '{address}' is too short to parse");

        var areaChar = s[0];
        var rest = s.Substring(1);

        switch (areaChar)
        {
            case 'M': return ParseMIQ(S7Area.Memory, rest, address);
            case 'I': return ParseMIQ(S7Area.Input, rest, address);
            case 'Q': return ParseMIQ(S7Area.Output, rest, address);
            case 'T': return ParseTimerOrCounter(S7Area.Timer, rest, address);
            case 'C': return ParseTimerOrCounter(S7Area.Counter, rest, address);
            case 'V': return ParseV(rest, address, cpuType);
            default:
                throw new FormatException($"S7 address '{address}' starts with unknown area '{areaChar}' (expected DB/M/I/Q/T/C/V)");
        }
    }

    /// <summary>
    ///     Try-parse variant for callers that can't afford an exception on bad input (e.g.
    ///     config validation pages in the Admin UI). Returns <c>false</c> for any input that
    ///     would throw from <see cref="Parse(string)"/>.
    /// </summary>
    public static bool TryParse(string address, out S7ParsedAddress result)
        => TryParse(address, cpuType: null, out result);

    /// <summary>
    ///     Try-parse variant that accepts a CPU family for V-memory addressing.
    /// </summary>
    public static bool TryParse(string address, S7NetCpuType? cpuType, out S7ParsedAddress result)
    {
        try
        {
            result = Parse(address, cpuType);
            return true;
        }
        catch (FormatException)
        {
            result = default;
            return false;
        }
    }

    private static bool TryParseDataBlock(string s, out S7ParsedAddress result)
    {
        result = default;
        // Split on first '.': left side must be DB{n}, right side DB{X|B|W|D}{offset}[.bit]
        var dot = s.IndexOf('.');
        if (dot < 0) return false;
        var head = s.Substring(0, dot);    // DB{n}
        var tail = s.Substring(dot + 1);   // DB{X|B|W|D}{offset}[.bit]

        if (head.Length < 3) return false;
        if (!int.TryParse(head.AsSpan(2), out var dbNumber) || dbNumber < 1)
            throw new FormatException($"S7 DB number in '{s}' must be a positive integer");

        if (!tail.StartsWith("DB") || tail.Length < 4)
            throw new FormatException($"S7 DB address tail '{tail}' must start with DB{{X|B|W|D|LD|L}}");

        // 64-bit suffixes are two-letter (LD or DBL-as-prefix). Detect them up front so the
        // single-char switch below stays readable. "DBLD" is the symmetric extension of
        // DBX/DBB/DBW/DBD; "DBL" is the shorter Siemens "long" alias accepted as an alternate.
        S7Size size;
        int offsetStart;
        if (tail.Length >= 5 && tail[2] == 'L' && tail[3] == 'D')
        {
            size = S7Size.LWord;
            offsetStart = 4;
        }
        else if (tail.Length >= 4 && tail[2] == 'L')
        {
            size = S7Size.LWord;
            offsetStart = 3;
        }
        else
        {
            var sizeChar = tail[2];
            offsetStart = 3;
            size = sizeChar switch
            {
                'X' => S7Size.Bit,
                'B' => S7Size.Byte,
                'W' => S7Size.Word,
                'D' => S7Size.DWord,
                _ => throw new FormatException($"S7 DB size '{sizeChar}' in '{s}' must be X/B/W/D/LD/L"),
            };
        }

        var (byteOffset, bitOffset) = ParseOffsetAndOptionalBit(tail, offsetStart, size, s);
        result = new S7ParsedAddress(S7Area.DataBlock, dbNumber, size, byteOffset, bitOffset);
        return true;
    }

    private static S7ParsedAddress ParseMIQ(S7Area area, string rest, string original)
    {
        if (rest.Length == 0)
            throw new FormatException($"S7 address '{original}' has no offset");

        var first = rest[0];
        S7Size size;
        int offsetStart;
        // Two-char "LD" prefix (8-byte LWord) checked first so it doesn't get swallowed by
        // the single-letter cases below.
        if (rest.Length >= 2 && first == 'L' && rest[1] == 'D')
        {
            size = S7Size.LWord;
            offsetStart = 2;
        }
        else
        {
            switch (first)
            {
                case 'B': size = S7Size.Byte;  offsetStart = 1; break;
                case 'W': size = S7Size.Word;  offsetStart = 1; break;
                case 'D': size = S7Size.DWord; offsetStart = 1; break;
                default:
                    // No size prefix => bit-level address requires explicit .bit. Size stays Bit;
                    // ParseOffsetAndOptionalBit will demand the dot.
                    size = S7Size.Bit;
                    offsetStart = 0;
                    break;
            }
        }

        var (byteOffset, bitOffset) = ParseOffsetAndOptionalBit(rest, offsetStart, size, original);
        return new S7ParsedAddress(area, DbNumber: 0, size, byteOffset, bitOffset);
    }

    /// <summary>
    ///     Parse a <c>V</c>-area address (S7-200 / S7-200 Smart / LOGO! V-memory). Same width
    ///     suffixes as M/I/Q (<c>VB</c>, <c>VW</c>, <c>VD</c>, <c>V0.0</c>) but rewritten as
    ///     a DataBlock access so the rest of the driver — which speaks S7.Net's DB-centric
    ///     API — needs no special-casing downstream.
    /// </summary>
    private static S7ParsedAddress ParseV(string rest, string original, S7NetCpuType? cpuType)
    {
        var dbNumber = VMemoryDbNumberFor(cpuType, original);
        // Reuse the M/I/Q grammar — V's size suffixes are identical (B/W/D/LD or .bit).
        var parsed = ParseMIQ(S7Area.Memory, rest, original);
        return parsed with { Area = S7Area.DataBlock, DbNumber = dbNumber };
    }

    /// <summary>
    ///     Map a CPU family to the underlying DB number that backs V-memory. Returns DB1
    ///     for S7-200, S7-200 Smart, and LOGO! 0BA8 (the only LOGO! the S7.Net <c>CpuType</c>
    ///     enum surfaces). Throws for families that have no V-area concept.
    /// </summary>
    private static int VMemoryDbNumberFor(S7NetCpuType? cpuType, string original)
    {
        if (cpuType is null)
            throw new FormatException(
                $"S7 V-memory address '{original}' requires a CPU family (S7-200 / S7-200 Smart / LOGO!) — " +
                "the CPU-agnostic Parse overload cannot resolve V-memory to a DB number");

        return cpuType.Value switch
        {
            S7NetCpuType.S7200      => 1,
            S7NetCpuType.S7200Smart => 1,
            // LOGO! 8 / 0BA8 firmware bands typically expose VM as DB1 over S7comm. Older
            // 0BA editions can differ; the mapping is centralised here for easy extension
            // once a site provides a non-DB1 firmware band to test against.
            S7NetCpuType.Logo0BA8   => 1,
            _ => throw new FormatException(
                $"S7 V-memory address '{original}' is only valid on S7-200 / S7-200 Smart / LOGO! " +
                $"(got CpuType={cpuType.Value}); use explicit DB{{n}}.DB... addressing on this family"),
        };
    }

    private static S7ParsedAddress ParseTimerOrCounter(S7Area area, string rest, string original)
    {
        if (rest.Length == 0)
            throw new FormatException($"S7 address '{original}' has no {area} number");
        if (!int.TryParse(rest, out var number) || number < 0)
            throw new FormatException($"S7 {area} number in '{original}' must be a non-negative integer");
        return new S7ParsedAddress(area, DbNumber: 0, S7Size.Word, number, BitOffset: 0);
    }

    private static (int byteOffset, int bitOffset) ParseOffsetAndOptionalBit(
        string s, int start, S7Size size, string original)
    {
        var offsetEnd = start;
        while (offsetEnd < s.Length && s[offsetEnd] >= '0' && s[offsetEnd] <= '9')
            offsetEnd++;
        if (offsetEnd == start)
            throw new FormatException($"S7 address '{original}' has no byte-offset digits");

        if (!int.TryParse(s.AsSpan(start, offsetEnd - start), out var byteOffset) || byteOffset < 0)
            throw new FormatException($"S7 byte offset in '{original}' must be non-negative");

        // No bit-suffix: done unless size is Bit with no prefix, which requires one.
        if (offsetEnd == s.Length)
        {
            if (size == S7Size.Bit)
                throw new FormatException($"S7 address '{original}' needs a .{{bit}} suffix for bit access");
            return (byteOffset, 0);
        }

        if (s[offsetEnd] != '.')
            throw new FormatException($"S7 address '{original}' has unexpected character after offset");

        if (size != S7Size.Bit)
            throw new FormatException($"S7 address '{original}' has a bit suffix but the size is {size} — bit access needs X (DB) or no size prefix (M/I/Q)");

        if (!int.TryParse(s.AsSpan(offsetEnd + 1), out var bitOffset) || bitOffset is < 0 or > 7)
            throw new FormatException($"S7 bit offset in '{original}' must be 0-7");

        return (byteOffset, bitOffset);
    }
}