cadstar_archive_parser.h

Go to the documentation of this file.

/*
 * This program source code file is part of KiCad, a free EDA CAD application.
 *
 * Copyright (C) 2020-2021 Roberto Fernandez Bautista <[email protected]>
 * Copyright The KiCad Developers, see AUTHORS.txt for contributors.
 *
 * This program is free software: you can redistribute it and/or modify it
 * under the terms of the GNU General Public License as published by the
 * Free Software Foundation, either version 3 of the License, or (at your
 * option) any later version.
 *
 * This program is distributed in the hope that it will be useful, but
 * WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program.  If not, see <https://www.gnu.org/licenses/>.
 */

 
#ifndef CADSTAR_ARCHIVE_PARSER_H_
#define CADSTAR_ARCHIVE_PARSER_H_
 
#include <richio.h>
#include <wx/string.h>
#include <functional>
#include <map>
#include <set>
#include <vector>
#include <xnode.h>
 
#include <math/vector2d.h>
#include <io/cadstar/cadstar_archive_objects.h>
#include <trace_helpers.h>
 
// THROW_IO_ERROR definitions to ensure consistent wording is used in the error messages
 
#define THROW_MISSING_NODE_IO_ERROR( nodename, location ) \
    THROW_IO_ERROR( wxString::Format( _( "Missing node '%s' in '%s'" ), nodename, location ) )
 
#define THROW_UNKNOWN_NODE_IO_ERROR( nodename, location ) \
    THROW_IO_ERROR( wxString::Format( _( "Unknown node '%s' in '%s'" ), nodename, location ) )
 
#define THROW_MISSING_PARAMETER_IO_ERROR( param, location ) \
    THROW_IO_ERROR( wxString::Format( _( "Missing Parameter '%s' in '%s'" ), param, location ) )
 
#define THROW_UNKNOWN_PARAMETER_IO_ERROR( param, location ) \
    THROW_IO_ERROR( wxString::Format( _( "Unknown Parameter '%s' in '%s'" ), param, location ) )
 
#define THROW_PARSING_IO_ERROR( param, location ) \
    THROW_IO_ERROR( wxString::Format( _( "Unable to parse '%s' in '%s'" ), param, location ) )
 
// Trace variants that log instead of throwing, allowing import to continue when encountering
// unknown nodes from newer CADSTAR versions. These are developer diagnostics rather than
// anything the user can act on, so they stay silent unless KICAD_CADSTAR_IO is traced.
 
#define WARN_UNKNOWN_NODE_IO_ERROR( nodename, location ) \
    wxLogTrace( traceCadstarIo, wxT( "Unknown node '%s' in '%s'" ), nodename, location )
 
#define WARN_UNKNOWN_PARAMETER_IO_ERROR( param, location ) \
    wxLogTrace( traceCadstarIo, wxT( "Unknown Parameter '%s' in '%s'" ), param, location )
 
//=================================
// MACRO DEFINITIONS
//=================================
#define UNDEFINED_LAYER_ID ( LAYER_ID ) wxEmptyString
 

#define COMPONENT_NAME_ATTRID ( ATTRIBUTE_ID ) wxT( "__COMPONENT_NAME__" )

#define COMPONENT_NAME_2_ATTRID ( ATTRIBUTE_ID ) wxT( "__COMPONENT_NAME_2__" )

#define SYMBOL_NAME_ATTRID ( ATTRIBUTE_ID ) wxT( "__SYMBOL_NAME__" )
#define LINK_ORIGIN_ATTRID ( ATTRIBUTE_ID ) wxT( "__LINK_ORIGIN__" )
#define SIGNALNAME_ORIGIN_ATTRID ( ATTRIBUTE_ID ) wxT( "__SIGNALNAME_ORIGIN__" )
#define PART_NAME_ATTRID ( ATTRIBUTE_ID ) wxT( "__PART_NAME__" )
 
class EDA_TEXT;
class wxXmlAttribute;
class PROGRESS_REPORTER;
class SHAPE_LINE_CHAIN;
class SHAPE_POLY_SET;
class SHAPE_ARC;

class CADSTAR_ARCHIVE_PARSER
{
public:
    CADSTAR_ARCHIVE_PARSER() { m_progressReporter = nullptr; }
 
    virtual ~CADSTAR_ARCHIVE_PARSER() {}
 
 
    typedef wxString LINECODE_ID;
    typedef wxString HATCHCODE_ID;
    typedef wxString ROUTECODE_ID;
    typedef wxString NETCLASS_ID;
    typedef wxString SPACING_CLASS_ID;
    typedef wxString TEXTCODE_ID;
    typedef wxString LAYER_ID; 
    typedef wxString VARIANT_ID;
    typedef wxString ATTRIBUTE_ID;
    typedef wxString SYMDEF_ID;
    typedef wxString PART_ID;
    typedef wxString GATE_ID;
    typedef long     TERMINAL_ID;            
    typedef long     PART_DEFINITION_PIN_ID; 
    typedef long     PART_PIN_ID;            
    typedef wxString TEXT_ID;
    typedef wxString FIGURE_ID;
    typedef wxString GROUP_ID;
    typedef wxString REUSEBLOCK_ID;
    typedef wxString NET_ID;
    typedef wxString NETELEMENT_ID;
    typedef wxString DOCUMENTATION_SYMBOL_ID;
    typedef wxString COLOR_ID;
 
    static const long UNDEFINED_VALUE = -1;

    static const double TXT_HEIGHT_RATIO;

    enum class TEXT_FIELD_NAME
    {
        DESIGN_TITLE,
        SHORT_JOBNAME,
        LONG_JOBNAME,
        NUM_OF_SHEETS,
        SHEET_NUMBER,
        SHEET_NAME,
        VARIANT_NAME,
        VARIANT_DESCRIPTION,
        REG_USER,
        COMPANY_NAME,
        CURRENT_USER,
        DATE,
        TIME,
        MACHINE_NAME,
        FROM_FILE,
        DISTANCE,
        UNITS_SHORT,
        UNITS_ABBREV,
        UNITS_FULL,
        HYPERLINK,
        NONE 
    };

    static const std::map<TEXT_FIELD_NAME, wxString> CADSTAR_TO_KICAD_FIELDS;
 
 
    struct PARSER_CONTEXT
    {
        std::map<wxString, wxString> FilenamesToTextMap;

        std::map<wxString, wxString> TextToHyperlinksMap;

        std::map<TEXT_FIELD_NAME, wxString> TextFieldToValuesMap;

        std::set<TEXT_FIELD_NAME> InconsistentTextFields;

        std::function<void()> CheckPointCallback = []() {};
    };

    static wxString ParseTextFields( const wxString& aTextString, PARSER_CONTEXT* aParserContext );
 
 
    struct PARSER
    {
        virtual void Parse( XNODE* aNode, PARSER_CONTEXT* aContext ) = 0;
 
        virtual ~PARSER() {};
    };
 
 
    struct FORMAT : PARSER
    {
        wxString Type;
        long     SomeInt; 
        long     Version; 
        void Parse( XNODE* aNode, PARSER_CONTEXT* aContext ) override;
    };
 
 
    struct TIMESTAMP : PARSER
    {
        long Year;
        long Month;
        long Day;
        long Hour;
        long Minute;
        long Second;
 
        void Parse( XNODE* aNode, PARSER_CONTEXT* aContext ) override;
    };
 
    //Note: there are possibly several other resolutions, but HUNDREDTH MICRON is only one known
    enum class RESOLUTION
    {
        HUNDREDTH_MICRON
    };
 
 
    struct HEADER : PARSER
    {
        FORMAT     Format;
        wxString   JobFile;
        wxString   JobTitle;
        wxString   Generator;
        RESOLUTION Resolution;
        TIMESTAMP  Timestamp;
 
        void Parse( XNODE* aNode, PARSER_CONTEXT* aContext ) override;
    };
 
 
    struct VARIANT : PARSER 
    {
        VARIANT_ID ID          = wxEmptyString;
        VARIANT_ID ParentID    = wxEmptyString; 
        wxString   Name        = wxEmptyString;
        wxString   Description = wxEmptyString;
 
        void Parse( XNODE* aNode, PARSER_CONTEXT* aContext ) override;
    };
 
 
    struct VARIANT_HIERARCHY : PARSER
    {
        std::map<VARIANT_ID, VARIANT> Variants;
 
        void Parse( XNODE* aNode, PARSER_CONTEXT* aContext ) override;
    };
 
 
    enum class LINESTYLE
    {
        SOLID,
        DASH,
        DASHDOT,
        DASHDOTDOT,
        DOT
    };
 
 
    struct LINECODE : PARSER
    {
        LINECODE_ID ID;
        wxString    Name;
        long        Width;
        LINESTYLE   Style = LINESTYLE::SOLID;
 
        void Parse( XNODE* aNode, PARSER_CONTEXT* aContext ) override;
    };
 
 
    struct HATCH : PARSER
    {
        long Step;
        long LineWidth;
        long OrientAngle; 
 
        void Parse( XNODE* aNode, PARSER_CONTEXT* aContext ) override;
    };
 
 
    struct HATCHCODE : PARSER
    {
        HATCHCODE_ID       ID;
        wxString           Name;
        std::vector<HATCH> Hatches;
 
        void Parse( XNODE* aNode, PARSER_CONTEXT* aContext ) override;
    };
 
 
    static const long FONT_NORMAL = 400;
    static const long FONT_BOLD   = 700;
 
 
    struct FONT : PARSER
    {
        wxString Name  = wxT( "CADSTAR" );
        long Modifier1 = FONT_NORMAL; 
        long Modifier2 = 0;           
        bool KerningPairs = false;    
        bool Italic = false;
 
        void Parse( XNODE* aNode, PARSER_CONTEXT* aContext ) override;
    };
 
 
    struct TEXTCODE : PARSER
    {
        TEXTCODE_ID ID;
        wxString    Name;
        long        LineWidth;
        long        Height;
        long        Width; 
        FONT        Font;
 
        void Parse( XNODE* aNode, PARSER_CONTEXT* aContext ) override;
    };
 
 
    struct ROUTEREASSIGN : PARSER
    {
        LAYER_ID LayerID;
        long     OptimalWidth;
        long     MinWidth;
        long     MaxWidth;
        long     NeckedWidth;
 
        void Parse( XNODE* aNode, PARSER_CONTEXT* aContext ) override;
    };
 
 
    struct ROUTECODE : PARSER
    {
        ROUTECODE_ID ID;
        wxString     Name;
        long         OptimalWidth;
        long         MinWidth;
        long         MaxWidth;
        long         NeckedWidth;
 
        std::vector<ROUTEREASSIGN> RouteReassigns;
 
        void Parse( XNODE* aNode, PARSER_CONTEXT* aContext ) override;
    };
 

    struct EVALUE : PARSER
    {
        long Base     = 0;
        long Exponent = 0;
 
        void   Parse( XNODE* aNode, PARSER_CONTEXT* aContext ) override;
        double GetDouble();
    };

    struct POINT : VECTOR2I, PARSER
    {
        POINT() : VECTOR2I( UNDEFINED_VALUE, UNDEFINED_VALUE ) {}
        POINT( int aX, int aY ) : VECTOR2I( aX, aY ) {}
 
        void Parse( XNODE* aNode, PARSER_CONTEXT* aContext ) override;
    };
 
 
    struct LONGPOINT : PARSER
    {
        long x = UNDEFINED_VALUE;
        long y = UNDEFINED_VALUE;
 
        void Parse( XNODE* aNode, PARSER_CONTEXT* aContext ) override;
    };
 
 
    struct TRANSFORM
    {
        virtual VECTOR2I Apply( POINT aCadstarPoint ) = 0;
    };
 
 
    enum class VERTEX_TYPE
    {
        VT_POINT,
        CLOCKWISE_ARC,
        CLOCKWISE_SEMICIRCLE,
        ANTICLOCKWISE_ARC,
        ANTICLOCKWISE_SEMICIRCLE
    };

    struct VERTEX : PARSER
    {
        VERTEX( VERTEX_TYPE aType = VERTEX_TYPE::VT_POINT, POINT aEnd = POINT(), POINT aCenter = POINT() ) :
                Type( aType ),
                End( aEnd ),
                Center( aCenter )
        {}
 
        VERTEX_TYPE Type;
        POINT       End;
        POINT       Center;
 
        static bool IsVertex( XNODE* aNode );
        void        Parse( XNODE* aNode, PARSER_CONTEXT* aContext ) override;
 
        void AppendToChain( SHAPE_LINE_CHAIN* aChainToAppendTo,
                            const std::function<VECTOR2I( const VECTOR2I& )> aCadstarToKicadPointCallback,
                            int aAccuracy ) const;
 
        SHAPE_ARC BuildArc( const VECTOR2I& aPrevPoint,
                            const std::function<VECTOR2I( const VECTOR2I& )> aCadstarToKicadPointCallback ) const;
    };

    struct CUTOUT : PARSER
    {
        std::vector<VERTEX> Vertices;
 
        void Parse( XNODE* aNode, PARSER_CONTEXT* aContext ) override;
    };
 
 
    enum class SHAPE_TYPE
    {
        OPENSHAPE, 
        OUTLINE,   
        SOLID,     
        HATCHED    
    };
 
 
    struct SHAPE : PARSER
    {
        SHAPE_TYPE          Type;
        std::vector<VERTEX> Vertices;
        std::vector<CUTOUT> Cutouts;     
        wxString            HatchCodeID; 
 
        static bool IsShape( XNODE* aNode );
        void        Parse( XNODE* aNode, PARSER_CONTEXT* aContext ) override;
 
        SHAPE_LINE_CHAIN OutlineAsChain( const std::function<VECTOR2I( const VECTOR2I& )> aCadstarToKicadPointCallback,
                                         int aAccuracy ) const;
 
        SHAPE_POLY_SET ConvertToPolySet( const std::function<VECTOR2I( const VECTOR2I& )> aCadstarToKicadPointCallback,
                                         int aAccuracy  ) const;
    };
 
 
    enum class UNITS
    {
        DESIGN, 
        THOU,
        INCH,
        MICROMETRE,
        MM,
        CENTIMETER,
        METER
    };
 
 
    static UNITS ParseUnits( XNODE* aNode );
 
 
    enum class ANGUNITS
    {
        DEGREES,
        RADIANS
    };
 
 
    static ANGUNITS ParseAngunits( XNODE* aNode );
 
 
    enum class GRID_TYPE
    {
        FRACTIONALGRID, 
        STEPGRID        
    };
 
 
    struct GRID : PARSER
    {
        GRID_TYPE Type;
        wxString  Name;
        long      Param1; 
        long      Param2; 
 
        static bool IsGrid( XNODE* aNode );
        void        Parse( XNODE* aNode, PARSER_CONTEXT* aContext ) override;
    };
 
 
    struct GRIDS : PARSER
    {
        GRID WorkingGrid;
        GRID ScreenGrid;             
        std::vector<GRID> UserGrids; 
 
        void Parse( XNODE* aNode, PARSER_CONTEXT* aContext ) override;
    };
 
 
    struct SETTINGS : PARSER
    {
        UNITS Units;                  
        long  UnitDisplPrecision;     
        long  InterlineGap;           
        long BarlineGap;              
        bool AllowBarredText = false; 
        long AngularPrecision; 
 
        long PinNoOffset; 
        long PinNoAngle; 
 
        LONGPOINT               DesignOrigin;
        std::pair<POINT, POINT> DesignArea;
        LONGPOINT               DesignRef; 
        LONGPOINT               DesignLimit;
 
        bool         ParseSubNode( XNODE* aChildNode, PARSER_CONTEXT* aContext );
        virtual void Parse( XNODE* aNode, PARSER_CONTEXT* aContext ) override;
    };
 
 

    enum class ALIGNMENT
    {
        NO_ALIGNMENT, 
        TOPLEFT,
        TOPCENTER,
        TOPRIGHT,
        CENTERLEFT,
        CENTERCENTER,
        CENTERRIGHT,
        BOTTOMLEFT,
        BOTTOMCENTER,
        BOTTOMRIGHT
    };
 
 
    static ALIGNMENT ParseAlignment( XNODE* aNode );

    enum class JUSTIFICATION
    {
        LEFT,
        CENTER,
        RIGHT
    };
 
 
    static JUSTIFICATION ParseJustification( XNODE* aNode );

    enum class READABILITY
    {
        BOTTOM_TO_TOP, 
        TOP_TO_BOTTOM  
    };
 
 
    static READABILITY ParseReadability( XNODE* aNode );
 
 
    enum class ATTROWNER
    {
        ALL_ITEMS,
        AREA,
        BOARD,
        COMPONENT,
        CONNECTION,
        COPPER,
        DOCSYMBOL,
        FIGURE,
        NET,
        NETCLASS,
        PART,            
        PART_DEFINITION, 
        PIN,
        SIGNALREF,
        SYMBOL,
        SYMDEF,
        TEMPLATE,
        TESTPOINT
    };
 
 
    enum class ATTRUSAGE
    {
        BOTH,      
        COMPONENT, 
        PART_DEFINITION, 
        PART_LIBRARY,    
        SYMBOL,          
        UNDEFINED 
    };
 
 
    struct ATTRIBUTE_LOCATION : PARSER
    {
        TEXTCODE_ID   TextCodeID;
        LAYER_ID      LayerID;
        POINT         Position;
        long          OrientAngle = 0;
        bool          Mirror      = false;
        bool          Fixed       = false;
        JUSTIFICATION Justification =
                JUSTIFICATION::LEFT; 
        ALIGNMENT Alignment = ALIGNMENT::
                NO_ALIGNMENT; 
 
        void         ParseIdentifiers( XNODE* aNode, PARSER_CONTEXT* aContext );
        bool         ParseSubNode( XNODE* aChildNode, PARSER_CONTEXT* aContext );
        virtual void Parse( XNODE* aNode, PARSER_CONTEXT* aContext ) override;
    };
 

    struct ATTRNAME : PARSER
    {
        struct COLUMNORDER : PARSER
        {
            long ID;
            long Order;
 
            void Parse( XNODE* aNode, PARSER_CONTEXT* aContext ) override;
        };
 
 
        struct COLUMNWIDTH : PARSER
        {
            long ID;
            long Width;
 
            void Parse( XNODE* aNode, PARSER_CONTEXT* aContext ) override;
        };
 
        ATTRIBUTE_ID ID;
        wxString     Name; 
        ATTROWNER AttributeOwner = ATTROWNER::ALL_ITEMS;
        ATTRUSAGE AttributeUsage = ATTRUSAGE::UNDEFINED;
        bool      NoTransfer     = false; 
        std::vector<COLUMNORDER> ColumnOrders;
        std::vector<COLUMNWIDTH> ColumnWidths;
        bool                     ColumnInvisible = false;
 
        void Parse( XNODE* aNode, PARSER_CONTEXT* aContext ) override;
    };
 
 
    struct ATTRIBUTE_VALUE : PARSER
    {
        ATTRIBUTE_ID AttributeID;
        wxString     Value;
        bool         ReadOnly    = false;
        bool         HasLocation = false; 
        ATTRIBUTE_LOCATION AttributeLocation;
 
        void Parse( XNODE* aNode, PARSER_CONTEXT* aContext ) override;
    };
 

    struct TEXT_LOCATION : ATTRIBUTE_LOCATION
    {
        TEXT_LOCATION()
        {
            // The default alignment for TEXT_LOCATION (when "NO_ALIGNMENT" is selected) is
            // Bottom left, matching CADSTAR's default behavior
            Alignment = ALIGNMENT::BOTTOMLEFT;
        }
        ATTRIBUTE_ID AttributeID;
 
        void Parse( XNODE* aNode, PARSER_CONTEXT* aContext ) override;
    };
 
 
    struct CADSTAR_NETCLASS : PARSER
    {
        NETCLASS_ID                  ID;
        wxString                     Name;
        std::vector<ATTRIBUTE_VALUE> Attributes;
 
        void Parse( XNODE* aNode, PARSER_CONTEXT* aContext ) override;
    };
 
 
    struct SPCCLASSNAME : PARSER
    {
        SPACING_CLASS_ID ID;
        wxString         Name;
 
        void Parse( XNODE* aNode, PARSER_CONTEXT* aContext ) override;
    };
 
 
    struct CODEDEFS : PARSER
    {
        std::map<LINECODE_ID, LINECODE>          LineCodes;
        std::map<HATCHCODE_ID, HATCHCODE>        HatchCodes;
        std::map<TEXTCODE_ID, TEXTCODE>          TextCodes;
        std::map<ROUTECODE_ID, ROUTECODE>        RouteCodes;
        std::map<ATTRIBUTE_ID, ATTRNAME>         AttributeNames;
        std::map<NETCLASS_ID, CADSTAR_NETCLASS>  NetClasses;
        std::map<SPACING_CLASS_ID, SPCCLASSNAME> SpacingClassNames;
 
        bool ParseSubNode( XNODE* aChildNode, PARSER_CONTEXT* aContext );
    };

    enum class SWAP_RULE
    {
        NO_SWAP,        
        USE_SWAP_LAYER, 
        BOTH            
    };
 
 
    static SWAP_RULE ParseSwapRule( XNODE* aNode );
 
 
    struct REUSEBLOCK : PARSER
    {
        REUSEBLOCK_ID ID;
        wxString      Name;
        wxString FileName; 
        bool     Mirror      = false;
        long     OrientAngle = 0;
 
        void Parse( XNODE* aNode, PARSER_CONTEXT* aContext ) override;
    };
 

    struct REUSEBLOCKREF : PARSER
    {
        REUSEBLOCK_ID ReuseBlockID = wxEmptyString;
        wxString ItemReference = wxEmptyString; 
 
        bool IsEmpty(); 
        void Parse( XNODE* aNode, PARSER_CONTEXT* aContext ) override;
    };
 
 
    struct GROUP : PARSER
    {
        GROUP_ID ID;
        wxString Name;
        bool     Fixed    = false;
        bool     Transfer = false;         
        GROUP_ID GroupID  = wxEmptyString; 
        REUSEBLOCKREF ReuseBlockRef;
 
        void Parse( XNODE* aNode, PARSER_CONTEXT* aContext ) override;
    };
 
 
    struct FIGURE : PARSER
    {
        FIGURE_ID   ID;
        LINECODE_ID LineCodeID;
        LAYER_ID    LayerID;
        SHAPE       Shape; //< Uses the component's coordinate frame if within a component
                           //< definition, otherwise uses the design's coordinate frame.
        GROUP_ID      GroupID = wxEmptyString; 
        REUSEBLOCKREF ReuseBlockRef;
        SWAP_RULE     SwapRule = SWAP_RULE::BOTH; 
        bool          Fixed    = false;
        std::map<ATTRIBUTE_ID, ATTRIBUTE_VALUE> AttributeValues;
 
        void Parse( XNODE* aNode, PARSER_CONTEXT* aContext ) override;
    };
 
 
    struct TEXT : PARSER
    {
        TEXT_ID       ID;
        wxString      Text; //TODO: Need to lex/parse to identify design fields and hyperlinks
        TEXTCODE_ID   TextCodeID;
        LAYER_ID      LayerID;
        POINT         Position;
        long          OrientAngle   = 0;
        bool          Mirror        = false;
        bool          Fixed         = false;
        SWAP_RULE     SwapRule      = SWAP_RULE::BOTH;
        JUSTIFICATION Justification = JUSTIFICATION::LEFT;     
        ALIGNMENT     Alignment     = ALIGNMENT::NO_ALIGNMENT; 
        GROUP_ID      GroupID = wxEmptyString; 
        REUSEBLOCKREF ReuseBlockRef;
 
        void Parse( XNODE* aNode, PARSER_CONTEXT* aContext ) override;
        void Parse( XNODE* aNode, PARSER_CONTEXT* aContext, bool aParseFields );
    };
 
 
    struct SYMDEF : PARSER
    {
        SYMDEF_ID ID;
        wxString  ReferenceName; 
        wxString Alternate;      
        POINT Origin;            
        bool Stub = false;       
        long Version = UNDEFINED_VALUE; 
 
        std::map<FIGURE_ID, FIGURE>           Figures;
        std::map<TEXT_ID, TEXT>               Texts;
        std::map<ATTRIBUTE_ID, TEXT_LOCATION> TextLocations;     
        std::map<ATTRIBUTE_ID, ATTRIBUTE_VALUE> AttributeValues; 
 
        wxString BuildLibName() const;
        void ParseIdentifiers( XNODE* aNode, PARSER_CONTEXT* aContext );
        bool ParseSubNode( XNODE* aChildNode, PARSER_CONTEXT* aContext );
    };
 
 
    struct PART : PARSER
    {
        static CADSTAR_PIN_TYPE GetPinType( XNODE* aNode );
 
        struct DEFINITION : PARSER 
        {
            struct GATE : PARSER 
            {
                GATE_ID  ID;        
                wxString Name;      
                wxString Alternate; 
                long     PinCount;  
 
                void Parse( XNODE* aNode, PARSER_CONTEXT* aContext ) override;
            };
 
 
            struct PIN : PARSER 
            {
                PART_DEFINITION_PIN_ID ID = UNDEFINED_VALUE;
 
                wxString Identifier = wxEmptyString;      
                wxString Name = wxEmptyString;            
                wxString Label = wxEmptyString;           
                wxString Signal = wxEmptyString;          
                GATE_ID     TerminalGate;                 
                TERMINAL_ID TerminalPin;                  
 
                CADSTAR_PIN_TYPE Type = CADSTAR_PIN_TYPE::UNCOMMITTED; 
 
                long Load = UNDEFINED_VALUE;              
                CADSTAR_PIN_POSITION Position =
                    CADSTAR_PIN_POSITION::TOP_RIGHT; 
 
                void Parse( XNODE* aNode, PARSER_CONTEXT* aContext ) override;
            };
 
 
            struct PIN_EQUIVALENCE : PARSER 
            {
                std::vector<PART_DEFINITION_PIN_ID> PinIDs; 
 
                void Parse( XNODE* aNode, PARSER_CONTEXT* aContext ) override;
            };
 
 
            struct SWAP_GATE : PARSER 
            {
                std::vector<PART_DEFINITION_PIN_ID> PinIDs; 
 
                void Parse( XNODE* aNode, PARSER_CONTEXT* aContext ) override;
            };
 
 
            struct SWAP_GROUP : PARSER
            {
                wxString GateName =
                        wxEmptyString; 
 
                bool External = false; 
 
                std::vector<SWAP_GATE> SwapGates; 
 
                void Parse( XNODE* aNode, PARSER_CONTEXT* aContext ) override;
            };
 
            wxString Name; 
            bool     HidePinNames =
                    false; 
 
            long MaxPinCount =
                    UNDEFINED_VALUE; 
 
            std::map<GATE_ID, GATE>                 GateSymbols;
            std::map<PART_DEFINITION_PIN_ID, PIN>   Pins;
            std::map<ATTRIBUTE_ID, ATTRIBUTE_VALUE> AttributeValues; 
            std::vector<PIN_EQUIVALENCE> PinEquivalences;
            std::vector<SWAP_GROUP>      SwapGroups;
 
            void Parse( XNODE* aNode, PARSER_CONTEXT* aContext ) override;
        };
 
 
        struct PART_PIN : PARSER 
        {
            PART_PIN_ID ID;
            wxString         Name = wxEmptyString;
            CADSTAR_PIN_TYPE Type = CADSTAR_PIN_TYPE::UNCOMMITTED;
            wxString         Identifier = wxEmptyString;
 
            void Parse( XNODE* aNode, PARSER_CONTEXT* aContext ) override;
        };
 
 
        PART_ID                         ID;
        wxString                        Name;
        long                            Version;
        DEFINITION                      Definition;
        std::map<PART_PIN_ID, PART_PIN> PartPins; 
 
        bool HidePinNames = false; 
 
        std::map<ATTRIBUTE_ID, ATTRIBUTE_VALUE> AttributeValues; 
 
        void Parse( XNODE* aNode, PARSER_CONTEXT* aContext ) override;
    };
 
 
    struct PARTS : PARSER
    {
        std::map<PART_ID, PART> PartDefinitions;
 
        void Parse( XNODE* aNode, PARSER_CONTEXT* aContext ) override;
    };
 
 
    struct NET : PARSER
    {
        struct JUNCTION : PARSER 
        {
            NETELEMENT_ID ID; 
            LAYER_ID      LayerID;
            POINT         Location;
            GROUP_ID      GroupID = wxEmptyString; 
            REUSEBLOCKREF ReuseBlockRef;
            bool          Fixed = false;
 
            void         ParseIdentifiers( XNODE* aNode, PARSER_CONTEXT* aContext );
            bool         ParseSubNode( XNODE* aChildNode, PARSER_CONTEXT* aContext );
            virtual void Parse( XNODE* aNode, PARSER_CONTEXT* aContext ) override;
        };
 
 
        struct CONNECTION : PARSER 
        {
            NETELEMENT_ID StartNode;
            NETELEMENT_ID EndNode;
            ROUTECODE_ID  RouteCodeID;
 
            bool     Fixed   = false;
            bool     Hidden  = false;
            GROUP_ID GroupID = wxEmptyString; 
            REUSEBLOCKREF ReuseBlockRef;
 
            std::map<ATTRIBUTE_ID, ATTRIBUTE_VALUE> AttributeValues; 
            void ParseIdentifiers( XNODE* aNode, PARSER_CONTEXT* aContext );
            bool ParseSubNode( XNODE* aChildNode, PARSER_CONTEXT* aContext );
 
            virtual ~CONNECTION() {}
        };
 
        NET_ID       ID;
        ROUTECODE_ID RouteCodeID = wxEmptyString;   
        long         SignalNum   = UNDEFINED_VALUE; 
        wxString Name = wxEmptyString; 
        bool Highlight = false;
 
        std::map<NETELEMENT_ID, JUNCTION>       Junctions;
        std::map<ATTRIBUTE_ID, ATTRIBUTE_VALUE> AttributeValues;
 
        NETCLASS_ID NetClassID =
                wxEmptyString; 
        SPACING_CLASS_ID SpacingClassID =
                wxEmptyString; 
 
        void ParseIdentifiers( XNODE* aNode, PARSER_CONTEXT* aContext );
        bool ParseSubNode( XNODE* aChildNode, PARSER_CONTEXT* aContext );
    };
 
 
    struct DOCUMENTATION_SYMBOL : PARSER
    {
        DOCUMENTATION_SYMBOL_ID ID;
 
        SYMDEF_ID SymdefID; 
        LAYER_ID LayerID;   
        POINT    Origin;    
 
        GROUP_ID      GroupID = wxEmptyString; 
        REUSEBLOCKREF ReuseBlockRef;
        long          OrientAngle = 0;
        bool          Mirror      = false;
        bool          Fixed       = false;
        READABILITY   Readability = READABILITY::BOTTOM_TO_TOP;
 
        long ScaleRatioNumerator = 1;   
        long ScaleRatioDenominator = 1; 
 
        std::map<ATTRIBUTE_ID, ATTRIBUTE_VALUE> AttributeValues;
 
        void Parse( XNODE* aNode, PARSER_CONTEXT* aContext ) override;
    };
 
 
    struct DFLTSETTINGS : PARSER
    {
        COLOR_ID Color;
        bool     IsVisible = true;
 
        void     Parse( XNODE* aNode, PARSER_CONTEXT* aContext ) override;
    };
 
 
    struct ATTRCOL : PARSER
    {
        ATTRIBUTE_ID AttributeID;
        COLOR_ID     Color;
        bool         IsVisible = true;
        bool         IsPickable = true;
 
        void Parse( XNODE* aNode, PARSER_CONTEXT* aContext ) override;
    };
 
 
    struct ATTRCOLORS : PARSER
    {
        DFLTSETTINGS DefaultSettings;
        std::map<ATTRIBUTE_ID, ATTRCOL> AttributeColors;
 
        bool IsVisible = true; // unclear what this represents - maybe all attributes are hidden?
 
        void Parse( XNODE* aNode, PARSER_CONTEXT* aContext ) override;
    };
 
 
    struct PARTNAMECOL : PARSER
    {
        COLOR_ID Color;
        bool     IsVisible = true;
        bool     IsPickable = true;
 
        void Parse( XNODE* aNode, PARSER_CONTEXT* aContext ) override;
    };

    // HELPER FUNCTIONS: //
 
 
    static void InsertAttributeAtEnd( XNODE* aNode, wxString aValue );

    static XNODE* LoadArchiveFile( const wxString& aFileName, const wxString& aFileTypeIdentifier,
                                   PROGRESS_REPORTER* aProgressReporter = nullptr );

    static bool IsValidAttribute( wxXmlAttribute* aAttribute );

    static wxString GetXmlAttributeIDString( XNODE* aNode, unsigned int aID,
                                             bool aIsRequired = true );

    static long GetXmlAttributeIDLong( XNODE* aNode, unsigned int aID, bool aIsRequired = true );

    static void CheckNoChildNodes( XNODE* aNode );

    static void CheckNoNextNodes( XNODE* aNode );

    static void ParseChildEValue( XNODE* aNode, PARSER_CONTEXT* aContext, EVALUE& aValueToParse );

    static std::vector<POINT> ParseAllChildPoints( XNODE* aNode, PARSER_CONTEXT* aContext,
                                                   bool aTestAllChildNodes = false,
                                                   int aExpectedNumPoints = UNDEFINED_VALUE );

    static std::vector<VERTEX> ParseAllChildVertices( XNODE* aNode, PARSER_CONTEXT* aContext,
                                                      bool aTestAllChildNodes = false );

    static std::vector<CUTOUT> ParseAllChildCutouts( XNODE* aNode, PARSER_CONTEXT* aContext,
                                                     bool aTestAllChildNodes = false );
 
    static long GetNumberOfChildNodes( XNODE* aNode );
 
    static long GetNumberOfStepsForReporting( XNODE*                aRootNode,
                                              std::vector<wxString> aSubNodeChildrenToCount );
 
 
    static wxString EscapeFieldText( const wxString& aFieldText )
    {
        wxString ret = aFieldText;
        ret.Replace( wxT( "\n" ), wxT( "\\n" ) );
        ret.Replace( wxT( "\r" ), wxT( "\\r" ) );
        ret.Replace( wxT( "\t" ), wxT( "\\t" ) );
 
        return ret;
    }

    static wxString HandleTextOverbar( wxString aCadstarString );

    static void FixTextPositionNoAlignment( EDA_TEXT* aKiCadTextItem );
 
    static wxString generateLibName( const wxString& aRefName, const wxString& aAlternateName );
 
 
protected:
    void checkPoint(); 
 
    PARSER_CONTEXT     m_context;
    PROGRESS_REPORTER* m_progressReporter; // optional; may be nullptr
 
 
}; // class CADSTAR_ARCHIVE_PARSER
 
#endif // CADSTAR_ARCHIVE_PARSER_H_