lmxopcua/src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Modbus.Addressing/ModbusAddressParser.cs

using System.Globalization;

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

/// <summary>
///     Parses the full Modbus tag-address grammar:
///     <c>&lt;region&gt;&lt;offset&gt;[.&lt;bit&gt;][:&lt;type&gt;[&lt;len&gt;]][:&lt;order&gt;][:&lt;count&gt;]</c>.
///     Output is a <see cref="ParsedModbusAddress"/> the driver-side config layer maps onto a
///     <c>ModbusTagDefinition</c>.
/// </summary>
/// <remarks>
///     <para>
///         The grammar mirrors industry conventions (Wonderware suffix style, Kepware/Modicon
///         digit prefixes, Ignition mnemonic prefixes — all accepted) so users can paste tag
///         spreadsheets from any of those tools without per-tag manual translation.
///     </para>
///     <para>
///         Examples (post-#146 type codes — verified against Wonderware DASMBTCP + Ignition):
///         <list type="bullet">
///             <item><c>40001</c> — HoldingRegisters[0], Int16 (default).</item>
///             <item><c>400001</c> — HoldingRegisters[0], Int16 (6-digit form).</item>
///             <item><c>40001.5</c> — bit 5 of HoldingRegisters[0].</item>
///             <item><c>40001:F</c> — Float32 starting at HR[0] (consumes HR[0..1]).</item>
///             <item><c>40001:F:CDAB</c> — same with word-swap byte order.</item>
///             <item><c>40001:STR20</c> — 20-char ASCII string.</item>
///             <item><c>HR1:I</c> — Int32 at HR[0] using mnemonic region (Wonderware-aligned).</item>
///             <item><c>40001:F:5</c> — Float32[5] array (consumes HR[0..9]).</item>
///             <item><c>40001:S::10</c> — Int16[10] using default byte order (empty order field).</item>
///             <item><c>C100</c> — Coils[99] (mnemonic).</item>
///         </list>
///     </para>
/// </remarks>
public static class ModbusAddressParser
{
    /// <summary>Parse an address string. Throws <see cref="FormatException"/> on invalid input.</summary>
    public static ParsedModbusAddress Parse(string address) => Parse(address, ModbusFamily.Generic, MelsecFamily.Q_L_iQR);

    /// <summary>Parse with a family hint (#144 family-native branch).</summary>
    public static ParsedModbusAddress Parse(string address, ModbusFamily family, MelsecFamily melsecSubFamily = MelsecFamily.Q_L_iQR)
    {
        if (TryParse(address, family, melsecSubFamily, out var parsed, out var error))
            return parsed!;
        throw new FormatException(error);
    }

    public static bool TryParse(string? address, out ParsedModbusAddress? result, out string? error)
        => TryParse(address, ModbusFamily.Generic, MelsecFamily.Q_L_iQR, out result, out error);

    /// <summary>
    ///     Try-parse with a family hint. When <paramref name="family"/> is non-Generic, the
    ///     parser tries the family-native form first (DL205 V-memory, MELSEC D-register, etc.)
    ///     and falls back to Modicon / mnemonic on miss. <paramref name="result"/> is null and
    ///     <paramref name="error"/> non-null on failure.
    /// </summary>
    public static bool TryParse(string? address, ModbusFamily family, MelsecFamily melsecSubFamily,
        out ParsedModbusAddress? result, out string? error)
    {
        result = null;

        if (string.IsNullOrWhiteSpace(address))
        {
            error = "Modbus address is null or empty";
            return false;
        }

        var s = address.Trim();

        // Split on ':' — the fields are: <region+offset>[.bit] :type :order :count.
        // Empty fields (e.g. "40001:I::5") are allowed and mean "use default."
        var parts = s.Split(':');
        if (parts.Length > 4)
        {
            error = $"Modbus address has too many ':'-separated fields ({parts.Length} > 4): '{address}'";
            return false;
        }

        var addressPart = parts[0];
        var typePart = parts.Length > 1 ? parts[1] : null;
        string? orderPart = null;
        string? countPart = null;

        // 3-field form is shorthand: <addr>:<type>:<X>. X is either a byte-order mnemonic
        // (4 letters — ABCD/CDAB/BADC/DCBA) or an array count (digits). Disambiguate by shape
        // so users can write 40001:F:5 for Float[5] without the awkward 40001:F::5. Anything
        // else surfaces a clear error in whichever slot it lands.
        if (parts.Length == 3)
        {
            // Driver.Modbus.Addressing-002: reject an empty 3rd field (e.g. "40001:F:") rather
            // than silently dropping it. Enumerable.All returns true for an empty sequence, so
            // without this guard the empty string would be classified as a valid array count and
            // then quietly ignored, leaving the user with no diagnostic for a typo'd trailing colon.
            if (parts[2].Length == 0)
            {
                error = $"3rd field is empty in '{address}' — use 4-field form '40001:F::5' to specify an array count with default byte order, or remove the trailing ':'";
                return false;
            }
            if (LooksLikeByteOrderToken(parts[2])) orderPart = parts[2];
            else if (parts[2].All(char.IsDigit)) countPart = parts[2];
            else
            {
                // Driver.Modbus.Addressing-003: when TryParseByteOrder would fail on a 4-letter
                // token that looks like a type code (e.g. BOOL), improve the diagnostic so the
                // user knows field 3 is a byte order and field 2 is the type.
                var mightBeTypeCode = parts[2].Length == 4 && parts[2].All(char.IsLetterOrDigit);
                error = mightBeTypeCode
                    ? $"3rd field '{parts[2]}' looks like a type code — type belongs in field 2 (e.g. '40001:BOOL'), not field 3. Field 3 must be a 4-letter byte order (ABCD/CDAB/BADC/DCBA) or a positive integer array count in '{address}'"
                    : $"3rd field '{parts[2]}' must be a 4-letter byte order (ABCD/CDAB/BADC/DCBA) or a positive integer array count in '{address}'";
                return false;
            }
        }
        else if (parts.Length == 4)
        {
            orderPart = parts[2];
            countPart = parts[3];
        }

        if (!TryParseRegionAndOffset(addressPart, family, melsecSubFamily, out var region, out var offset, out var bit, out error))
            return false;

        // Type field — defaults: Bool for Coils/DiscreteInputs, Int16 for InputRegisters/HoldingRegisters,
        // BitInRegister when bit-suffix is present.
        ModbusDataType dataType;
        ushort stringLen = 0;

        if (bit.HasValue)
        {
            // Bit suffix forces BitInRegister; explicit type would conflict.
            if (!string.IsNullOrEmpty(typePart))
            {
                error = $"Bit suffix '.{bit.Value}' cannot combine with explicit type ':{typePart}' in '{address}'";
                return false;
            }
            dataType = ModbusDataType.BitInRegister;
        }
        else if (string.IsNullOrEmpty(typePart))
        {
            dataType = region is ModbusRegion.Coils or ModbusRegion.DiscreteInputs
                ? ModbusDataType.Bool
                : ModbusDataType.Int16;
        }
        else
        {
            if (!TryParseType(typePart, out dataType, out stringLen, out error))
                return false;
        }

        // Region/type compatibility check — Coils and DiscreteInputs only carry Bool semantics.
        if (region is ModbusRegion.Coils or ModbusRegion.DiscreteInputs && dataType != ModbusDataType.Bool)
        {
            error = $"Region {region} only supports Bool-typed tags; got {dataType} in '{address}'";
            return false;
        }

        // Order field — defaults to BigEndian; only meaningful for multi-register types.
        var order = ModbusByteOrder.BigEndian;
        if (!string.IsNullOrEmpty(orderPart))
        {
            if (!TryParseByteOrder(orderPart, out order, out error))
                return false;
        }

        // Count field — array length. Bit + array is rejected.
        int? arrayCount = null;
        if (!string.IsNullOrEmpty(countPart))
        {
            if (bit.HasValue)
            {
                error = $"Bit suffix and array count cannot combine in '{address}'";
                return false;
            }
            if (!int.TryParse(countPart, NumberStyles.None, CultureInfo.InvariantCulture, out var parsedCount) || parsedCount < 1)
            {
                error = $"Array count must be a positive integer; got '{countPart}' in '{address}'";
                return false;
            }
            arrayCount = parsedCount;
        }

        result = new ParsedModbusAddress(region, offset, bit, dataType, stringLen, order, arrayCount);
        error = null;
        return true;
    }

    private static bool TryParseRegionAndOffset(string text, ModbusFamily family, MelsecFamily melsecSubFamily,
        out ModbusRegion region, out ushort offset, out byte? bit, out string? error)
    {
        region = default;
        offset = 0;
        bit = null;

        if (string.IsNullOrEmpty(text))
        {
            error = "Region/offset segment is empty";
            return false;
        }

        // Optional bit suffix: '.N' at the end, N in 0..15. Strip before parsing region/offset.
        // Driver.Modbus.Addressing-004: use LastIndexOf so a multi-dot input like "40001.5.3"
        // produces a descriptive error ("bit index '5.3' must be 0..15") rather than silently
        // parsing "5" as the bit and leaving ".3" as part of the address text. Also validate
        // the address segment is non-empty (a leading dot like ".5" is not a valid Modbus addr).
        var dotIdx = text.LastIndexOf('.');
        var addrText = dotIdx < 0 ? text : text[..dotIdx];
        if (dotIdx >= 0)
        {
            if (addrText.Length == 0)
            {
                error = $"Region/offset segment is empty before bit suffix '.{text[(dotIdx + 1)..]}' in '{text}'";
                return false;
            }
            // Assert exactly one dot: if the remaining address still contains a dot the
            // user typed something like "400.01.5" — give a precise "multiple dots" diagnostic.
            if (addrText.Contains('.'))
            {
                error = $"Address segment '{addrText}' contains multiple dots; expected at most one '.bit' suffix in '{text}'";
                return false;
            }
            var bitText = text[(dotIdx + 1)..];
            if (!byte.TryParse(bitText, NumberStyles.None, CultureInfo.InvariantCulture, out var bitVal) || bitVal > 15)
            {
                error = $"Bit index must be 0..15; got '{bitText}'";
                return false;
            }
            bit = bitVal;
        }

        // Family-native branch (#144) — when a non-Generic family is configured, try its native
        // syntax first. Successful native parse wins; failure falls through to Modicon / mnemonic.
        // The order matters for cross-family ambiguity: DL205 'C100' is a control relay, not a
        // Modicon coil, when the user has explicitly selected DL205.
        string? familyNativeError = null;
        if (family != ModbusFamily.Generic)
        {
            if (TryParseFamilyNative(addrText, family, melsecSubFamily, out region, out offset, out familyNativeError))
            {
                error = null;
                return true;
            }
        }

        // Try mnemonic prefix first (HR, IR, C, DI). Cheaper than the digit branch and
        // unambiguous when present.
        if (TryParseMnemonicAddress(addrText, out region, out offset, out error))
            return true;

        // Fall back to Modicon (5/6-digit). Reuses #136's parser.
        if (ModbusModiconAddress.TryParse(addrText, out region, out offset, out error))
            return true;

        // Driver.Modbus.Addressing-005: when a non-Generic family was configured and the
        // family-native parser set a specific error (meaning the address matched a recognised
        // family prefix but the value was invalid, e.g. "contains non-octal digit"), prefer
        // that error over the generic Modicon fallback diagnostic, which otherwise says
        // "must be 5 or 6 digits" for something the user clearly intended as a V-address.
        if (familyNativeError is not null)
            error = familyNativeError;

        return false;
    }

    private static bool TryParseFamilyNative(string text, ModbusFamily family, MelsecFamily melsecSubFamily,
        out ModbusRegion region, out ushort offset, out string? error)
    {
        region = default;
        offset = 0;
        error = null;

        try
        {
            switch (family)
            {
                case ModbusFamily.DL205:
                    // V-memory → HoldingRegisters; Y → Coils; C → Coils (relays); X → DiscreteInputs;
                    // SP → DiscreteInputs (special relays).
                    if (text.StartsWith("V", StringComparison.OrdinalIgnoreCase))
                    {
                        // VMemoryToPdu routes user vs system V-memory: the system bank (octal
                        // >= V40400) is relocated to PDU 0x2100, NOT a plain octal decode.
                        offset = DirectLogicAddress.VMemoryToPdu(text);
                        region = ModbusRegion.HoldingRegisters;
                        return true;
                    }
                    if (text.StartsWith("Y", StringComparison.OrdinalIgnoreCase))
                    {
                        offset = DirectLogicAddress.YOutputToCoil(text);
                        region = ModbusRegion.Coils;
                        return true;
                    }
                    if (text.StartsWith("C", StringComparison.OrdinalIgnoreCase))
                    {
                        offset = DirectLogicAddress.CRelayToCoil(text);
                        region = ModbusRegion.Coils;
                        return true;
                    }
                    if (text.StartsWith("X", StringComparison.OrdinalIgnoreCase))
                    {
                        offset = DirectLogicAddress.XInputToDiscrete(text);
                        region = ModbusRegion.DiscreteInputs;
                        return true;
                    }
                    if (text.StartsWith("SP", StringComparison.OrdinalIgnoreCase))
                    {
                        offset = DirectLogicAddress.SpecialToDiscrete(text);
                        region = ModbusRegion.DiscreteInputs;
                        return true;
                    }
                    return false;

                case ModbusFamily.MELSEC:
                    // D-registers → HoldingRegisters; X → DiscreteInputs; Y → Coils; M → Coils.
                    // The MelsecAddress helpers honour the sub-family (Q hex vs F octal) and use
                    // bank base 0; users with non-zero assignment bases must use the structured
                    // tag form to override. The grammar string covers the common base-0 path.
                    if (text.StartsWith("D", StringComparison.OrdinalIgnoreCase))
                    {
                        offset = MelsecAddress.DRegisterToHolding(text);
                        region = ModbusRegion.HoldingRegisters;
                        return true;
                    }
                    if (text.StartsWith("X", StringComparison.OrdinalIgnoreCase))
                    {
                        offset = MelsecAddress.XInputToDiscrete(text, melsecSubFamily);
                        region = ModbusRegion.DiscreteInputs;
                        return true;
                    }
                    if (text.StartsWith("Y", StringComparison.OrdinalIgnoreCase))
                    {
                        offset = MelsecAddress.YOutputToCoil(text, melsecSubFamily);
                        region = ModbusRegion.Coils;
                        return true;
                    }
                    if (text.StartsWith("M", StringComparison.OrdinalIgnoreCase))
                    {
                        offset = MelsecAddress.MRelayToCoil(text);
                        region = ModbusRegion.Coils;
                        return true;
                    }
                    return false;

                default:
                    return false;
            }
        }
        catch (Exception ex) when (ex is ArgumentException or OverflowException)
        {
            error = $"Family-native parse for {family} failed on '{text}': {ex.Message}";
            return false;
        }
    }

    private static bool TryParseMnemonicAddress(string text, out ModbusRegion region, out ushort offset, out string? error)
    {
        region = default;
        offset = 0;
        error = null;

        // Mnemonic = letter prefix + 1-based register number. We require pure-digit suffix
        // after the prefix; anything else (including the Modicon-digit forms) falls through
        // to the Modicon parser.
        (string Prefix, ModbusRegion Region)[] candidates =
        [
            ("HR", ModbusRegion.HoldingRegisters),
            ("IR", ModbusRegion.InputRegisters),
            ("DI", ModbusRegion.DiscreteInputs),
            ("C",  ModbusRegion.Coils),
        ];

        foreach (var (prefix, mnemonicRegion) in candidates)
        {
            if (!text.StartsWith(prefix, StringComparison.OrdinalIgnoreCase)) continue;
            var rest = text[prefix.Length..];
            if (rest.Length == 0 || !rest.All(char.IsDigit))
            {
                // Prefix matched but body is non-numeric — not a mnemonic address.
                continue;
            }
            if (!int.TryParse(rest, NumberStyles.None, CultureInfo.InvariantCulture, out var n) || n < 1 || n > 65536)
            {
                error = $"Mnemonic register number must be 1..65536; got '{rest}'";
                return false;
            }
            region = mnemonicRegion;
            offset = (ushort)(n - 1);
            return true;
        }

        return false;
    }

    private static bool TryParseType(string text, out ModbusDataType type, out ushort stringLen, out string? error)
    {
        type = default;
        stringLen = 0;
        error = null;

        // STR<n> — string length glued to the type code.
        if (text.StartsWith("STR", StringComparison.OrdinalIgnoreCase))
        {
            var lenText = text[3..];
            if (lenText.Length == 0)
            {
                error = "STR type requires a length: STR<n>";
                return false;
            }
            if (!ushort.TryParse(lenText, NumberStyles.None, CultureInfo.InvariantCulture, out var len) || len < 1)
            {
                error = $"STR length must be a positive integer; got '{lenText}'";
                return false;
            }
            type = ModbusDataType.String;
            stringLen = len;
            return true;
        }

        // #146 — codes aligned with Wonderware DASMBTCP + Ignition Modbus driver after the
        // 2026-04-25 vendor-doc verification:
        //   - `:I` is Int32 (Wonderware: "letter 'I' follow ... 32-bit signed quantity, two
        //     consecutive registers"). Ignition's HRI is also Int32. The pre-#146 mapping
        //     `:I` = Int16 silently produced wrong-typed data + offset-shifted neighbours when
        //     a tag spreadsheet was pasted from another vendor.
        //   - `:S` is the explicit Int16 code (Wonderware: "letter 'S' ... 16-bit signed").
        //   - `:US` is UInt16 (Ignition: HRUS = "Unsigned Short").
        //   - `:UI` is UInt32 (parallel to `:I` shape; matches Ignition HRUI).
        //   - `:I_64` / `:UI_64` for 64-bit (Ignition HRI_64 / HRUI_64 underscore-N convention).
        //   - `:BCD_32` for 32-bit BCD (Ignition HRBCD_32). The pre-#146 `:LBCD` is dropped.
        //   - HR/IR with no explicit type still default to Int16 (matches Ignition `HR`).
        type = text.ToUpperInvariant() switch
        {
            "BOOL" => ModbusDataType.Bool,
            "S" => ModbusDataType.Int16,
            "US" => ModbusDataType.UInt16,
            "I" => ModbusDataType.Int32,
            "UI" => ModbusDataType.UInt32,
            "I_64" => ModbusDataType.Int64,
            "UI_64" => ModbusDataType.UInt64,
            "F" => ModbusDataType.Float32,
            "D" => ModbusDataType.Float64,
            "BCD" => ModbusDataType.Bcd16,
            "BCD_32" => ModbusDataType.Bcd32,
            _ => (ModbusDataType)(-1),
        };

        if ((int)type == -1)
        {
            error = $"Unknown type code '{text}'. Valid: BOOL, S, US, I, UI, I_64, UI_64, F, D, BCD, BCD_32, STR<n>";
            return false;
        }

        return true;
    }

    private static bool LooksLikeByteOrderToken(string text) =>
        text.Length == 4 && text.All(char.IsLetter);

    private static bool TryParseByteOrder(string text, out ModbusByteOrder order, out string? error)
    {
        order = ModbusByteOrder.BigEndian;
        error = null;

        order = text.ToUpperInvariant() switch
        {
            "ABCD" => ModbusByteOrder.BigEndian,
            "CDAB" => ModbusByteOrder.WordSwap,
            "BADC" => ModbusByteOrder.ByteSwap,
            "DCBA" => ModbusByteOrder.FullReverse,
            _ => (ModbusByteOrder)(-1),
        };

        if ((int)order == -1)
        {
            error = $"Unknown byte order '{text}'. Valid: ABCD, CDAB, BADC, DCBA";
            return false;
        }

        return true;
    }
}

/// <summary>
///     Result of parsing a Modbus tag-address string. Maps directly onto the driver-side
///     <c>ModbusTagDefinition</c> at config-bind time.
/// </summary>
/// <param name="Region">Coils / DiscreteInputs / InputRegisters / HoldingRegisters.</param>
/// <param name="Offset">Zero-based PDU offset.</param>
/// <param name="Bit">When non-null, the tag is a single-bit-in-register selector (0..15).</param>
/// <param name="DataType">Inferred from explicit type code or region default.</param>
/// <param name="StringLength">Character count for <see cref="ModbusDataType.String"/>; zero otherwise.</param>
/// <param name="ByteOrder">Word/byte ordering for multi-register types.</param>
/// <param name="ArrayCount">Element count when the tag is an array; null for scalars.</param>
public sealed record ParsedModbusAddress(
    ModbusRegion Region,
    ushort Offset,
    byte? Bit,
    ModbusDataType DataType,
    ushort StringLength,
    ModbusByteOrder ByteOrder,
    int? ArrayCount);