netlist_exporter_xml.cpp

Go to the documentation of this file.

/*
 * This program source code file is part of KiCad, a free EDA CAD application.
 *
 * Copyright (C) 1992-2013 jp.charras at wanadoo.fr
 * Copyright (C) 2013-2017 SoftPLC Corporation, Dick Hollenbeck <[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 2
 * 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/>.
 */
 
#include "netlist_exporter_xml.h"
 
#include <algorithm>
#include <build_version.h>
#include <gal/color4d.h>
#include <common.h>     // for ExpandTextVars
#include <sch_base_frame.h>
#include <sch_group.h>
#include <sch_sheet.h>
#include <string_utils.h>
#include <connection_graph.h>
#include <pgm_base.h>
#include <core/kicad_algo.h>
#include <wx/wfstream.h>
#include <xnode.h>      // also nests: <wx/xml/xml.h>
#include <json_common.h>
#include <project_sch.h>
#include <project/project_file.h>
#include <project/net_settings.h>
#include <sch_rule_area.h>
#include <trace_helpers.h>
 
#include <map>
#include <optional>
#include <set>
#include <libraries/symbol_library_adapter.h>
#include <sch_sheet_path.h>
 
static bool sortPinsByNumber( SCH_PIN* aPin1, SCH_PIN* aPin2 );
 
bool NETLIST_EXPORTER_XML::writeNetlist( const wxString& aOutFileName, unsigned aNetlistOptions,
                                         REPORTER& aReporter )
{
    // output the XML format netlist.
 
    // declare the stream ourselves to use the buffered FILE api
    // instead of letting wx use the syscall variant
    wxFFileOutputStream stream( aOutFileName );
 
    if( !stream.IsOk() )
        return false;
 
    wxXmlDocument xdoc;
    xdoc.SetRoot( makeRoot( GNL_ALL | aNetlistOptions ) );
 
    return xdoc.Save( stream, 2 /* indent bug, today was ignored by wxXml lib */ );
}
 
 
XNODE* NETLIST_EXPORTER_XML::makeRoot( unsigned aCtl )
{
    XNODE*      xroot = node( wxT( "export" ) );
 
    xroot->AddAttribute( wxT( "version" ), wxT( "E" ) );
 
    if( aCtl & GNL_HEADER )
    {
        // add the "design" header
        xroot->AddChild( makeDesignHeader() );
    }
 
    if( aCtl & GNL_SYMBOLS )
    {
        xroot->AddChild( makeSymbols( aCtl ) );
 
        if( aCtl & GNL_OPT_KICAD )
        {
            xroot->AddChild( makeGroups() );
            xroot->AddChild( makeVariants() );
        }
    }
 
    if( aCtl & GNL_PARTS )
        xroot->AddChild( makeLibParts() );
 
    if( aCtl & GNL_LIBRARIES )
    {
        // must follow makeGenericLibParts()
        xroot->AddChild( makeLibraries() );
    }
 
    if( aCtl & GNL_NETS )
    {
        xroot->AddChild( makeListOfNets( aCtl ) );
 
        // Net chains are a KiCad-internal extension that is not part of the public XML
        // netlist schema (version "E"). Emit them only for the KiCad-internal consumer
        // (eeschema -> pcbnew via NETLIST_EXPORTER_KICAD) so that generic XML, KiCost and
        // other schema-validating tools do not see an unexpected element.
        if( aCtl & GNL_OPT_KICAD )
        {
            if( XNODE* xchains = makeNetChains() )
                xroot->AddChild( xchains );
        }
    }
 
    return xroot;
}
 

 
 
void NETLIST_EXPORTER_XML::addSymbolFields( XNODE* aNode, SCH_SYMBOL* aSymbol, const SCH_SHEET_PATH& aSheet,
                                            const SCH_SHEET_LIST& aSheetList )
{
    wxString                     value;
    wxString                     footprint;
    wxString                     datasheet;
    wxString                     description;
    wxString                     candidate;
    nlohmann::ordered_map<wxString, wxString> fields;
 
    if( aSymbol->GetUnitCount() > 1 )
    {
        // Sadly, each unit of a symbol can have its own unique fields. This
        // block finds the unit with the lowest number having a non blank field
        // value and records it.  Therefore user is best off setting fields
        // into only the first unit.  But this scavenger algorithm will find
        // any non blank fields in all units and use the first non-blank field
        // for each unique field name.
 
        wxString ref = aSymbol->GetRef( &aSheet );
 
        // ranked by unit then UUID so the pick does not depend on visiting order
        using SOURCE = std::pair<int, KIID>;
 
        std::optional<SOURCE>      valueSrc;
        std::optional<SOURCE>      footprintSrc;
        std::optional<SOURCE>      datasheetSrc;
        std::optional<SOURCE>      descriptionSrc;
 
        // a blank field ranks after any text so it never hides a higher unit's value
        std::map<wxString, std::pair<bool, SOURCE>> fieldSrcs;
 
        auto earlier =
                []( const SOURCE& aNew, const std::optional<SOURCE>& aOld )
                {
                    return !aOld || aNew < *aOld;
                };
 
        for( const SCH_SHEET_PATH& sheet : aSheetList )
        {
            for( SCH_ITEM* item : sheet.LastScreen()->Items().OfType( SCH_SYMBOL_T ) )
            {
                SCH_SYMBOL* symbol2 = static_cast<SCH_SYMBOL*>( item );
 
                wxString ref2 = symbol2->GetRef( &sheet );
 
                if( ref2.CmpNoCase( ref ) != 0 )
                    continue;
 
                const SOURCE src{ symbol2->GetUnitSelection( &sheet ), symbol2->m_Uuid };
 
                // The lowest unit number wins.  User should only set fields in any one unit.
 
                // Value
                candidate = symbol2->GetValue( &sheet, m_resolveTextVars, m_exportVariant );
 
                if( !candidate.IsEmpty() && earlier( src, valueSrc ) )
                {
                    value = candidate;
                    valueSrc = src;
                }
 
                // Footprint
                candidate = symbol2->GetFootprintFieldText( &sheet, m_resolveTextVars, m_exportVariant );
 
                if( !candidate.IsEmpty() && earlier( src, footprintSrc ) )
                {
                    footprint = candidate;
                    footprintSrc = src;
                }
 
                // Datasheet
                candidate = symbol2->GetField( FIELD_T::DATASHEET )->GetShownText( &sheet, m_resolveTextVars,
                                                                                   m_exportVariant );
 
                if( !candidate.IsEmpty() && earlier( src, datasheetSrc ) )
                {
                    datasheet = candidate;
                    datasheetSrc = src;
                }
 
                // Description
                candidate = symbol2->GetField( FIELD_T::DESCRIPTION )->GetShownText( &sheet, m_resolveTextVars,
                                                                                     m_exportVariant );
 
                if( !candidate.IsEmpty() && earlier( src, descriptionSrc ) )
                {
                    description = candidate;
                    descriptionSrc = src;
                }
 
                // All non-mandatory fields
                for( SCH_FIELD& field : symbol2->GetFields() )
                {
                    if( field.IsMandatory() || field.IsPrivate() )
                        continue;
 
                    candidate = field.GetShownText( &sheet, m_resolveTextVars, m_exportVariant );
 
                    const std::pair<bool, SOURCE> rank{ candidate.IsEmpty(), src };
                    auto                          known = fieldSrcs.find( field.GetName() );
 
                    if( known == fieldSrcs.end() || rank < known->second )
                    {
                        fields[field.GetName()] = candidate;
                        fieldSrcs.insert_or_assign( field.GetName(), rank );
                    }
                }
            }
        }
    }
    else
    {
        value = aSymbol->GetValue( &aSheet, m_resolveTextVars, m_exportVariant );
        footprint = aSymbol->GetFootprintFieldText( &aSheet, m_resolveTextVars, m_exportVariant );
 
        SCH_FIELD* datasheetField = aSymbol->GetField( FIELD_T::DATASHEET );
        SCH_FIELD* descriptionField = aSymbol->GetField( FIELD_T::DESCRIPTION );
 
        datasheet = datasheetField->GetShownText( &aSheet, m_resolveTextVars, m_exportVariant );
        description = descriptionField->GetShownText( &aSheet, m_resolveTextVars, m_exportVariant );
 
        for( SCH_FIELD& field : aSymbol->GetFields() )
        {
            if( field.IsMandatory() || field.IsPrivate() )
                continue;
 
            fields[field.GetName()] = field.GetShownText( &aSheet, m_resolveTextVars, m_exportVariant );
        }
    }
 
    fields[GetDefaultFieldName( FIELD_T::FOOTPRINT, UNTRANSLATED )] = footprint;
    fields[GetDefaultFieldName( FIELD_T::DATASHEET, UNTRANSLATED )] = datasheet;
    fields[GetDefaultFieldName( FIELD_T::DESCRIPTION, UNTRANSLATED )] = description;
 
    // Do not output field values blank in netlist:
    if( value.size() )
        aNode->AddChild( node( wxT( "value" ), UnescapeString( value ) ) );
    else    // value field always written in netlist
        aNode->AddChild( node( wxT( "value" ), wxT( "~" ) ) );
 
    if( footprint.size() )
        aNode->AddChild( node( wxT( "footprint" ), UnescapeString( footprint ) ) );
 
    if( datasheet.size() )
        aNode->AddChild( node( wxT( "datasheet" ), UnescapeString( datasheet ) ) );
 
    if( description.size() )
        aNode->AddChild( node( wxT( "description" ), UnescapeString( description ) ) );
 
    XNODE* xfields;
    aNode->AddChild( xfields = node( wxT( "fields" ) ) );
 
    for( const auto& [ fieldName, fieldValue ] : fields )
    {
        XNODE* xfield = node( wxT( "field" ), UnescapeString( fieldValue ) );
        xfield->AddAttribute( wxT( "name" ), UnescapeString( fieldName ) );
        xfields->AddChild( xfield );
    }
}
 
 
XNODE* NETLIST_EXPORTER_XML::makeSymbols( unsigned aCtl )
{
    XNODE* xcomps = node( wxT( "components" ) );
 
    m_referencesAlreadyFound.Clear();
    m_libParts.clear();
    getSheetComponentClasses();
 
    SCH_SHEET_PATH currentSheet = m_schematic->CurrentSheet();
    SCH_SHEET_LIST sheetList = m_exportSheets;
 
    // Output is xml, so there is no reason to remove spaces from the field values.
    // And XML element names need not be translated to various languages.
 
    for( const SCH_SHEET_PATH& sheet : sheetList )
    {
        // Change schematic CurrentSheet in each iteration to allow hierarchical
        // resolution of text variables in sheet fields.
        m_schematic->SetCurrentSheet( sheet );
 
        auto cmp =
                [&sheet]( SCH_SYMBOL* a, SCH_SYMBOL* b )
                {
                    return ( StrNumCmp( a->GetRef( &sheet, false ),
                                        b->GetRef( &sheet, false ), true ) < 0 );
                };
 
        std::set<SCH_SYMBOL*, decltype( cmp )> ordered_symbols( cmp );
        std::multiset<SCH_SYMBOL*, decltype( cmp )> extra_units( cmp );
 
        for( SCH_ITEM* item : sheet.LastScreen()->Items().OfType( SCH_SYMBOL_T ) )
        {
            SCH_SYMBOL* symbol = static_cast<SCH_SYMBOL*>( item );
            auto        test = ordered_symbols.insert( symbol );
 
            if( !test.second )
            {
                if( ( *( test.first ) )->m_Uuid > symbol->m_Uuid )
                {
                    extra_units.insert( *( test.first ) );
                    ordered_symbols.erase( test.first );
                    ordered_symbols.insert( symbol );
                }
                else
                {
                    extra_units.insert( symbol );
                }
            }
        }
 
        for( EDA_ITEM* item : ordered_symbols )
        {
            SCH_SYMBOL* symbol = findNextSymbol( item, sheet );
            bool        forBOM = aCtl & GNL_OPT_BOM;
            bool        forBoard = aCtl & GNL_OPT_KICAD;
 
            if( !symbol )
                continue;
 
            // Do not use exportVariant for determininig whether or not to output a symbol.  It
            // will be blank when exporting to PCBNew.
 
            if( forBOM && ( sheet.GetExcludedFromBOM( m_schematic->GetCurrentVariant() )
                           || symbol->ResolveExcludedFromBOM( &sheet, m_schematic->GetCurrentVariant() ) ) )
            {
                continue;
            }
 
            if( forBoard && ( sheet.GetExcludedFromBoard( m_schematic->GetCurrentVariant() )
                             || symbol->ResolveExcludedFromBoard( &sheet, m_schematic->GetCurrentVariant() ) ) )
            {
                continue;
            }
 
            // Output the symbol's elements in order of expected access frequency. This may
            // not always look best, but it will allow faster execution under XSL processing
            // systems which do sequential searching within an element.
 
            XNODE* xcomp;  // current symbol being constructed
            xcomps->AddChild( xcomp = node( wxT( "comp" ) ) );
 
            xcomp->AddAttribute( wxT( "ref" ), symbol->GetRef( &sheet ) );
            addSymbolFields( xcomp, symbol, sheet, sheetList );
 
            XNODE*  xlibsource;
            xcomp->AddChild( xlibsource = node( wxT( "libsource" ) ) );
 
            // "logical" library name, which is in anticipation of a better search algorithm
            // for parts based on "logical_lib.part" and where logical_lib is merely the library
            // name minus path and extension.
            wxString libName;
            wxString partName;
 
            if( symbol->UseLibIdLookup() )
            {
                libName = symbol->GetLibId().GetUniStringLibNickname();
                partName = symbol->GetLibId().GetUniStringLibItemName();
            }
            else
            {
                partName = symbol->GetSchSymbolLibraryName();
            }
 
            xlibsource->AddAttribute( wxT( "lib" ), libName );
 
            // We only want the symbol name, not the full LIB_ID.
            xlibsource->AddAttribute( wxT( "part" ), partName );
 
            xlibsource->AddAttribute( wxT( "description" ), symbol->GetShownDescription( m_resolveTextVars ) );
 
            /* Add the symbol properties. */
            XNODE* xproperty;
 
            std::vector<SCH_FIELD>& fields = symbol->GetFields();
 
            for( SCH_FIELD& field : fields )
            {
                if( field.IsMandatory() || field.IsPrivate() )
                    continue;
 
                xcomp->AddChild( xproperty = node( wxT( "property" ) ) );
                xproperty->AddAttribute( wxT( "name" ), field.GetUntranslatedName() );
 
                xproperty->AddAttribute( wxT( "value" ), field.GetShownText( &sheet, m_resolveTextVars,
                                                                             m_exportVariant ) );
            }
 
            for( const SCH_FIELD& sheetField : sheet.Last()->GetFields() )
            {
                xcomp->AddChild( xproperty = node( wxT( "property" ) ) );
                xproperty->AddAttribute( wxT( "name" ), sheetField.GetUntranslatedName() );
 
                xproperty->AddAttribute( wxT( "value" ), sheetField.GetShownText( &sheet, m_resolveTextVars,
                                                                                  m_exportVariant ) );
            }
 
            const bool baseExcludedFromBOM = symbol->ResolveExcludedFromBOM( &sheet ) || sheet.GetExcludedFromBOM();
            const bool baseExcludedFromSim = symbol->ResolveExcludedFromSim( &sheet ) || sheet.GetExcludedFromSim();
 
            if( symbol->ResolveExcludedFromBOM( &sheet, m_exportVariant )
                    || sheet.GetExcludedFromBOM( m_exportVariant ) )
            {
                xcomp->AddChild( xproperty = node( wxT( "property" ) ) );
                xproperty->AddAttribute( wxT( "name" ), wxT( "exclude_from_bom" ) );
            }
 
            if( symbol->ResolveExcludedFromSim( &sheet, m_exportVariant )
                || sheet.GetExcludedFromSim( m_exportVariant ) )
            {
                xcomp->AddChild( xproperty = node( wxT( "property" ) ) );
                xproperty->AddAttribute( wxT( "name" ), wxT( "exclude_from_sim" ) );
            }
 
            if( symbol->ResolveExcludedFromBoard( &sheet, m_exportVariant )
                || sheet.GetExcludedFromBoard( m_exportVariant ) )
            {
                xcomp->AddChild( xproperty = node( wxT( "property" ) ) );
                xproperty->AddAttribute( wxT( "name" ), wxT( "exclude_from_board" ) );
            }
 
            const bool baseExcludedFromPosFiles = symbol->ResolveExcludedFromPosFiles( &sheet );
 
            if( symbol->ResolveExcludedFromPosFiles( &sheet, m_exportVariant ) )
            {
                xcomp->AddChild( xproperty = node( wxT( "property" ) ) );
                xproperty->AddAttribute( wxT( "name" ), wxT( "exclude_from_pos_files" ) );
            }
 
            const bool baseDnp = symbol->ResolveDNP( &sheet ) || sheet.GetDNP();
 
            if( symbol->ResolveDNP( &sheet, m_exportVariant ) || sheet.GetDNP( m_exportVariant ) )
            {
                xcomp->AddChild( xproperty = node( wxT( "property" ) ) );
                xproperty->AddAttribute( wxT( "name" ), wxT( "dnp" ) );
            }
 
            // Iterate all variants in the schematic, not just those in the symbol instance,
            // because a sheet can have variant-specific attributes even if the symbol does not.
            const std::set<wxString>& variantNames = m_schematic->GetVariantNames();
 
            // Differences against the base design, which only the board netlist still reports.
            if( ( aCtl & GNL_OPT_KICAD ) && !variantNames.empty() )
            {
                XNODE* xvariants = nullptr;
 
                for( const auto& variantName : variantNames )
                {
                    XNODE* xvariant = nullptr;
 
                    auto addToVariant =
                            [this, &xvariant, &variantName]( XNODE* child ) -> void
                            {
                                if( !child )
                                    return;
 
                                if( !xvariant )
                                {
                                    xvariant = node( wxT( "variant" ) );
                                    xvariant->AddAttribute( wxT( "name" ), variantName );
                                }
                                xvariant->AddChild( child );
                            };
 
                    auto addBinaryProp =
                            [this, &addToVariant]( wxString const& name, bool base, bool effective ) -> void
                            {
                                if( base == effective )
                                    return;
 
                                XNODE* xvarprop = node( wxT( "property" ) );
                                xvarprop->AddAttribute( wxT( "name" ), name );
                                xvarprop->AddAttribute( wxT( "value" ), effective ? wxT( "1" ) : wxT( "0" ) );
                                addToVariant( xvarprop );
                            };
 
                    bool effectiveDnp = symbol->ResolveDNP( &sheet, variantName ) || sheet.GetDNP( variantName );
                    addBinaryProp( wxT( "dnp" ), baseDnp, effectiveDnp );
 
                    bool effectiveExcludedFromBOM = symbol->ResolveExcludedFromBOM( &sheet, variantName )
                                                    || sheet.GetExcludedFromBOM( variantName );
                    addBinaryProp( wxT( "exclude_from_bom" ), baseExcludedFromBOM, effectiveExcludedFromBOM );
 
                    bool effectiveExcludedFromSim = symbol->ResolveExcludedFromSim( &sheet, variantName )
                                                    || sheet.GetExcludedFromSim( variantName );
                    addBinaryProp( wxT( "exclude_from_sim" ), baseExcludedFromSim, effectiveExcludedFromSim );
 
                    bool effectiveExcludedFromPosFiles = symbol->ResolveExcludedFromPosFiles( &sheet, variantName );
                    addBinaryProp( wxT( "exclude_from_pos_files" ), baseExcludedFromPosFiles,
                                   effectiveExcludedFromPosFiles );
 
                    SCH_SYMBOL_INSTANCE       instance;
                    const SCH_SYMBOL_VARIANT* variant = nullptr;
 
                    if( symbol->GetInstance( instance, sheet.Path() ) && instance.m_Variants.contains( variantName ) )
                        variant = &instance.m_Variants.at( variantName );
 
                    if( variant && variant->m_SymbolOverride )
                    {
                        XNODE* xprop = node( wxT( "property" ) );
                        xprop->AddAttribute( wxT( "name" ), wxT( "symbol_override" ) );
                        xprop->AddAttribute( wxT( "value" ), variant->m_SymbolOverride->Format() );
                        addToVariant( xprop );
                    }
 
                    if( variant && ( !variant->m_Fields.empty() || variant->m_SymbolOverride ) )
                    {
                        XNODE* xfields = nullptr;
 
                        for( const auto& [fieldName, fieldValue] : variant->m_Fields )
                        {
                            const wxString baseValue = symbol->GetFieldText( fieldName, &sheet, wxEmptyString );
 
                            if( fieldValue == baseValue )
                                continue;
 
                            if( !xfields )
                                xfields = node( wxT( "fields" ) );
 
                            wxString resolvedValue = fieldValue;
 
                            if( m_resolveTextVars != RAW_VALUE )
                                resolvedValue = symbol->ResolveText( fieldValue, &sheet );
 
                            XNODE* xfield = node( wxT( "field" ), UnescapeString( resolvedValue ) );
                            xfield->AddAttribute( wxT( "name" ), UnescapeString( fieldName ) );
                            xfields->AddChild( xfield );
                        }
 
                        // Emit fields resolved from the alternate library symbol where the
                        // value differs from the base symbol. Explicit overrides in
                        // variant->m_Fields were already handled above.
                        if( variant->m_SymbolOverride )
                        {
                            for( const SCH_FIELD& baseField : symbol->GetFields() )
                            {
                                const wxString& fieldName = baseField.GetName();
 
                                if( variant->m_Fields.contains( fieldName ) )
                                    continue;
 
                                const wxString baseValue = symbol->GetFieldText( fieldName, &sheet, wxEmptyString );
                                const wxString variantValue = symbol->GetFieldText( fieldName, &sheet, variantName );
 
                                if( variantValue == baseValue )
                                    continue;
 
                                if( !xfields )
                                    xfields = node( wxT( "fields" ) );
 
                                wxString resolvedValue = variantValue;
 
                                if( m_resolveTextVars != RAW_VALUE )
                                    resolvedValue = symbol->ResolveText( variantValue, &sheet );
 
                                XNODE* xfield = node( wxT( "field" ), UnescapeString( resolvedValue ) );
                                xfield->AddAttribute( wxT( "name" ), UnescapeString( baseField.GetUntranslatedName() ) );
                                xfields->AddChild( xfield );
                            }
 
                            // Emit fields that exist only on the alternate library symbol so the
                            // netlist reflects the full atomic part, not just the base field set.
                            if( LIB_SYMBOL* altSymbol = symbol->GetVariantLibSymbol( variantName, sheet ) )
                            {
                                std::vector<SCH_FIELD*> altFields;
                                altSymbol->GetFields( altFields );
 
                                for( const SCH_FIELD* altField : altFields )
                                {
                                    const wxString& fieldName = altField->GetName();
 
                                    if( symbol->GetField( fieldName )
                                        || variant->m_Fields.contains( fieldName )
                                        || altField->GetText().IsEmpty() )
                                    {
                                        continue;
                                    }
 
                                    if( !xfields )
                                        xfields = node( wxT( "fields" ) );
 
                                    wxString resolvedValue = altField->GetText();
 
                                    if( m_resolveTextVars != RAW_VALUE )
                                        resolvedValue = symbol->ResolveText( resolvedValue, &sheet );
 
                                    XNODE* xfield = node( wxT( "field" ), UnescapeString( resolvedValue ) );
                                    xfield->AddAttribute( wxT( "name" ), UnescapeString( fieldName ) );
                                    xfields->AddChild( xfield );
                                }
                            }
                        }
 
                        addToVariant( xfields );
                    }
 
                    if( xvariant )
                    {
                        if( !xvariants )
                            xvariants = node( wxT( "variants" ) );
 
                        xvariants->AddChild( xvariant );
                    }
                }
 
                if( xvariants )
                    xcomp->AddChild( xvariants );
            }
 
            if( const std::unique_ptr<LIB_SYMBOL>& part = symbol->GetLibSymbolRef() )
            {
                if( part->GetKeyWords().size() )
                {
                    xcomp->AddChild( xproperty = node( wxT( "property" ) ) );
                    xproperty->AddAttribute( wxT( "name" ), wxT( "ki_keywords" ) );
                    xproperty->AddAttribute( wxT( "value" ), part->GetKeyWords() );
                }
 
                if( !part->GetFPFilters().IsEmpty() )
                {
                    wxString filters;
 
                    for( const wxString& filter : part->GetFPFilters() )
                        filters += ' ' + filter;
 
                    xcomp->AddChild( xproperty = node( wxT( "property" ) ) );
                    xproperty->AddAttribute( wxT( "name" ), wxT( "ki_fp_filters" ) );
                    xproperty->AddAttribute( wxT( "value" ), filters.Trim( false ) );
                }
 
                if( part->GetDuplicatePinNumbersAreJumpers() )
                    xcomp->AddChild( node( wxT( "duplicate_pin_numbers_are_jumpers" ), wxT( "1" ) ) );
 
                const JUMPER_GROUP_SET& jumperGroups = part->JumperPinGroups();
 
                if( !jumperGroups.IsEmpty() )
                {
                    XNODE* groupNode;
                    xcomp->AddChild( xproperty = node( wxT( "jumper_pin_groups" ) ) );
 
                    for( const JUMPER_GROUP& group : jumperGroups.GetAll() )
                    {
                        xproperty->AddChild( groupNode = node( wxT( "group" ) ) );
 
                        for( const wxString& pinName : group.GetNames() )
                            groupNode->AddChild( node( wxT( "pin" ), pinName ) );
                    }
                }
            }
 
            XNODE* xsheetpath;
            xcomp->AddChild( xsheetpath = node( wxT( "sheetpath" ) ) );
 
            xsheetpath->AddAttribute( wxT( "names" ), sheet.PathHumanReadable() );
            xsheetpath->AddAttribute( wxT( "tstamps" ), sheet.PathAsString() );
 
            // Node for component class
            std::vector<wxString> compClassNames = getComponentClassNamesForAllSymbolUnits( symbol, sheet, sheetList );
 
            if( compClassNames.size() > 0 )
            {
                XNODE* xcompclasslist;
                xcomp->AddChild( xcompclasslist = node( wxT( "component_classes" ) ) );
 
                for( const wxString& compClass : compClassNames )
                    xcompclasslist->AddChild( node( wxT( "class" ), UnescapeString( compClass ) ) );
            }
 
            XNODE* xunits; // Node for extra units
            xcomp->AddChild( xunits = node( wxT( "tstamps" ) ) );
 
            auto     range = extra_units.equal_range( symbol );
            wxString uuid;
 
            // Output a series of children with all UUIDs associated with the REFDES
            for( auto it = range.first; it != range.second; ++it )
            {
                uuid = ( *it )->m_Uuid.AsString();
 
                // Add a space between UUIDs, if not in KICAD mode (i.e.
                // using wxXmlDocument::Save()).  KICAD MODE has its own XNODE::Format function.
                if( !( aCtl & GNL_OPT_KICAD ) )     // i.e. for .xml format
                    uuid += ' ';
 
                xunits->AddChild( new XNODE( wxXML_TEXT_NODE, wxEmptyString, uuid ) );
            }
 
            // Output the primary UUID
            uuid = symbol->m_Uuid.AsString();
            xunits->AddChild( new XNODE( wxXML_TEXT_NODE, wxEmptyString, uuid ) );
 
            // Emit unit information (per-unit name and pins) after tstamps
            XNODE* xunitInfo;
            xcomp->AddChild( xunitInfo = node( wxT( "units" ) ) );
 
            const std::unique_ptr<LIB_SYMBOL>& libSym = symbol->GetLibSymbolRef();
 
            if( libSym )
            {
                // A multi-unit symbol can resolve to a different lib symbol per placed unit
                // after unit-specific edits. For instane, if you have units A B C in a multi-unit
                // symbol, and you edit only unit B, unit B will point to new, modified lib symbol
                // but A and C will point to the original lib symbol.
                //
                // Export the unit metadata from the actual unit instances's lib symbols so the PCB
                // footprint metadata matches during backannotation, which always works per unit.
                //
                // However, the user isn't required to place all units, so keep a fallback default unit info.
                const std::vector<LIB_SYMBOL::UNIT_PIN_INFO>& defaultUnitInfo = libSym->GetUnitPinInfo();
                std::map<int, SCH_SYMBOL*>                    symbolByUnit;
 
                auto addUnitSymbol =
                        [&]( SCH_SYMBOL* aUnitSymbol )
                        {
                            if( !aUnitSymbol )
                                return;
 
                            int unit = aUnitSymbol->GetUnitSelection( &sheet );
 
                            if( unit > 0 )
                                symbolByUnit.try_emplace( unit, aUnitSymbol );
                        };
 
                addUnitSymbol( symbol );
 
                auto extraUnitRange = extra_units.equal_range( symbol );
 
                // Collect the other placed units that share this reference so each unit number
                // can be resolved back to the specific SCH_SYMBOL instance on the sheet.
                for( auto it = extraUnitRange.first; it != extraUnitRange.second; ++it )
                    addUnitSymbol( *it );
 
                // Emit every unit slot from the default library symbol, but override that slot's
                // metadata with the placed unit's resolved library symbol when one exists.
                for( size_t unitIdx = 0; unitIdx < defaultUnitInfo.size(); ++unitIdx )
                {
                    LIB_SYMBOL::UNIT_PIN_INFO unitInfo = defaultUnitInfo[unitIdx];
                    auto                      symbolIt = symbolByUnit.find( unitIdx + 1 );
 
                    if( symbolIt != symbolByUnit.end() )
                    {
                        const std::unique_ptr<LIB_SYMBOL>& unitLibSym = symbolIt->second->GetLibSymbolRef();
 
                        if( unitLibSym )
                        {
                            const std::vector<LIB_SYMBOL::UNIT_PIN_INFO>& unitSpecificInfo =
                                    unitLibSym->GetUnitPinInfo();
 
                            if( unitIdx < unitSpecificInfo.size() )
                                unitInfo = unitSpecificInfo[unitIdx];
                        }
                    }
 
                    XNODE* xunit;
                    xunitInfo->AddChild( xunit = node( wxT( "unit" ) ) );
                    xunit->AddAttribute( wxT( "name" ), unitInfo.m_unitName );
 
                    XNODE* xpins;
                    xunit->AddChild( xpins = node( wxT( "pins" ) ) );
 
                    for( const wxString& number : unitInfo.m_pinNumbers )
                    {
                        XNODE* xpin;
                        xpins->AddChild( xpin = node( wxT( "pin" ) ) );
                        xpin->AddAttribute( wxT( "num" ), number );
                    }
                }
            }
        }
    }
 
    m_schematic->SetCurrentSheet( currentSheet );
 
    return xcomps;
}
 
 
XNODE* NETLIST_EXPORTER_XML::makeGroups()
{
    XNODE* xcomps = node( wxT( "groups" ) );
 
    m_referencesAlreadyFound.Clear();
    // Do not clear m_libParts here: it is populated in makeSymbols() and used later by
    // makeLibParts() to emit the libparts section for CvPcb and other consumers.
 
    SCH_SHEET_PATH currentSheet = m_schematic->CurrentSheet();
    SCH_SHEET_LIST sheetList = m_exportSheets;
    std::map<SCH_SCREEN*, int> screenVisits;
 
    for( const SCH_SHEET_PATH& sheet : sheetList )
        screenVisits[sheet.LastScreen()]++;
 
    for( const SCH_SHEET_PATH& sheet : sheetList )
    {
        // Change schematic CurrentSheet in each iteration to allow hierarchical
        // resolution of text variables in sheet fields.
        m_schematic->SetCurrentSheet( sheet );
 
        wxString instancePrefix = sheet.PathAsString();
 
        for( SCH_ITEM* item : sheet.LastScreen()->Items().OfType( SCH_GROUP_T ) )
        {
            SCH_GROUP* group = static_cast<SCH_GROUP*>( item );
            wxString   groupName = group->GetName();
 
            if( screenVisits[sheet.LastScreen()] > 1 )
                groupName = wxString::Format( wxT( "%s (%s)" ), groupName, sheet.PathHumanReadable() );
 
            XNODE* xgroup;  // current symbol being constructed
            xcomps->AddChild( xgroup = node( wxT( "group" ) ) );
 
            xgroup->AddAttribute( wxT( "name" ), groupName );
            xgroup->AddAttribute( wxT( "uuid" ), instancePrefix + group->m_Uuid.AsString() );
            xgroup->AddAttribute( wxT( "lib_id" ), group->GetDesignBlockLibId().Format() );
 
            XNODE* xmembers;
            xgroup->AddChild( xmembers = node( wxT( "members" ) ) );
 
            for( EDA_ITEM* member : group->GetItems() )
            {
                if( member->Type() == SCH_SYMBOL_T )
                {
                    XNODE* xmember;
                    xmembers->AddChild( xmember = node( wxT( "member" ) ) );
                    xmember->AddAttribute( wxT( "uuid" ), instancePrefix + member->m_Uuid.AsString() );
                }
                else if( member->Type() == SCH_GROUP_T )
                {
                    // Emit nested groups so the board side can rebuild the nesting.
                    XNODE* xmember;
                    xmembers->AddChild( xmember = node( wxT( "member" ) ) );
                    xmember->AddAttribute( wxT( "uuid" ), instancePrefix + member->m_Uuid.AsString() );
                }
                else if( member->Type() == SCH_SHEET_T )
                {
                    SCH_SHEET_PATH              subSheetPath = sheet;
                    std::vector<SCH_SHEET_PATH> descendantSheets;
 
                    subSheetPath.push_back( static_cast<SCH_SHEET*>( member ) );
                    sheetList.GetSheetsWithinPath( descendantSheets, subSheetPath );
 
                    for( const SCH_SHEET_PATH& descendantSheet : descendantSheets )
                    {
                        for( SCH_ITEM* descendantItem : descendantSheet.LastScreen()->Items().OfType( SCH_SYMBOL_T ) )
                        {
                            XNODE* xmember;
                            xmembers->AddChild( xmember = node( wxT( "member" ) ) );
                            xmember->AddAttribute( wxT( "uuid" ),
                                                   descendantSheet.PathAsString() + descendantItem->m_Uuid.AsString() );
                        }
                    }
                }
            }
        }
    }
 
    m_schematic->SetCurrentSheet( currentSheet );
 
    return xcomps;
}
 
 
XNODE* NETLIST_EXPORTER_XML::makeVariants()
{
    XNODE* xvariants = node( wxT( "variants" ) );
 
    std::set<wxString> variantNames = m_schematic->GetVariantNames();
 
    for( const wxString& variantName : variantNames )
    {
        XNODE* xvariant;
        xvariants->AddChild( xvariant = node( wxT( "variant" ) ) );
        xvariant->AddAttribute( wxT( "name" ), variantName );
 
        wxString description = m_schematic->GetVariantDescription( variantName );
 
        if( !description.IsEmpty() )
            xvariant->AddAttribute( wxT( "description" ), description );
    }
 
    return xvariants;
}
 
 
std::vector<wxString> NETLIST_EXPORTER_XML::getComponentClassNamesForAllSymbolUnits(
        SCH_SYMBOL* aSymbol, const SCH_SHEET_PATH& aSymbolSheet, const SCH_SHEET_LIST& aSheetList )
{
    std::vector<SCH_SHEET_PATH> symbolSheets;
    symbolSheets.push_back( aSymbolSheet );
 
    std::unordered_set<wxString> compClassNames = aSymbol->GetComponentClassNames( &aSymbolSheet, m_exportVariant );
    int                          primaryUnit = aSymbol->GetUnitSelection( &aSymbolSheet );
 
    if( aSymbol->GetUnitCount() > 1 )
    {
        const wxString ref = aSymbol->GetRef( &aSymbolSheet );
 
        for( const SCH_SHEET_PATH& sheet : aSheetList )
        {
            for( SCH_ITEM* item : sheet.LastScreen()->Items().OfType( SCH_SYMBOL_T ) )
            {
                const SCH_SYMBOL* symbol2 = static_cast<SCH_SYMBOL*>( item );
 
                wxString  ref2 = symbol2->GetRef( &sheet );
                const int otherUnit = symbol2->GetUnitSelection( &sheet );
 
                if( ref2.CmpNoCase( ref ) != 0 )
                    continue;
 
                if( otherUnit == primaryUnit )
                    continue;
 
                symbolSheets.push_back( sheet );
 
                std::unordered_set<wxString> otherClassNames = symbol2->GetComponentClassNames( &sheet,
                                                                                                m_exportVariant );
                compClassNames.insert( otherClassNames.begin(), otherClassNames.end() );
            }
        }
    }
 
    // Add sheet-level component classes
    for( auto& [sheetPath, sheetCompClasses] : m_sheetComponentClasses )
    {
        for( SCH_SHEET_PATH& symbolSheetPath : symbolSheets )
        {
            if( symbolSheetPath.IsContainedWithin( sheetPath ) )
                compClassNames.insert( sheetCompClasses.begin(), sheetCompClasses.end() );
        }
    }
 
    std::vector<wxString> sortedCompClassNames( compClassNames.begin(), compClassNames.end() );
    std::sort( sortedCompClassNames.begin(), sortedCompClassNames.end(),
               []( const wxString& str1, const wxString& str2 )
               {
                   return str1.Cmp( str2 ) < 0;
               } );
 
    return sortedCompClassNames;
}
 
 
XNODE* NETLIST_EXPORTER_XML::makeDesignHeader()
{
    SCH_SCREEN* screen;
    XNODE*      xdesign = node( wxT( "design" ) );
    XNODE*      xtitleBlock;
    XNODE*      xsheet;
    XNODE*      xcomment;
    XNODE*      xtextvar;
    wxString    sheetTxt;
    wxFileName  sourceFileName;
 
    // the root sheet is a special sheet, call it source
    xdesign->AddChild( node( wxT( "source" ), m_schematic->GetFileName() ) );
 
    xdesign->AddChild( node( wxT( "date" ), GetISO8601CurrentDateTime() ) );
 
    // which Eeschema tool
    xdesign->AddChild( node( wxT( "tool" ), wxT( "Eeschema " ) + GetBuildVersion() ) );
 
    const std::map<wxString, wxString>& properties = m_schematic->Project().GetTextVars();
 
    for( const std::pair<const wxString, wxString>& prop : properties )
    {
        xdesign->AddChild( xtextvar = node( wxT( "textvar" ), prop.second ) );
        xtextvar->AddAttribute( wxT( "name" ), prop.first );
    }
 
    /*
     *  Export the sheets information
     */
    unsigned sheetIndex = 1;     // Human readable index
 
    for( const SCH_SHEET_PATH& sheet : m_exportSheets )
    {
        screen = sheet.LastScreen();
 
        xdesign->AddChild( xsheet = node( wxT( "sheet" ) ) );
 
        // get the string representation of the sheet index number.
        sheetTxt.Printf( wxT( "%u" ), sheetIndex++ );
        xsheet->AddAttribute( wxT( "number" ), sheetTxt );
        xsheet->AddAttribute( wxT( "name" ), sheet.PathHumanReadable() );
        xsheet->AddAttribute( wxT( "tstamps" ), sheet.PathAsString() );
 
        TITLE_BLOCK tb = screen->GetTitleBlock();
        PROJECT*    prj = &m_schematic->Project();
 
        xsheet->AddChild( xtitleBlock = node( wxT( "title_block" ) ) );
 
        xtitleBlock->AddChild( node( wxT( "title" ), ExpandTextVars( tb.GetTitle(), prj, m_resolveTextVars ) ) );
        xtitleBlock->AddChild( node( wxT( "company" ), ExpandTextVars( tb.GetCompany(), prj, m_resolveTextVars ) ) );
        xtitleBlock->AddChild( node( wxT( "rev" ), ExpandTextVars( tb.GetRevision(), prj, m_resolveTextVars ) ) );
        xtitleBlock->AddChild( node( wxT( "date" ), ExpandTextVars( tb.GetDate(), prj, m_resolveTextVars ) ) );
 
        // We are going to remove the fileName directories.
        sourceFileName = wxFileName( screen->GetFileName() );
        xtitleBlock->AddChild( node( wxT( "source" ), sourceFileName.GetFullName() ) );
 
        xtitleBlock->AddChild( xcomment = node( wxT( "comment" ) ) );
        xcomment->AddAttribute( wxT( "number" ), wxT( "1" ) );
        xcomment->AddAttribute( wxT( "value" ), ExpandTextVars( tb.GetComment( 0 ), prj, m_resolveTextVars ) );
 
        xtitleBlock->AddChild( xcomment = node( wxT( "comment" ) ) );
        xcomment->AddAttribute( wxT( "number" ), wxT( "2" ) );
        xcomment->AddAttribute( wxT( "value" ), ExpandTextVars( tb.GetComment( 1 ), prj, m_resolveTextVars ) );
 
        xtitleBlock->AddChild( xcomment = node( wxT( "comment" ) ) );
        xcomment->AddAttribute( wxT( "number" ), wxT( "3" ) );
        xcomment->AddAttribute( wxT( "value" ), ExpandTextVars( tb.GetComment( 2 ), prj, m_resolveTextVars ) );
 
        xtitleBlock->AddChild( xcomment = node( wxT( "comment" ) ) );
        xcomment->AddAttribute( wxT( "number" ), wxT( "4" ) );
        xcomment->AddAttribute( wxT( "value" ), ExpandTextVars( tb.GetComment( 3 ), prj, m_resolveTextVars ) );
 
        xtitleBlock->AddChild( xcomment = node( wxT( "comment" ) ) );
        xcomment->AddAttribute( wxT( "number" ), wxT( "5" ) );
        xcomment->AddAttribute( wxT( "value" ), ExpandTextVars( tb.GetComment( 4 ), prj, m_resolveTextVars ) );
 
        xtitleBlock->AddChild( xcomment = node( wxT( "comment" ) ) );
        xcomment->AddAttribute( wxT( "number" ), wxT( "6" ) );
        xcomment->AddAttribute( wxT( "value" ), ExpandTextVars( tb.GetComment( 5 ), prj, m_resolveTextVars ) );
 
        xtitleBlock->AddChild( xcomment = node( wxT( "comment" ) ) );
        xcomment->AddAttribute( wxT( "number" ), wxT( "7" ) );
        xcomment->AddAttribute( wxT( "value" ), ExpandTextVars( tb.GetComment( 6 ), prj, m_resolveTextVars ) );
 
        xtitleBlock->AddChild( xcomment = node( wxT( "comment" ) ) );
        xcomment->AddAttribute( wxT( "number" ), wxT( "8" ) );
        xcomment->AddAttribute( wxT( "value" ), ExpandTextVars( tb.GetComment( 7 ), prj, m_resolveTextVars ) );
 
        xtitleBlock->AddChild( xcomment = node( wxT( "comment" ) ) );
        xcomment->AddAttribute( wxT( "number" ), wxT( "9" ) );
        xcomment->AddAttribute( wxT( "value" ), ExpandTextVars( tb.GetComment( 8 ), prj, m_resolveTextVars ) );
    }
 
    return xdesign;
}
 
 
XNODE* NETLIST_EXPORTER_XML::makeLibraries()
{
    XNODE*            xlibs = node( wxT( "libraries" ) );     // auto_ptr
    LIBRARY_MANAGER& manager = Pgm().GetLibraryManager();
 
    for( const wxString& libNickname : m_libraries )
    {
        XNODE* xlibrary;
 
        std::optional<wxString> uri = manager.GetFullURI( LIBRARY_TABLE_TYPE::SYMBOL, libNickname );
 
        if( uri )
        {
            xlibs->AddChild( xlibrary = node( wxT( "library" ) ) );
            xlibrary->AddAttribute( wxT( "logical" ), libNickname );
            xlibrary->AddChild( node( wxT( "uri" ), *uri  ) );
        }
    }
 
    return xlibs;
}
 
 
XNODE* NETLIST_EXPORTER_XML::makeLibParts()
{
    XNODE*                  xlibparts = node( wxT( "libparts" ) );   // auto_ptr
    std::vector<SCH_FIELD*> fieldList;
 
    m_libraries.clear();
 
    for( LIB_SYMBOL* lcomp : m_libParts )
    {
        wxString libNickname = lcomp->GetLibId().GetLibNickname();;
 
        // The library nickname will be empty if the cache library is used.
        if( !libNickname.IsEmpty() )
            m_libraries.insert( libNickname );  // inserts symbol's library if unique
 
        XNODE* xlibpart;
        xlibparts->AddChild( xlibpart = node( wxT( "libpart" ) ) );
        xlibpart->AddAttribute( wxT( "lib" ), libNickname );
        xlibpart->AddAttribute( wxT( "part" ), lcomp->GetName()  );
 
        //----- show the important properties -------------------------
        if( !lcomp->GetDescription().IsEmpty() )
            xlibpart->AddChild( node( wxT( "description" ), lcomp->GetDescription() ) );
 
        if( !lcomp->GetDatasheetField().GetText().IsEmpty() )
            xlibpart->AddChild( node( wxT( "docs" ),  lcomp->GetDatasheetField().GetText() ) );
 
        // Write the footprint list
        if( lcomp->GetFPFilters().GetCount() )
        {
            XNODE*  xfootprints;
            xlibpart->AddChild( xfootprints = node( wxT( "footprints" ) ) );
 
            for( unsigned i = 0; i < lcomp->GetFPFilters().GetCount(); ++i )
            {
                if( !lcomp->GetFPFilters()[i].IsEmpty() )
                    xfootprints->AddChild( node( wxT( "fp" ), lcomp->GetFPFilters()[i] ) );
            }
        }
 
        //----- show the fields here ----------------------------------
        fieldList.clear();
        lcomp->GetFields( fieldList );
 
        XNODE*     xfields;
        xlibpart->AddChild( xfields = node( "fields" ) );
 
        for( const SCH_FIELD* field : fieldList )
        {
            XNODE* xfield;
            xfields->AddChild( xfield = node( wxT( "field" ), field->GetText() ) );
            xfield->AddAttribute( wxT( "name" ), field->GetUntranslatedName() );
        }
 
    //----- show the pins here ------------------------------------
    // NOTE: Expand stacked-pin notation into individual pins so downstream
    // tools (e.g. CvPcb) see the actual number of footprint pins.
    std::vector<SCH_PIN*> pinList = lcomp->GetGraphicalPins( 0, 0 );
 
        /*
         * We must erase redundant Pins references in pinList
         * These redundant pins exist because some pins are found more than one time when a
         * symbol has multiple parts per package or has 2 representations (DeMorgan conversion).
         * For instance, a 74ls00 has DeMorgan conversion, with different pin shapes, and
         * therefore each pin  appears 2 times in the list. Common pins (VCC, GND) can also be
         * found more than once.
         */
        sort( pinList.begin(), pinList.end(), sortPinsByNumber );
 
        for( int ii = 0; ii < (int)pinList.size()-1; ii++ )
        {
            if( pinList[ii]->GetNumber() == pinList[ii+1]->GetNumber() )
            {   // 2 pins have the same number, remove the redundant pin at index i+1
                pinList.erase(pinList.begin() + ii + 1);
                ii--;
            }
        }
 
        wxLogTrace( "CVPCB_PINCOUNT",
                wxString::Format( "makeLibParts: lib='%s' part='%s' pinList(size)=%zu",
                          libNickname, lcomp->GetName(), pinList.size() ) );
 
        if( pinList.size() )
        {
            XNODE*     pins;
 
            xlibpart->AddChild( pins = node( wxT( "pins" ) ) );
 
            for( unsigned i=0; i<pinList.size();  ++i )
            {
                SCH_PIN* basePin = pinList[i];
 
                bool                     stackedValid = false;
                std::vector<wxString>    expandedNums = basePin->GetStackedPinNumbers( &stackedValid );
 
                // If stacked notation detected and valid, emit one libparts pin per expanded number.
                if( stackedValid && !expandedNums.empty() )
                {
                    for( const wxString& num : expandedNums )
                    {
                        XNODE* pin;
                        pins->AddChild( pin = node( wxT( "pin" ) ) );
                        pin->AddAttribute( wxT( "num" ), num );
                        pin->AddAttribute( wxT( "name" ), basePin->GetShownName() );
                        pin->AddAttribute( wxT( "type" ), basePin->GetCanonicalElectricalTypeName() );
 
                        wxLogTrace( "CVPCB_PINCOUNT",
                                    wxString::Format( "makeLibParts: -> pin num='%s' name='%s' (expanded)",
                                                      num, basePin->GetShownName() ) );
                    }
                }
                else
                {
                    XNODE* pin;
                    pins->AddChild( pin = node( wxT( "pin" ) ) );
                    pin->AddAttribute( wxT( "num" ), basePin->GetShownNumber() );
                    pin->AddAttribute( wxT( "name" ), basePin->GetShownName() );
                    pin->AddAttribute( wxT( "type" ), basePin->GetCanonicalElectricalTypeName() );
 
                    wxLogTrace( "CVPCB_PINCOUNT",
                                wxString::Format( "makeLibParts: -> pin num='%s' name='%s'",
                                                  basePin->GetShownNumber(),
                                                  basePin->GetShownName() ) );
                }
 
                // caution: construction work site here, drive slowly
            }
        }
    }
 
    return xlibparts;
}
 
 
XNODE* NETLIST_EXPORTER_XML::makeListOfNets( unsigned aCtl )
{
    wxString netCodeTxt;
    XNODE*   xnets = node( wxT( "nets" ) ); // auto_ptr if exceptions ever get used.
    XNODE*   xnet = nullptr;
 
    /*  output:
        <net code="123" name="/cfcard.sch/WAIT#" class="signal">
            <node ref="R23" pin="1"/>
            <node ref="U18" pin="12"/>
        </net>
    */
 
    struct NET_NODE
    {
        NET_NODE( SCH_PIN* aPin, const SCH_SHEET_PATH& aSheet ) :
                m_Pin( aPin ),
                m_Sheet( aSheet )
        {}
 
        SCH_PIN*       m_Pin;
        SCH_SHEET_PATH m_Sheet;
    };
 
    struct NET_RECORD
    {
        NET_RECORD( const wxString& aName ) :
                m_Name( aName ),
                m_HasNoConnect( false )
        {};
 
        wxString              m_Name;
        wxString              m_Class;
        bool                  m_HasNoConnect;
        std::vector<NET_NODE> m_Nodes;
    };
 
    std::vector<NET_RECORD*> nets;
 
    std::shared_ptr<NET_SETTINGS> netSettings;
 
    if( m_schematic )
        netSettings = m_schematic->Project().GetProjectFile().NetSettings();
 
    for( const EXPORT_NET& net : m_exportNets )
    {
        wxString netName = ( aCtl & GNL_OPT_KICAD ) ? net.name : UnescapeString( net.name );
        nets.emplace_back( new NET_RECORD( netName ) );
        NET_RECORD* net_record = nets.back();
        net_record->m_HasNoConnect = net.hasNoConnect;
 
        if( netSettings )
        {
            if( const auto netclass = netSettings->GetEffectiveNetClass( net.name ) )
                net_record->m_Class = UnescapeString( netclass->GetName() );
        }
 
        for( const auto& [pin, sheet] : net.pins )
        {
            SCH_SYMBOL* symbol = dynamic_cast<SCH_SYMBOL*>( pin->GetParentSymbol() );
            bool        forBOM = aCtl & GNL_OPT_BOM;
            bool        forBoard = aCtl & GNL_OPT_KICAD;
 
            if( !symbol )
                continue;
 
            if( forBOM && ( sheet.GetExcludedFromBOM( m_exportVariant )
                           || symbol->ResolveExcludedFromBOM( &sheet, m_exportVariant ) ) )
            {
                continue;
            }
 
            if( forBoard && ( sheet.GetExcludedFromBoard( m_exportVariant )
                             || symbol->ResolveExcludedFromBoard( &sheet, m_exportVariant ) ) )
            {
                continue;
            }
 
            net_record->m_Nodes.emplace_back( pin, sheet );
        }
    }
 
    // Netlist ordering: Net name, then ref des, then pin name
    std::sort( nets.begin(), nets.end(),
               []( const NET_RECORD* a, const NET_RECORD*b )
               {
                   return StrNumCmp( a->m_Name, b->m_Name ) < 0;
               } );
 
    for( int i = 0; i < (int) nets.size(); ++i )
    {
        NET_RECORD* net_record = nets[i];
        bool        added = false;
        XNODE*      xnode;
 
        // Netlist ordering: Net name, then ref des, then pin name
        std::sort( net_record->m_Nodes.begin(), net_record->m_Nodes.end(),
                []( const NET_NODE& a, const NET_NODE& b )
                {
                    wxString refA = a.m_Pin->GetParentSymbol()->GetRef( &a.m_Sheet );
                    wxString refB = b.m_Pin->GetParentSymbol()->GetRef( &b.m_Sheet );
 
                    if( refA == refB )
                        return a.m_Pin->GetShownNumber() < b.m_Pin->GetShownNumber();
 
                    return refA < refB;
                } );
 
        // Some duplicates can exist, for example on multi-unit parts with duplicated pins across
        // units.  If the user connects the pins on each unit, they will appear on separate
        // subgraphs.  Remove those here:
        alg::remove_duplicates( net_record->m_Nodes,
                []( const NET_NODE& a, const NET_NODE& b )
                {
                    wxString refA = a.m_Pin->GetParentSymbol()->GetRef( &a.m_Sheet );
                    wxString refB = b.m_Pin->GetParentSymbol()->GetRef( &b.m_Sheet );
 
                    return refA == refB && a.m_Pin->GetShownNumber() == b.m_Pin->GetShownNumber();
                } );
 
        // Determine if all pins in the net are stacked (nets with only one pin are implicitly
        // taken to be stacked)
        bool allNetPinsStacked = true;
 
        if( net_record->m_Nodes.size() > 1 )
        {
            SCH_PIN* firstPin = net_record->m_Nodes.begin()->m_Pin;
            allNetPinsStacked = std::all_of( net_record->m_Nodes.begin() + 1, net_record->m_Nodes.end(),
                    [=]( NET_NODE& node )
                    {
                        return firstPin->GetParent() == node.m_Pin->GetParent()
                               && firstPin->GetPosition() == node.m_Pin->GetPosition()
                               && firstPin->GetName() == node.m_Pin->GetName();
                    } );
        }
 
        for( const NET_NODE& netNode : net_record->m_Nodes )
        {
            wxString refText = netNode.m_Pin->GetParentSymbol()->GetRef( &netNode.m_Sheet );
 
            // Skip power symbols and virtual symbols
            if( refText[0] == wxChar( '#' ) )
                continue;
 
            // Emit the resolved footprint pad number(s), not the raw symbol pin number, so a
            // remapped pin's net lands on the right pad when the board reads this netlist
            // (issue #2282).  Shared with the PIN_INFO path via resolvePadNumbers.
            std::vector<wxString> nums = resolvePadNumbers( netNode.m_Pin, netNode.m_Sheet );
 
            // An unmapped pin contributes no pad, so skip it and do not open an empty net for it.
            if( nums.empty() )
                continue;
 
            wxString baseName = netNode.m_Pin->GetShownName();
            wxString pinType = netNode.m_Pin->GetCanonicalElectricalTypeName();
 
            if( !added )
            {
                netCodeTxt.Printf( wxT( "%d" ), i + 1 );
 
                xnets->AddChild( xnet = node( wxT( "net" ) ) );
                xnet->AddAttribute( wxT( "code" ), netCodeTxt );
                xnet->AddAttribute( wxT( "name" ), net_record->m_Name );
                xnet->AddAttribute( wxT( "class" ), net_record->m_Class );
 
                added = true;
            }
 
            for( const wxString& num : nums )
            {
                xnet->AddChild( xnode = node( wxT( "node" ) ) );
                xnode->AddAttribute( wxT( "ref" ), refText );
                xnode->AddAttribute( wxT( "pin" ), num );
 
                wxString fullName = baseName.IsEmpty() ? num : baseName + wxT( "_" ) + num;
 
                if( !baseName.IsEmpty() || nums.size() > 1 )
                    xnode->AddAttribute( wxT( "pinfunction" ), fullName );
 
                wxString typeAttr = pinType;
 
                if( net_record->m_HasNoConnect
                    && ( net_record->m_Nodes.size() == 1 || allNetPinsStacked ) )
                {
                    typeAttr += wxT( "+no_connect" );
                }
 
                xnode->AddAttribute( wxT( "pintype" ), typeAttr );
            }
        }
    }
 
    for( NET_RECORD* record : nets )
        delete record;
 
    return xnets;
}
 
XNODE* NETLIST_EXPORTER_XML::makeNetChains()
{
    const auto& committed = m_schematic->NetChains().GetCommittedNetChains();
 
    if( committed.empty() )
        return nullptr;
 
    XNODE* xchains = node( wxT( "net_chains" ) );
 
    for( const std::unique_ptr<SCH_NETCHAIN>& chain : committed )
    {
        if( !chain )
            continue;
 
        XNODE* xchain;
        xchains->AddChild( xchain = node( wxT( "net_chain" ) ) );
        xchain->AddAttribute( wxT( "name" ), chain->GetName() );
 
        if( !chain->GetNetClass().IsEmpty() )
            xchain->AddAttribute( wxT( "net_class" ), chain->GetNetClass() );
 
        // Carry the chain's class assignment (from project's NET_SETTINGS) so
        // that downstream consumers of the netlist can see chain hierarchy
        // without having to also parse the .kicad_pro file.
        if( m_schematic )
        {
            PROJECT_FILE& pf = m_schematic->Project().GetProjectFile();
            const std::shared_ptr<NET_SETTINGS>& ns = pf.NetSettings();
 
            if( ns )
            {
                wxString className = ns->GetNetChainClass( chain->GetName() );
 
                if( !className.IsEmpty() )
                    xchain->AddAttribute( wxT( "net_chain_class" ), className );
            }
        }
 
        if( chain->GetColor() != COLOR4D::UNSPECIFIED )
        {
            const COLOR4D& c = chain->GetColor();
            xchain->AddAttribute( wxT( "color" ),
                                   wxString::Format( wxT( "#%02X%02X%02X%02X" ),
                                                     (int) std::clamp( KiROUND( c.r * 255.0 ), 0, 255 ),
                                                     (int) std::clamp( KiROUND( c.g * 255.0 ), 0, 255 ),
                                                     (int) std::clamp( KiROUND( c.b * 255.0 ), 0, 255 ),
                                                     (int) std::clamp( KiROUND( c.a * 255.0 ), 0, 255 ) ) );
        }
 
        XNODE* xmembers;
        xchain->AddChild( xmembers = node( wxT( "members" ) ) );
 
        // Synthetic per-run subgraph names (__SG_*) embed run-specific subgraph codes
        // that do not survive a reload, and downstream consumers cannot resolve them
        // back to a real net.  Mirror the sexpr writer's filter so the XML output is
        // limited to nets that have stable, user-visible names.
        for( const wxString& net : chain->GetNets() )
        {
            if( !SCH_NETCHAIN::IsPersistableNet( net ) )
                continue;
 
            XNODE* xmember;
            xmembers->AddChild( xmember = node( wxT( "member" ) ) );
            xmember->AddAttribute( wxT( "net" ), net );
        }
 
        if( !chain->GetTerminalRef( 0 ).IsEmpty() || !chain->GetTerminalRef( 1 ).IsEmpty() )
        {
            XNODE* xterms;
            xchain->AddChild( xterms = node( wxT( "terminal_pins" ) ) );
 
            for( int i = 0; i < 2; ++i )
            {
                if( chain->GetTerminalRef( i ).IsEmpty() )
                    continue;
 
                XNODE* xterm;
                xterms->AddChild( xterm = node( wxT( "terminal_pin" ) ) );
                xterm->AddAttribute( wxT( "ref" ), chain->GetTerminalRef( i ) );
                xterm->AddAttribute( wxT( "pin" ), chain->GetTerminalPinNum( i ) );
            }
        }
    }
 
    return xchains;
}
 
 
XNODE* NETLIST_EXPORTER_XML::node( const wxString& aName, const wxString& aTextualContent )
{
    XNODE* n = new XNODE( wxXML_ELEMENT_NODE, aName );
 
    if( aTextualContent.Len() > 0 )     // excludes wxEmptyString, the parameter's default value
        n->AddChild( new XNODE( wxXML_TEXT_NODE, wxEmptyString, aTextualContent ) );
 
    return n;
}
 
 
static bool sortPinsByNumber( SCH_PIN* aPin1, SCH_PIN* aPin2 )
{
    // return "lhs < rhs"
    return StrNumCmp( aPin1->GetShownNumber(), aPin2->GetShownNumber(), true ) < 0;
}
 
 
void NETLIST_EXPORTER_XML::getSheetComponentClasses()
{
    m_sheetComponentClasses.clear();
 
    SCH_SHEET_LIST sheetList = m_exportSheets;
 
    auto getComponentClassFields =
            [&]( const std::vector<SCH_FIELD>& fields, const SCH_SHEET_PATH* sheetPath )
            {
                std::unordered_set<wxString> componentClasses;
 
                for( const SCH_FIELD& field : fields )
                {
                    if( field.GetUntranslatedName() == wxT( "Component Class" ) )
                    {
                        if( field.GetShownText( sheetPath, m_resolveTextVars ) != wxEmptyString )
                            componentClasses.insert( field.GetShownText( sheetPath, m_resolveTextVars ) );
                    }
                }
 
                return componentClasses;
            };
 
    for( const SCH_SHEET_PATH& sheet : sheetList )
    {
        for( SCH_ITEM* item : sheet.LastScreen()->Items().OfType( SCH_SHEET_T ) )
        {
            SCH_SHEET*                                sheetItem = static_cast<SCH_SHEET*>( item );
            std::unordered_set<wxString>              sheetComponentClasses;
            const std::unordered_set<SCH_RULE_AREA*>& sheetRuleAreas = sheetItem->GetRuleAreaCache();
 
            for( const SCH_RULE_AREA* ruleArea : sheetRuleAreas )
            {
                for( const SCH_DIRECTIVE_LABEL* label : ruleArea->GetDirectives() )
                {
                    std::unordered_set<wxString> ruleAreaComponentClasses = getComponentClassFields( label->GetFields(),
                                                                                                     &sheet );
                    sheetComponentClasses.insert( ruleAreaComponentClasses.begin(), ruleAreaComponentClasses.end() );
                }
            }
 
            SCH_SHEET_PATH newPath = sheet;
            newPath.push_back( sheetItem );
            wxASSERT( !m_sheetComponentClasses.contains( newPath ) );
 
            m_sheetComponentClasses[newPath] = sheetComponentClasses;
        }
    }
}