namespace ZB.MOM.WW.OtOpcUa.Driver.AbLegacy.Import;

/// <summary>
///     Materialises <see cref="AbLegacyTagDefinition"/> entries from a RSLogix export. v1 ships
///     a single implementation (<see cref="RsLogixSymbolImport"/>) for text/CSV "Database
///     Export" — RSLogix 500's <c>.RSS</c> and RSLogix 5's <c>.RSP</c> binary project files are
///     proprietary and out of scope (no parser ships with libplctag or any community library at
///     the time of writing). The interface exists so a binary parser can slot in later without
///     reshaping the call sites.
/// </summary>
/// <remarks>
///     <para>
///         The <c>deviceHostAddress</c> parameter on <see cref="Parse"/> is required because RSLogix
///         exports list addresses scoped to a single PLC; the importer needs to stamp every
///         resulting tag with the gateway address that the runtime layer will use to reach
///         it. Multi-device deployments call the importer once per device, then concatenate.
///     </para>
///     <para>
///         <see cref="Parse"/> never throws on parse errors when
///         <see cref="ImportOptions.IgnoreInvalid"/> is <c>true</c> (default) — malformed rows
///         are skipped with a structured warning logged via the importer's <c>ILogger</c>, and
///         the counts surface on <see cref="RsLogixImportResult"/>. With
///         <see cref="ImportOptions.IgnoreInvalid"/> set to <c>false</c> the first malformed row
///         throws <see cref="System.IO.InvalidDataException"/>.
///     </para>
/// </remarks>
public interface IRsLogixImporter
{
    /// <summary>
    ///     Read the entire <paramref name="stream"/> and emit one
    ///     <see cref="AbLegacyTagDefinition"/> per recognised symbol row.
    /// </summary>
    /// <param name="stream">Open, readable stream over the RSLogix export. Caller owns it.</param>
    /// <param name="deviceHostAddress">
    ///     Canonical AB Legacy gateway URI (<c>ab://host[:port]/cip-path</c>) the resulting
    ///     tags should bind to.
    /// </param>
    /// <param name="options">Filter + safety knobs; <c>null</c> ≡ default options.</param>
    RsLogixImportResult Parse(Stream stream, string deviceHostAddress, ImportOptions? options = null);
}