pcbexpr_functions.cpp

Go to the documentation of this file.

/*
 * This program source code file is part of KiCad, a free EDA CAD application.
 *
 * 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 <algorithm>
#include <cstdio>
#include <memory>
#include <mutex>
#include <set>
 
#include <wx/log.h>
 
#include <board.h>
#include <board_design_settings.h>
#include <project/net_settings.h>
#include <component_classes/component_class.h>
#include <drc/drc_rtree.h>
#include <drc/drc_engine.h>
#include <footprint.h>
#include <footprint_courtyard_index.h>
#include <lset.h>
#include <pad.h>
#include <pcb_track.h>
#include <pcb_group.h>
#include <geometry/shape_segment.h>
#include <pcbexpr_evaluator.h>
#include <connectivity/connectivity_data.h>
#include <connectivity/connectivity_algo.h>
#include <connectivity/from_to_cache.h>
#include <properties/property.h>
#include <properties/property_mgr.h>
 
 
bool fromToFunc( LIBEVAL::CONTEXT* aCtx, void* self )
{
    PCBEXPR_VAR_REF* vref = static_cast<PCBEXPR_VAR_REF*>( self );
    BOARD_ITEM*      item = vref ? vref->GetObject( aCtx ) : nullptr;
    LIBEVAL::VALUE*  result = aCtx->AllocValue();
    LIBEVAL::VALUE*  argTo = aCtx->Pop();
    LIBEVAL::VALUE*  argFrom = aCtx->Pop();
 
    result->Set(0.0);
    aCtx->Push( result );
 
    if( !item )
        return false;
 
    if( !argFrom || argFrom->AsString().IsEmpty() )
    {
        if( aCtx->HasErrorCallback() )
        {
            aCtx->ReportError( wxString::Format( _( "Missing 'from' pad argument (footprint reference designator "
                                                    "followed by hyphen and pad number) to %s." ),
                                                 wxT( "fromTo()" ) ) );
        }
 
        return false;
    }
 
    if( !argTo || argTo->AsString().IsEmpty() )
    {
        if( aCtx->HasErrorCallback() )
        {
            aCtx->ReportError( wxString::Format( _( "Missing 'to' pad argument (footprint reference designator "
                                                    "followed by hyphen and pad number) to %s." ),
                                                 wxT( "fromTo()" ) ) );
        }
 
        return false;
    }
 
    auto ftCache = item->GetBoard()->GetConnectivity()->GetFromToCache();
 
    if( !ftCache )
    {
        wxLogWarning( wxT( "Attempting to call fromTo() with non-existent from-to cache." ) );
        return true;
    }
 
    if( ftCache->IsOnFromToPath( static_cast<BOARD_CONNECTED_ITEM*>( item ), argFrom->AsString(), argTo->AsString() ) )
        result->Set(1.0);
 
    return true;
}
 
 
static void existsOnLayerFunc( LIBEVAL::CONTEXT* aCtx, void *self )
{
    PCBEXPR_VAR_REF* vref = static_cast<PCBEXPR_VAR_REF*>( self );
    BOARD_ITEM*      item = vref ? vref->GetObject( aCtx ) : nullptr;
    LIBEVAL::VALUE*  arg = aCtx->Pop();
    LIBEVAL::VALUE*  result = aCtx->AllocValue();
 
    result->Set( 0.0 );
    aCtx->Push( result );
 
    if( !item )
        return;
 
    if( !arg || arg->AsString().IsEmpty() )
    {
        if( aCtx->HasErrorCallback() )
        {
            aCtx->ReportError( wxString::Format( _( "Missing layer name argument to %s." ),
                                                 wxT( "existsOnLayer()" ) ) );
        }
 
        return;
    }
 
    result->SetDeferredEval(
            [item, arg, aCtx]() -> double
            {
                const wxString& layerName = arg->AsString();
                wxPGChoices& layerMap = ENUM_MAP<PCB_LAYER_ID>::Instance().Choices();
 
                if( aCtx->HasErrorCallback())
                {
                    /*
                     * Interpreted version
                     */
 
                    bool anyMatch = false;
 
                    for( unsigned ii = 0; ii < layerMap.GetCount(); ++ii )
                    {
                        wxPGChoiceEntry& entry = layerMap[ ii ];
 
                        if( entry.GetText().Matches( layerName ))
                        {
                            anyMatch = true;
 
                            if( item->IsOnLayer( ToLAYER_ID( entry.GetValue() ) ) )
                                return 1.0;
                        }
                    }
 
                    if( !anyMatch )
                    {
                        aCtx->ReportError( wxString::Format( _( "Unrecognized layer '%s'" ),
                                                             layerName ) );
                    }
 
                    return 0.0;
                }
                else
                {
                    /*
                     * Compiled version
                     */
 
                    BOARD* board = item->GetBoard();
 
                    {
                        std::shared_lock<std::shared_mutex> readLock( board->m_CachesMutex );
 
                        auto i = board->m_LayerExpressionCache.find( layerName );
 
                        if( i != board->m_LayerExpressionCache.end() )
                            return ( item->GetLayerSet() & i->second ).any() ? 1.0 : 0.0;
                    }
 
                    LSET mask;
 
                    for( unsigned ii = 0; ii < layerMap.GetCount(); ++ii )
                    {
                        wxPGChoiceEntry& entry = layerMap[ ii ];
 
                        if( entry.GetText().Matches( layerName ) )
                            mask.set( ToLAYER_ID( entry.GetValue() ) );
                    }
 
                    {
                        std::unique_lock<std::shared_mutex> writeLock( board->m_CachesMutex );
                        board->m_LayerExpressionCache[ layerName ] = mask;
                    }
 
                    return ( item->GetLayerSet() & mask ).any() ? 1.0 : 0.0;
                }
            } );
}
 
 
static void isPlatedFunc( LIBEVAL::CONTEXT* aCtx, void* self )
{
    LIBEVAL::VALUE* result = aCtx->AllocValue();
 
    result->Set( 0.0 );
    aCtx->Push( result );
 
    PCBEXPR_VAR_REF* vref = static_cast<PCBEXPR_VAR_REF*>( self );
    BOARD_ITEM*       item = vref ? vref->GetObject( aCtx ) : nullptr;
 
    if( !item )
        return;
 
    if( item->Type() == PCB_PAD_T && static_cast<PAD*>( item )->GetAttribute() == PAD_ATTRIB::PTH )
        result->Set( 1.0 );
    else if( item->Type() == PCB_VIA_T )
        result->Set( 1.0 );
}
 
 
bool collidesWithCourtyard( BOARD_ITEM* aItem, std::shared_ptr<SHAPE>& aItemShape,
                            PCBEXPR_CONTEXT* aCtx, FOOTPRINT* aFootprint, PCB_LAYER_ID aSide )
{
    const SHAPE_POLY_SET& footprintCourtyard = aFootprint->GetCourtyard( aSide );
 
    if( footprintCourtyard.OutlineCount() == 0 )
        return false;
 
    // Broad phase before the polygon-level Collide, which dominates when a rule tests a
    // courtyard against many items (intersectsCourtyard('*') over a full board). A bbox miss
    // cannot collide, so the expensive shape build and Collide are skipped.
    if( !footprintCourtyard.BBox().Intersects( aItem->GetBoundingBox() ) )
        return false;
 
    if( aItemShape )
    {
        return footprintCourtyard.Collide( aItemShape.get() );
    }
    else if( ZONE* zone = dynamic_cast<ZONE*>( aItem ) )
    {
        // Since rules are used for zone filling we can't rely on the filled shapes.  Use the
        // zone  outline instead.
        SHAPE_POLY_SET  zoneOutlineStorage;
        SHAPE_POLY_SET* zoneOutline = &zoneOutlineStorage;
 
        if( zone->GetParentFootprint() )
            zoneOutlineStorage = zone->GetBoardOutline();
        else
            zoneOutline = zone->Outline();
 
        return footprintCourtyard.Collide( zoneOutline );
    }
    else
    {
        return footprintCourtyard.Collide( aItem->GetEffectiveShape( aCtx->GetLayer() ).get() );
    }
};
 
 
static bool testFootprintSelector( FOOTPRINT* aFp, const wxString& aSelector )
{
    // NOTE: This code may want to be somewhat more generalized, but for now it's implemented
    // here to support functions like insersectsCourtyard where we want multiple ways to search
    // for the footprints in question.
    // If support for text variable replacement is added, it should happen before any other
    // logic here, so that people can use text variables to contain references or LIBIDs.
    // (see: https://gitlab.com/kicad/code/kicad/-/issues/11231)
 
    if( aSelector.IsEmpty() )
        return false;
 
    // First check if we have a known directive
    if( aSelector[0] == '$' && aSelector.Last() == '}' && aSelector.Upper().StartsWith( wxT( "${CLASS:" ) ) )
    {
        wxString name = aSelector.Mid( 8, aSelector.Length() - 9 );
 
        const COMPONENT_CLASS* compClass = aFp->GetComponentClass();
 
        if( compClass && compClass->ContainsClassName( name ) )
            return true;
    }
    else if( aFp->GetReference().Matches( aSelector ) )
    {
        return true;
    }
    else if( aSelector.Find( ':' ) != wxNOT_FOUND && aFp->GetFPIDAsString().Matches( aSelector ) )
    {
        return true;
    }
 
    return false;
}
 
 
/*
 * Find footprints relevant to a courtyard-intersection predicate.  "A"/"B" resolve to the items
 * under test; any other selector is matched against the footprints whose courtyard can actually
 * reach aItem, found via the spatial index rather than a full-board scan.  A footprint the index
 * skips would fail the same bbox test collidesWithCourtyard() applies, so the result matches a
 * linear scan.
 */
static bool searchFootprintsNearItem( BOARD* aBoard, const wxString& aArg, PCBEXPR_CONTEXT* aCtx,
                                      BOARD_ITEM* aItem, const std::function<bool( FOOTPRINT* )>& aFunc )
{
    if( aArg == wxT( "A" ) )
    {
        FOOTPRINT* fp = dynamic_cast<FOOTPRINT*>( aCtx->GetItem( 0 ) );
        return fp && aFunc( fp );
    }
    else if( aArg == wxT( "B" ) )
    {
        FOOTPRINT* fp = dynamic_cast<FOOTPRINT*>( aCtx->GetItem( 1 ) );
        return fp && aFunc( fp );
    }
 
    bool found = false;
 
    // Hold the index alive for the whole query; a concurrent IncrementTimeStamp() may detach the
    // board's copy while we iterate.
    std::shared_ptr<const FOOTPRINT_COURTYARD_INDEX> index = aBoard->GetFootprintCourtyardIndex();
 
    index->QueryOverlapping( aItem->GetBoundingBox(),
            [&]( FOOTPRINT* fp ) -> bool
            {
                if( testFootprintSelector( fp, aArg ) && aFunc( fp ) )
                {
                    found = true;
                    return false;
                }
 
                return true;
            } );
 
    return found;
}
 
 
#define MISSING_FP_ARG( f ) \
    wxString::Format( _( "Missing footprint argument (A, B, or reference designator) to %s." ), f )
 
static void intersectsCourtyardFunc( LIBEVAL::CONTEXT* aCtx, void* self )
{
    PCBEXPR_CONTEXT* context = static_cast<PCBEXPR_CONTEXT*>( aCtx );
    LIBEVAL::VALUE*  arg = context->Pop();
    LIBEVAL::VALUE*  result = context->AllocValue();
 
    result->Set( 0.0 );
    context->Push( result );
 
    if( !arg || arg->AsString().IsEmpty() )
    {
        if( context->HasErrorCallback() )
            context->ReportError( MISSING_FP_ARG( wxT( "intersectsCourtyard()" ) ) );
 
        return;
    }
 
    PCBEXPR_VAR_REF* vref = static_cast<PCBEXPR_VAR_REF*>( self );
    BOARD_ITEM*      item = vref ? vref->GetObject( context ) : nullptr;
 
    if( !item )
        return;
 
    result->SetDeferredEval(
            [item, arg, context]() -> double
            {
                BOARD*         board = item->GetBoard();
                bool           transient = ( item->GetFlags() & ROUTER_TRANSIENT ) != 0;
                const wxString selector = arg->AsString();
 
                // Whole-predicate memo: the same condition repeated across many rules resolves
                // in O(1) here instead of re-scanning every footprint.  "A"/"B" select the other
                // item of the current pair rather than a board-wide set, so they cannot be keyed
                // by item alone (and touch only one footprint anyway); skip the memo for those.
                bool memoize = !transient && selector != wxT( "A" ) && selector != wxT( "B" );
 
                ITEM_SELECTOR_LAYER_CACHE_KEY rkey{ item, selector, context->GetLayer(),
                                                    context->GetConstraint() };
                bool whole = false;
 
                if( memoize && board->m_IntersectsCourtyardResultCache.Get( rkey, whole ) )
                    return whole ? 1.0 : 0.0;
 
                std::shared_ptr<SHAPE> itemShape;
 
                bool res = searchFootprintsNearItem( board, selector, context, item,
                        [&]( FOOTPRINT* fp )
                        {
                            PTR_PTR_CACHE_KEY key = { fp, item };
                            bool              cached = false;
 
                            if( !transient && board->m_IntersectsCourtyardCache.Get( key, cached ) )
                                return cached;
 
                            bool hit = collidesWithCourtyard( item, itemShape, context, fp, F_Cu )
                                    || collidesWithCourtyard( item, itemShape, context, fp, B_Cu );
 
                            if( !transient )
                                board->m_IntersectsCourtyardCache.Set( key, hit );
 
                            return hit;
                        } );
 
                if( memoize )
                    board->m_IntersectsCourtyardResultCache.Set( rkey, res );
 
                if( res )
                {
                    return 1.0;
                }
 
                return 0.0;
            } );
}
 
 
static void intersectsFrontCourtyardFunc( LIBEVAL::CONTEXT* aCtx, void* self )
{
    PCBEXPR_CONTEXT* context = static_cast<PCBEXPR_CONTEXT*>( aCtx );
    LIBEVAL::VALUE*  arg = context->Pop();
    LIBEVAL::VALUE*  result = context->AllocValue();
 
    result->Set( 0.0 );
    context->Push( result );
 
    if( !arg || arg->AsString().IsEmpty() )
    {
        if( context->HasErrorCallback() )
            context->ReportError( MISSING_FP_ARG( wxT( "intersectsFrontCourtyard()" ) ) );
 
        return;
    }
 
    PCBEXPR_VAR_REF* vref = static_cast<PCBEXPR_VAR_REF*>( self );
    BOARD_ITEM*      item = vref ? vref->GetObject( context ) : nullptr;
 
    if( !item )
        return;
 
    result->SetDeferredEval(
            [item, arg, context]() -> double
            {
                BOARD*         board = item->GetBoard();
                bool           transient = ( item->GetFlags() & ROUTER_TRANSIENT ) != 0;
                const wxString selector = arg->AsString();
 
                // See intersectsCourtyard: "A"/"B" are pair-relative and not memoizable here.
                bool memoize = !transient && selector != wxT( "A" ) && selector != wxT( "B" );
 
                ITEM_SELECTOR_LAYER_CACHE_KEY rkey{ item, selector, context->GetLayer(),
                                                    context->GetConstraint() };
                bool whole = false;
 
                if( memoize && board->m_IntersectsFCourtyardResultCache.Get( rkey, whole ) )
                    return whole ? 1.0 : 0.0;
 
                std::shared_ptr<SHAPE> itemShape;
 
                bool res = searchFootprintsNearItem( board, selector, context, item,
                        [&]( FOOTPRINT* fp )
                        {
                            PTR_PTR_CACHE_KEY key = { fp, item };
                            bool              cached = false;
 
                            if( !transient && board->m_IntersectsFCourtyardCache.Get( key, cached ) )
                                return cached;
 
                            PCB_LAYER_ID layerId = fp->IsFlipped() ? B_Cu : F_Cu;
 
                            bool hit = collidesWithCourtyard( item, itemShape, context, fp, layerId );
 
                            if( !transient )
                                board->m_IntersectsFCourtyardCache.Set( key, hit );
 
                            return hit;
                        } );
 
                if( memoize )
                    board->m_IntersectsFCourtyardResultCache.Set( rkey, res );
 
                return res ? 1.0 : 0.0;
            } );
}
 
 
static void intersectsBackCourtyardFunc( LIBEVAL::CONTEXT* aCtx, void* self )
{
    PCBEXPR_CONTEXT* context = static_cast<PCBEXPR_CONTEXT*>( aCtx );
    LIBEVAL::VALUE*  arg = context->Pop();
    LIBEVAL::VALUE*  result = context->AllocValue();
 
    result->Set( 0.0 );
    context->Push( result );
 
    if( !arg || arg->AsString().IsEmpty() )
    {
        if( context->HasErrorCallback() )
            context->ReportError( MISSING_FP_ARG( wxT( "intersectsBackCourtyard()" ) ) );
 
        return;
    }
 
    PCBEXPR_VAR_REF* vref = static_cast<PCBEXPR_VAR_REF*>( self );
    BOARD_ITEM*      item = vref ? vref->GetObject( context ) : nullptr;
 
    if( !item )
        return;
 
    result->SetDeferredEval(
            [item, arg, context]() -> double
            {
                BOARD*         board = item->GetBoard();
                bool           transient = ( item->GetFlags() & ROUTER_TRANSIENT ) != 0;
                const wxString selector = arg->AsString();
 
                // See intersectsCourtyard: "A"/"B" are pair-relative and not memoizable here.
                bool memoize = !transient && selector != wxT( "A" ) && selector != wxT( "B" );
 
                ITEM_SELECTOR_LAYER_CACHE_KEY rkey{ item, selector, context->GetLayer(),
                                                    context->GetConstraint() };
                bool whole = false;
 
                if( memoize && board->m_IntersectsBCourtyardResultCache.Get( rkey, whole ) )
                    return whole ? 1.0 : 0.0;
 
                std::shared_ptr<SHAPE> itemShape;
 
                bool res = searchFootprintsNearItem( board, selector, context, item,
                        [&]( FOOTPRINT* fp )
                        {
                            PTR_PTR_CACHE_KEY key = { fp, item };
                            bool              cached = false;
 
                            if( !transient && board->m_IntersectsBCourtyardCache.Get( key, cached ) )
                                return cached;
 
                            PCB_LAYER_ID layerId = fp->IsFlipped() ? F_Cu : B_Cu;
 
                            bool hit = collidesWithCourtyard( item, itemShape, context, fp, layerId );
 
                            if( !transient )
                                board->m_IntersectsBCourtyardCache.Set( key, hit );
 
                            return hit;
                        } );
 
                if( memoize )
                    board->m_IntersectsBCourtyardResultCache.Set( rkey, res );
 
                return res ? 1.0 : 0.0;
            } );
}
 
 
static SHAPE_POLY_SET getDeflatedZoneOutline( BOARD* aBoard, ZONE* aArea )
{
    // Check cache first with read lock
    {
        std::shared_lock<std::shared_mutex> readLock( aBoard->m_CachesMutex );
        auto it = aBoard->m_DeflatedZoneOutlineCache.find( aArea );
 
        if( it != aBoard->m_DeflatedZoneOutlineCache.end() )
            return it->second;
    }
 
    // Cache miss - compute deflated outline
    SHAPE_POLY_SET areaOutline = aArea->GetBoardOutline();
    areaOutline.ClearArcs();
    areaOutline.Deflate( aBoard->GetDesignSettings().GetDRCEpsilon(), CORNER_STRATEGY::ALLOW_ACUTE_CORNERS,
                         ARC_LOW_DEF );
 
    // Store in cache
    {
        std::unique_lock<std::shared_mutex> writeLock( aBoard->m_CachesMutex );
        aBoard->m_DeflatedZoneOutlineCache[aArea] = areaOutline;
    }
 
    return areaOutline;
}
 
 
bool collidesWithArea( BOARD_ITEM* aItem, PCB_LAYER_ID aLayer, PCBEXPR_CONTEXT* aCtx, ZONE* aArea, bool aForKeepout )
{
    BOARD* board = aArea->GetBoard();
    BOX2I  areaBBox = aArea->GetBoundingBox();
 
    // Get cached deflated outline. Collisions include touching, so we need to deflate outline
    // by enough to exclude it. This is particularly important for detecting copper fills as
    // they will be exactly touching along the entire exclusion border.
    SHAPE_POLY_SET areaOutline = getDeflatedZoneOutline( board, aArea );
 
    if( aItem->GetFlags() & HOLE_PROXY )
    {
        if( aItem->Type() == PCB_PAD_T )
        {
            return areaOutline.Collide( aItem->GetEffectiveHoleShape().get() );
        }
        else if( aItem->Type() == PCB_VIA_T )
        {
            LSET overlap = aItem->GetLayerSet() & aArea->GetLayerSet();

            if( overlap.any() )
            {
                if( aCtx->GetLayer() == UNDEFINED_LAYER || overlap.Contains( aCtx->GetLayer() ) )
                    return areaOutline.Collide( aItem->GetEffectiveHoleShape().get() );
            }
        }
 
        return false;
    }
 
    if( aItem->Type() == PCB_FOOTPRINT_T )
    {
        FOOTPRINT* footprint = static_cast<FOOTPRINT*>( aItem );
 
        if( ( footprint->GetFlags() & MALFORMED_COURTYARDS ) != 0 )
        {
            if( aCtx->HasErrorCallback() )
                aCtx->ReportError( _( "Footprint's courtyard is not a single, closed shape." ) );
 
            return false;
        }
 
        if( ( aArea->GetLayerSet() & LSET::FrontMask() ).any() )
        {
            const SHAPE_POLY_SET& courtyard = footprint->GetCourtyard( F_CrtYd );
 
            if( courtyard.OutlineCount() == 0 )
            {
                if( aCtx->HasErrorCallback() )
                    aCtx->ReportError( _( "Footprint has no front courtyard." ) );
            }
            else if( areaOutline.Collide( &courtyard.Outline( 0 ) ) )
            {
                return true;
            }
        }
 
        if( ( aArea->GetLayerSet() & LSET::BackMask() ).any() )
        {
            const SHAPE_POLY_SET& courtyard = footprint->GetCourtyard( B_CrtYd );
 
            if( courtyard.OutlineCount() == 0 )
            {
                if( aCtx->HasErrorCallback() )
                    aCtx->ReportError( _( "Footprint has no back courtyard." ) );
            }
            else if( areaOutline.Collide( &courtyard.Outline( 0 ) ) )
            {
                return true;
            }
        }
 
        return false;
    }
    else if( aItem->Type() == PCB_ZONE_T )
    {
        ZONE* zone = static_cast<ZONE*>( aItem );
 
        if( aForKeepout )
        {
            if( !zone->IsFilled() )
                return false;
 
            if( DRC_RTREE* zoneRTree = board->m_CopperZoneRTreeCache[ zone ].get() )
            {
                if( zoneRTree->QueryColliding( areaBBox, &areaOutline, aLayer ) )
                    return true;
            }
            else
            {
                std::unique_ptr<DRC_RTREE> rtree = std::make_unique<DRC_RTREE>();
                rtree->Insert( zone, aLayer, CLEARANCE_CONSTRAINT );
                rtree->Build();
 
                if( rtree->QueryColliding( areaBBox, &areaOutline, aLayer ) )
                    return true;
            }
 
            return false;
        }
        else
        {
            SHAPE_POLY_SET  zonePolyStorage;
            SHAPE_POLY_SET* zonePoly = &zonePolyStorage;
 
            // GetBoardOutline() is expensive.  Only use it where we have to.
            if( zone->GetParentFootprint() )
                zonePolyStorage = zone->GetBoardOutline();
            else
                zonePoly = zone->Outline();
 
            return areaOutline.Collide( zonePoly );
        }
    }
    else
    {
        if( !aArea->GetLayerSet().Contains( aLayer ) )
            return false;
 
        return areaOutline.Collide( aItem->GetEffectiveShape( aLayer ).get() );
    }
}
 
 
bool searchAreas( BOARD* aBoard, const wxString& aArg, PCBEXPR_CONTEXT* aCtx,
                  const std::function<bool( ZONE* )>& aFunc )
{
    if( aArg == wxT( "A" ) )
    {
        return aFunc( dynamic_cast<ZONE*>( aCtx->GetItem( 0 ) ) );
    }
    else if( aArg == wxT( "B" ) )
    {
        return aFunc( dynamic_cast<ZONE*>( aCtx->GetItem( 1 ) ) );
    }
    else if( KIID::SniffTest( aArg ) )
    {
        KIID target( aArg );
 
        // Use the board's item-by-ID cache for O(1) lookup instead of O(n) iteration.
        // The cache includes both board zones and zones inside footprints.
        const auto& cache = aBoard->GetItemByIdCache();
        auto        it = cache.find( target );
 
        if( it != cache.end() && it->second->Type() == PCB_ZONE_T )
            return aFunc( static_cast<ZONE*>( it->second ) );
 
        return false;
    }
    else  // Match on zone name
    {
        // Use cached zone name lookup to avoid O(n) iteration through all zones for each call.
        // This is a significant performance improvement for boards with many area-based DRC rules.
        std::vector<ZONE*> matchingZones;
        bool               cacheHit = false;
 
        {
            std::shared_lock<std::shared_mutex> readLock( aBoard->m_CachesMutex );
            auto it = aBoard->m_ZonesByNameCache.find( aArg );
 
            if( it != aBoard->m_ZonesByNameCache.end() )
            {
                matchingZones = it->second;
                cacheHit = true;
            }
        }
 
        if( !cacheHit )
        {
            for( ZONE* area : aBoard->Zones() )
            {
                if( area->GetZoneName().Matches( aArg ) )
                    matchingZones.push_back( area );
            }
 
            for( FOOTPRINT* footprint : aBoard->Footprints() )
            {
                for( ZONE* area : footprint->Zones() )
                {
                    if( area->GetZoneName().Matches( aArg ) )
                        matchingZones.push_back( area );
                }
            }
 
            // Store in cache for future lookups
            {
                std::unique_lock<std::shared_mutex> writeLock( aBoard->m_CachesMutex );
                aBoard->m_ZonesByNameCache[aArg] = matchingZones;
            }
        }
 
        for( ZONE* area : matchingZones )
        {
            if( aFunc( area ) )
                return true;
        }
 
        return false;
    }
}
 
 
class SCOPED_LAYERSET
{
public:
    SCOPED_LAYERSET( BOARD_ITEM* aItem )
    {
        m_item = aItem;
        m_layers = aItem->GetLayerSet();
    }
 
    ~SCOPED_LAYERSET()
    {
        m_item->SetLayerSet( m_layers );
    }
 
    void Add( PCB_LAYER_ID aLayer )
    {
        m_item->SetLayerSet( m_item->GetLayerSet().set( aLayer ) );
    }
 
private:
    BOARD_ITEM* m_item;
    LSET        m_layers;
};
 
 
#define MISSING_AREA_ARG( f ) \
    wxString::Format( _( "Missing rule-area argument (A, B, or rule-area name) to %s." ), f )
 
static void doIntersectsAreaFunc( LIBEVAL::CONTEXT* aCtx, void* self, bool aForKeepout )
{
    PCBEXPR_CONTEXT* context = static_cast<PCBEXPR_CONTEXT*>( aCtx );
    LIBEVAL::VALUE*  arg = aCtx->Pop();
    LIBEVAL::VALUE*  result = aCtx->AllocValue();
 
    result->Set( 0.0 );
    aCtx->Push( result );
 
    if( !arg || arg->AsString().IsEmpty() )
    {
        if( aCtx->HasErrorCallback() )
        {
            if( aForKeepout )
                aCtx->ReportError( MISSING_AREA_ARG( wxT( "intersectsKeepout()" ) ) );
            else
                aCtx->ReportError( MISSING_AREA_ARG( wxT( "intersectsArea()" ) ) );
        }
 
        return;
    }
 
    PCBEXPR_VAR_REF* vref = static_cast<PCBEXPR_VAR_REF*>( self );
    BOARD_ITEM*      item = vref ? vref->GetObject( context ) : nullptr;
 
    if( !item )
        return;
 
    result->SetDeferredEval(
            [item, arg, context, aForKeepout]() -> double
            {
                BOARD*         board = item->GetBoard();
                PCB_LAYER_ID   aLayer = context->GetLayer();
                bool           transient = ( item->GetFlags() & ROUTER_TRANSIENT ) != 0;
                const wxString selector = arg->AsString();
 
                auto&          resultsCache = aForKeepout ? board->m_IntersectsKeepoutResultCache
                                                          : board->m_IntersectsAreaResultCache;
 
                auto&          intersectsCache = aForKeepout ? board->m_IntersectsKeepoutCache
                                                             : board->m_IntersectsAreaCache;
 
                // See intersectsCourtyard: "A"/"B" are pair-relative and not memoizable here.
                bool memoize = !transient && selector != wxT( "A" ) && selector != wxT( "B" );
                bool whole = false;
 
                if( memoize && resultsCache.Get( { item, selector, aLayer, context->GetConstraint() }, whole ) )
                    return whole ? 1.0 : 0.0;
 
                BOX2I itemBBox = item->GetBoundingBox();
 
                bool res = searchAreas( board, selector, context,
                        [&]( ZONE* aArea )
                        {
                            if( !aArea || aArea == item || aArea->GetParent() == item )
                                return false;
 
                            SCOPED_LAYERSET scopedLayerSet( aArea );
 
                            if( context->GetConstraint() == SILK_CLEARANCE_CONSTRAINT )
                            {
                                // Silk clearance tests are run across layer pairs
                                if(    ( aArea->IsOnLayer( F_SilkS ) && IsFrontLayer( aLayer ) )
                                    || ( aArea->IsOnLayer( B_SilkS ) && IsBackLayer( aLayer ) ) )
                                {
                                    scopedLayerSet.Add( aLayer );
                                }
                            }
 
                            LSET commonLayers = aArea->GetLayerSet() & item->GetLayerSet();
 
                            if( !commonLayers.any() )
                                return false;
 
                            if( !aArea->GetBoundingBox().Intersects( itemBBox ) )
                                return false;
 
                            LSET testLayers;
 
                            if( aLayer != UNDEFINED_LAYER )
                                testLayers.set( aLayer );
                            else
                                testLayers = commonLayers;
 
                            bool isTransient = ( item->GetFlags() & ROUTER_TRANSIENT ) != 0;
                            std::vector<PCB_LAYER_ID> layersToCompute;
 
                            if( !isTransient )
                            {
                                for( PCB_LAYER_ID layer : testLayers.UIOrder() )
                                {
                                    bool cached = false;
 
                                    if( intersectsCache.Get( { aArea, item, layer }, cached ) )
                                    {
                                        if( cached )
                                            return true;
                                    }
                                    else
                                    {
                                        layersToCompute.push_back( layer );
                                    }
                                }
                            }
                            else
                            {
                                for( PCB_LAYER_ID layer : testLayers.UIOrder() )
                                    layersToCompute.push_back( layer );
                            }
 
                            bool anyCollision = false;
 
                            for( PCB_LAYER_ID layer : layersToCompute )
                            {
                                bool collides = collidesWithArea( item, layer, context, aArea, aForKeepout );
 
                                if( !isTransient )
                                    intersectsCache.Set( { aArea, item, layer }, collides );
 
                                if( collides )
                                    anyCollision = true;
                            }
 
                            return anyCollision;
                        } );
 
                if( memoize )
                    resultsCache.Set( { item, selector, aLayer, context->GetConstraint() }, res );
 
                return res ? 1.0 : 0.0;
            } );
}
 
 
static void intersectsKeepoutFunc( LIBEVAL::CONTEXT* aCtx, void* self )
{
    doIntersectsAreaFunc( aCtx, self, true );
}
 
 
static void intersectsAreaFunc( LIBEVAL::CONTEXT* aCtx, void* self )
{
    doIntersectsAreaFunc( aCtx, self, false );
}
 
 
static void enclosedByAreaFunc( LIBEVAL::CONTEXT* aCtx, void* self )
{
    PCBEXPR_CONTEXT* context = static_cast<PCBEXPR_CONTEXT*>( aCtx );
    LIBEVAL::VALUE*  arg = aCtx->Pop();
    LIBEVAL::VALUE*  result = aCtx->AllocValue();
 
    result->Set( 0.0 );
    aCtx->Push( result );
 
    if( !arg || arg->AsString().IsEmpty() )
    {
        if( aCtx->HasErrorCallback() )
            aCtx->ReportError( MISSING_AREA_ARG( wxT( "enclosedByArea()" ) ) );
 
        return;
    }
 
    PCBEXPR_VAR_REF* vref = static_cast<PCBEXPR_VAR_REF*>( self );
    BOARD_ITEM*      item = vref ? vref->GetObject( context ) : nullptr;
 
    if( !item )
        return;
 
    result->SetDeferredEval(
            [item, arg, context]() -> double
            {
                BOARD*         board = item->GetBoard();
                int            maxError = board->GetDesignSettings().m_MaxError;
                PCB_LAYER_ID   layer = context->GetLayer();
                bool           transient = ( item->GetFlags() & ROUTER_TRANSIENT ) != 0;
                const wxString selector = arg->AsString();
 
                // See intersectsCourtyard: "A"/"B" are pair-relative and not memoizable here.
                bool memoize = !transient && selector != wxT( "A" ) && selector != wxT( "B" );
 
                ITEM_SELECTOR_LAYER_CACHE_KEY rkey{ item, selector, layer, context->GetConstraint() };
                bool whole = false;
 
                if( memoize && board->m_EnclosedByAreaResultCache.Get( rkey, whole ) )
                    return whole ? 1.0 : 0.0;
 
                BOX2I itemBBox = item->GetBoundingBox();
 
                bool res = searchAreas( board, selector, context,
                        [&]( ZONE* aArea )
                        {
                            if( !aArea || aArea == item || aArea->GetParent() == item )
                                return false;
 
                            if( item->Type() != PCB_FOOTPRINT_T )
                            {
                                if( !( aArea->GetLayerSet() & item->GetLayerSet() ).any() )
                                    return false;
                            }
 
                            if( !aArea->GetBoundingBox().Intersects( itemBBox ) )
                                return false;
 
                            PTR_PTR_LAYER_CACHE_KEY key = { aArea, item, layer };
                            bool                    cached = false;
 
                            if( ( item->GetFlags() & ROUTER_TRANSIENT ) == 0
                                && board->m_EnclosedByAreaCache.Get( key, cached ) )
                            {
                                return cached;
                            }
 
                            SHAPE_POLY_SET itemShape;
                            bool           enclosedByArea = false;
 
                            if( item->Type() == PCB_ZONE_T )
                            {
                                itemShape = static_cast<ZONE*>( item )->GetBoardOutline();
                            }
                            else if( item->Type() == PCB_FOOTPRINT_T )
                            {
                                FOOTPRINT* fp = static_cast<FOOTPRINT*>( item );
 
                                for( PCB_LAYER_ID testLayer : aArea->GetLayerSet() )
                                {
                                    fp->TransformPadsToPolySet( itemShape, testLayer, 0, maxError, ERROR_OUTSIDE );
                                    fp->TransformFPShapesToPolySet( itemShape, testLayer, 0, maxError, ERROR_OUTSIDE );
                                }
                            }
                            else
                            {
                                item->TransformShapeToPolygon( itemShape, layer, 0, maxError, ERROR_OUTSIDE );
                            }
 
                            if( itemShape.IsEmpty() )
                            {
                                // If it's already empty then our test will have no meaning.
                                enclosedByArea = false;
                            }
                            else
                            {
                                SHAPE_POLY_SET  areaOutlineStorage;
                                SHAPE_POLY_SET* areaOutline = &areaOutlineStorage;
 
                                // GetBoardOutline() is expensive.  Only use it where we have to.
                                if( aArea->GetParentFootprint() )
                                    areaOutlineStorage = aArea->GetBoardOutline();
                                else
                                    areaOutline = aArea->Outline();
 
                                itemShape.ClearArcs();
                                itemShape.BooleanSubtract( *areaOutline );
 
                                enclosedByArea = itemShape.IsEmpty();
                            }
 
                            if( ( item->GetFlags() & ROUTER_TRANSIENT ) == 0 )
                                board->m_EnclosedByAreaCache.Set( key, enclosedByArea );
 
                            return enclosedByArea;
                        } );
 
                if( memoize )
                    board->m_EnclosedByAreaResultCache.Set( rkey, res );
 
                return res ? 1.0 : 0.0;
            } );
}
 
 
static void memberOfGroupFunc( LIBEVAL::CONTEXT* aCtx, void* self )
{
    LIBEVAL::VALUE* arg = aCtx->Pop();
    LIBEVAL::VALUE* result = aCtx->AllocValue();
 
    result->Set( 0.0 );
    aCtx->Push( result );
 
    if( !arg || arg->AsString().IsEmpty() )
    {
        if( aCtx->HasErrorCallback() )
        {
            aCtx->ReportError( wxString::Format( _( "Missing group name argument to %s." ),
                                                 wxT( "memberOfGroup()" ) ) );
        }
 
        return;
    }
 
    PCBEXPR_VAR_REF* vref = static_cast<PCBEXPR_VAR_REF*>( self );
    BOARD_ITEM*      item = vref ? vref->GetObject( aCtx ) : nullptr;
 
    if( !item )
        return;
 
    result->SetDeferredEval(
            [item, arg]() -> double
            {
                EDA_GROUP* group = item->GetParentGroup();
 
                if( !group && item->GetParent() && item->GetParent()->Type() == PCB_FOOTPRINT_T )
                    group = item->GetParent()->GetParentGroup();
 
                while( group )
                {
                    if( group->GetName().Matches( arg->AsString() ) )
                        return 1.0;
 
                    group = group->AsEdaItem()->GetParentGroup();
                }
 
                return 0.0;
            } );
}
 
 
#define MISSING_SHEET_ARG( f ) \
    wxString::Format( _( "Missing sheet name argument to %s." ), f )
 
static void memberOfSheetFunc( LIBEVAL::CONTEXT* aCtx, void* self )
{
    LIBEVAL::VALUE* arg = aCtx->Pop();
    LIBEVAL::VALUE* result = aCtx->AllocValue();
 
    result->Set( 0.0 );
    aCtx->Push( result );
 
    if( !arg || arg->AsString().IsEmpty() )
    {
        if( aCtx->HasErrorCallback() )
            aCtx->ReportError( MISSING_SHEET_ARG( wxT( "memberOfSheet()" ) ) );
 
        return;
    }
 
    PCBEXPR_VAR_REF* vref = static_cast<PCBEXPR_VAR_REF*>( self );
    BOARD_ITEM*      item = vref ? vref->GetObject( aCtx ) : nullptr;
 
    if( !item )
        return;
 
    result->SetDeferredEval(
            [item, arg]() -> double
            {
                FOOTPRINT* fp = item->GetParentFootprint();
 
                if( !fp && item->Type() == PCB_FOOTPRINT_T )
                    fp = static_cast<FOOTPRINT*>( item );
 
                if( !fp )
                    return 0.0;
 
                wxString sheetName = fp->GetSheetname();
                wxString refName = arg->AsString();
 
                if( sheetName.EndsWith( wxT( "/" ) ) )
                    sheetName.RemoveLast();
                if( refName.EndsWith( wxT( "/" ) ) )
                    refName.RemoveLast();
 
                if( sheetName.Matches( refName ) )
                    return 1.0;
 
                if( ( refName.Matches( wxT( "/" ) ) || refName.IsEmpty() )
                    && sheetName.IsEmpty() )
                {
                    return 1.0;
                }
 
                return 0.0;
            } );
}
 
 
static void memberOfSheetOrChildrenFunc( LIBEVAL::CONTEXT* aCtx, void* self )
{
    LIBEVAL::VALUE* arg = aCtx->Pop();
    LIBEVAL::VALUE* result = aCtx->AllocValue();
 
    result->Set( 0.0 );
    aCtx->Push( result );
 
    if( !arg || arg->AsString().IsEmpty() )
    {
        if( aCtx->HasErrorCallback() )
            aCtx->ReportError( MISSING_SHEET_ARG( wxT( "memberOfSheetOrChildren()" ) ) );
 
        return;
    }
 
    PCBEXPR_VAR_REF* vref = static_cast<PCBEXPR_VAR_REF*>( self );
    BOARD_ITEM*      item = vref ? vref->GetObject( aCtx ) : nullptr;
 
    if( !item )
        return;
 
    result->SetDeferredEval(
            [item, arg]() -> double
            {
                FOOTPRINT* fp = item->GetParentFootprint();
 
                if( !fp && item->Type() == PCB_FOOTPRINT_T )
                    fp = static_cast<FOOTPRINT*>( item );
 
                if( !fp )
                    return 0.0;
 
                wxString sheetName = fp->GetSheetname();
                wxString refName = arg->AsString();
 
                if( sheetName.EndsWith( wxT( "/" ) ) )
                    sheetName.RemoveLast();
                if( refName.EndsWith( wxT( "/" ) ) )
                    refName.RemoveLast();
 
                wxArrayString sheetPath = wxSplit( sheetName, '/' );
                wxArrayString refPath = wxSplit( refName, '/' );
 
                if( refPath.size() > sheetPath.size() )
                    return 0.0;
 
                if( ( refName.Matches( wxT( "/" ) ) || refName.IsEmpty() )
                        && sheetName.IsEmpty() )
                {
                    return 1.0;
                }
 
                for( size_t i = 0; i < refPath.size(); i++ )
                {
                    if( !sheetPath[i].Matches( refPath[i] ) )
                        return 0.0;
                }
 
                return 1.0;
            } );
}
 
 
static void memberOfFootprintFunc( LIBEVAL::CONTEXT* aCtx, void* self )
{
    LIBEVAL::VALUE* arg = aCtx->Pop();
    LIBEVAL::VALUE* result = aCtx->AllocValue();
 
    result->Set( 0.0 );
    aCtx->Push( result );
 
    if( !arg || arg->AsString().IsEmpty() )
    {
        if( aCtx->HasErrorCallback() )
        {
            aCtx->ReportError( wxString::Format( _( "Missing footprint argument (reference designator) to %s." ),
                                                 wxT( "memberOfFootprint()" ) ) );
        }
 
        return;
    }
 
    PCBEXPR_VAR_REF* vref = static_cast<PCBEXPR_VAR_REF*>( self );
    BOARD_ITEM*      item = vref ? vref->GetObject( aCtx ) : nullptr;
 
    if( !item )
        return;
 
    result->SetDeferredEval(
            [item, arg]() -> double
            {
                if( FOOTPRINT* parentFP = item->GetParentFootprint() )
                {
                    if( testFootprintSelector( parentFP, arg->AsString() ) )
                        return 1.0;
                }
 
                return 0.0;
            } );
}
 
 
static void isMicroVia( LIBEVAL::CONTEXT* aCtx, void* self )
{
    PCBEXPR_VAR_REF* vref = static_cast<PCBEXPR_VAR_REF*>( self );
    BOARD_ITEM*      item = vref ? vref->GetObject( aCtx ) : nullptr;
    LIBEVAL::VALUE*  result = aCtx->AllocValue();
 
    result->Set( 0.0 );
    aCtx->Push( result );
 
    if( item && item->Type() == PCB_VIA_T && static_cast<PCB_VIA*>( item )->IsMicroVia() )
        result->Set( 1.0 );
}
 
static void isBlindVia( LIBEVAL::CONTEXT* aCtx, void* self )
{
    PCBEXPR_VAR_REF* vref = static_cast<PCBEXPR_VAR_REF*>( self );
    BOARD_ITEM*      item = vref ? vref->GetObject( aCtx ) : nullptr;
    LIBEVAL::VALUE*  result = aCtx->AllocValue();
 
    result->Set( 0.0 );
    aCtx->Push( result );
 
    if( item && item->Type() == PCB_VIA_T && static_cast<PCB_VIA*>( item )->IsBlindVia() )
        result->Set( 1.0 );
}
 
static void isBuriedVia( LIBEVAL::CONTEXT* aCtx, void* self )
{
    PCBEXPR_VAR_REF* vref = static_cast<PCBEXPR_VAR_REF*>( self );
    BOARD_ITEM*      item = vref ? vref->GetObject( aCtx ) : nullptr;
    LIBEVAL::VALUE*  result = aCtx->AllocValue();
 
    result->Set( 0.0 );
    aCtx->Push( result );
 
    if( item && item->Type() == PCB_VIA_T && static_cast<PCB_VIA*>( item )->IsBuriedVia() )
        result->Set( 1.0 );
}
 
static void isStackedViaFunc( LIBEVAL::CONTEXT* aCtx, void* self )
{
    PCBEXPR_VAR_REF* vref = static_cast<PCBEXPR_VAR_REF*>( self );
    BOARD_ITEM*      item = vref ? vref->GetObject( aCtx ) : nullptr;
    LIBEVAL::VALUE*  result = aCtx->AllocValue();
 
    result->Set( 0.0 );
    aCtx->Push( result );
 
    if( !item || item->Type() != PCB_VIA_T )
        return;
 
    PCB_VIA* via = static_cast<PCB_VIA*>( item );
    BOARD*   board = via->GetBoard();
 
    if( !board || via->GetViaType() != VIATYPE::MICROVIA )
        return;
 
    {
        std::shared_lock<std::shared_mutex> readLock( board->m_CachesMutex );
 
        if( board->m_StackedMicroviaCache.has_value() )
        {
            if( board->m_StackedMicroviaCache->count( via ) )
                result->Set( 1.0 );
 
            return;
        }
    }
 
    std::set<const PCB_VIA*> stacked;
 
    for( const std::vector<PCB_VIA*>& column : PCB_VIA::CollectMicroviaColumns( board ) )
        stacked.insert( column.begin(), column.end() );
 
    {
        std::unique_lock<std::shared_mutex> writeLock( board->m_CachesMutex );
        board->m_StackedMicroviaCache = stacked;
    }
 
    if( stacked.count( via ) )
        result->Set( 1.0 );
}
 
static void isBlindBuriedViaFunc( LIBEVAL::CONTEXT* aCtx, void* self )
{
    PCBEXPR_VAR_REF* vref = static_cast<PCBEXPR_VAR_REF*>( self );
    BOARD_ITEM*      item = vref ? vref->GetObject( aCtx ) : nullptr;
    LIBEVAL::VALUE*  result = aCtx->AllocValue();
 
    result->Set( 0.0 );
    aCtx->Push( result );
 
    if( item && item->Type() == PCB_VIA_T )
    {
        PCB_VIA* via = static_cast<PCB_VIA*>( item );
 
        if( via->IsBlindVia() || via->IsBuriedVia() )
            result->Set( 1.0 );
    }
}
 
 
static void isCoupledDiffPairFunc( LIBEVAL::CONTEXT* aCtx, void* self )
{
    PCBEXPR_CONTEXT*      context = static_cast<PCBEXPR_CONTEXT*>( aCtx );
    BOARD_CONNECTED_ITEM* a = dynamic_cast<BOARD_CONNECTED_ITEM*>( context->GetItem( 0 ) );
    BOARD_CONNECTED_ITEM* b = dynamic_cast<BOARD_CONNECTED_ITEM*>( context->GetItem( 1 ) );
    LIBEVAL::VALUE*       result = aCtx->AllocValue();
 
    result->Set( 0.0 );
    aCtx->Push( result );
 
    result->SetDeferredEval(
            [a, b, context]() -> double
            {
                NETINFO_ITEM* netinfo = a ? a->GetNet() : nullptr;
 
                if( !netinfo )
                    return 0.0;
 
                wxString coupledNet;
                wxString dummy;
 
                if( !DRC_ENGINE::MatchDpSuffix( netinfo->GetNetname(), coupledNet, dummy ) )
                    return 0.0;
 
                if( context->GetConstraint() == DRC_CONSTRAINT_T::DIFF_PAIR_GAP_CONSTRAINT
                        || context->GetConstraint() == DRC_CONSTRAINT_T::LENGTH_CONSTRAINT
                        || context->GetConstraint() == DRC_CONSTRAINT_T::NET_CHAIN_LENGTH_CONSTRAINT
                        || context->GetConstraint() == DRC_CONSTRAINT_T::SKEW_CONSTRAINT )
                {
                    // DRC engine evaluates these only in the context of a diffpair, but doesn't
                    // always supply the second (B) item.
                    if( BOARD* board = a->GetBoard() )
                    {
                        if( board->FindNet( coupledNet ) )
                            return 1.0;
                    }
                }
 
                if( b && b->GetNetname() == coupledNet )
                    return 1.0;
 
                return 0.0;
            } );
}
 
 
static void inDiffPairFunc( LIBEVAL::CONTEXT* aCtx, void* self )
{
    LIBEVAL::VALUE*  argv   = aCtx->Pop();
    PCBEXPR_VAR_REF* vref   = static_cast<PCBEXPR_VAR_REF*>( self );
    BOARD_ITEM*      item   = vref ? vref->GetObject( aCtx ) : nullptr;
    LIBEVAL::VALUE*  result = aCtx->AllocValue();
 
    result->Set( 0.0 );
    aCtx->Push( result );
 
    if( !argv || argv->AsString().IsEmpty() )
    {
        if( aCtx->HasErrorCallback() )
        {
            aCtx->ReportError( wxString::Format( _( "Missing diff-pair name argument to %s." ),
                                                 wxT( "inDiffPair()" ) ) );
        }
 
        return;
    }
 
    if( !item || !item->GetBoard() )
        return;
 
    result->SetDeferredEval(
            [item, argv]() -> double
            {
                if( item && item->IsConnected() )
                {
                    NETINFO_ITEM* netinfo = static_cast<BOARD_CONNECTED_ITEM*>( item )->GetNet();
 
                    if( !netinfo )
                        return 0.0;
 
                    wxString refName = netinfo->GetNetname();
                    wxString arg = argv->AsString();
                    wxString baseName, coupledNet;
                    int      polarity = DRC_ENGINE::MatchDpSuffix( refName, coupledNet, baseName );
 
                    if( polarity != 0 && item->GetBoard()->FindNet( coupledNet ) )
                    {
                        if( baseName.Matches( arg ) )
                            return 1.0;
 
                        if( baseName.EndsWith( "_" ) && baseName.BeforeLast( '_' ).Matches( arg ) )
                            return 1.0;
                    }
                }
 
                return 0.0;
            } );
}
 
 
static void inNetChainFunc( LIBEVAL::CONTEXT* aCtx, void* self )
{
    LIBEVAL::VALUE*  argv   = aCtx->Pop();
    PCBEXPR_VAR_REF* vref   = static_cast<PCBEXPR_VAR_REF*>( self );
    BOARD_ITEM*      item   = vref ? vref->GetObject( aCtx ) : nullptr;
    LIBEVAL::VALUE*  result = aCtx->AllocValue();
 
    result->Set( 0.0 );
    aCtx->Push( result );
 
    if( !argv || argv->AsString().IsEmpty() )
    {
        if( aCtx->HasErrorCallback() )
        {
            aCtx->ReportError( wxString::Format( _( "Missing net-chain name argument to %s" ),
                                                 wxT( "inNetChain()" ) ) );
        }
 
        return;
    }
 
    if( !item || !item->GetBoard() )
        return;
 
    result->SetDeferredEval(
            [item, argv]() -> double
            {
                if( !item || !item->IsConnected() )
                    return 0.0;
 
                NETINFO_ITEM* netinfo = static_cast<BOARD_CONNECTED_ITEM*>( item )->GetNet();
 
                if( !netinfo )
                    return 0.0;
 
                const wxString& chainName = netinfo->GetNetChain();
 
                if( chainName.IsEmpty() )
                    return 0.0;
 
                wxString arg = argv->AsString();
 
                return chainName.Matches( arg ) ? 1.0 : 0.0;
            } );
}
 
 
static void hasNetChainFunc( LIBEVAL::CONTEXT* aCtx, void* self )
{
    PCBEXPR_VAR_REF* vref   = static_cast<PCBEXPR_VAR_REF*>( self );
    BOARD_ITEM*      item   = vref ? vref->GetObject( aCtx ) : nullptr;
    LIBEVAL::VALUE*  result = aCtx->AllocValue();
 
    result->Set( 0.0 );
    aCtx->Push( result );
 
    if( !item || !item->GetBoard() )
        return;
 
    result->SetDeferredEval(
            [item]() -> double
            {
                if( !item || !item->IsConnected() )
                    return 0.0;
 
                NETINFO_ITEM* netinfo = static_cast<BOARD_CONNECTED_ITEM*>( item )->GetNet();
 
                return ( netinfo && !netinfo->GetNetChain().IsEmpty() ) ? 1.0 : 0.0;
            } );
}
 
 
static void inNetChainClassFunc( LIBEVAL::CONTEXT* aCtx, void* self )
{
    LIBEVAL::VALUE*  argv   = aCtx->Pop();
    PCBEXPR_VAR_REF* vref   = static_cast<PCBEXPR_VAR_REF*>( self );
    BOARD_ITEM*      item   = vref ? vref->GetObject( aCtx ) : nullptr;
    LIBEVAL::VALUE*  result = aCtx->AllocValue();
 
    result->Set( 0.0 );
    aCtx->Push( result );
 
    if( !argv || argv->AsString().IsEmpty() )
    {
        if( aCtx->HasErrorCallback() )
        {
            aCtx->ReportError( wxString::Format( _( "Missing netclass name argument to %s" ),
                                                 wxT( "inNetChainClass()" ) ) );
        }
 
        return;
    }
 
    if( !item || !item->GetBoard() )
        return;
 
    result->SetDeferredEval(
            [item, argv]() -> double
            {
                if( !item || !item->IsConnected() )
                    return 0.0;
 
                NETINFO_ITEM* netinfo = static_cast<BOARD_CONNECTED_ITEM*>( item )->GetNet();
 
                if( !netinfo )
                    return 0.0;
 
                const wxString& chainName = netinfo->GetNetChain();
 
                if( chainName.IsEmpty() )
                    return 0.0;
 
                if( BOARD* board = item->GetBoard() )
                {
                    std::shared_ptr<NET_SETTINGS> ns = board->GetDesignSettings().m_NetSettings;
 
                    if( ns )
                    {
                        const wxString& className = ns->GetNetChainClass( chainName );
 
                        if( className.IsEmpty() )
                            return 0.0;
 
                        wxString arg = argv->AsString();
 
                        return className.Matches( arg ) ? 1.0 : 0.0;
                    }
                }
 
                return 0.0;
            } );
}
 
 
static void getFieldFunc( LIBEVAL::CONTEXT* aCtx, void* self )
{
    LIBEVAL::VALUE*  arg    = aCtx->Pop();
    PCBEXPR_VAR_REF* vref   = static_cast<PCBEXPR_VAR_REF*>( self );
    BOARD_ITEM*      item   = vref ? vref->GetObject( aCtx ) : nullptr;
    LIBEVAL::VALUE*  result = aCtx->AllocValue();
 
    result->Set( "" );
    aCtx->Push( result );
 
    if( !arg || arg->AsString().IsEmpty() )
    {
        if( aCtx->HasErrorCallback() )
        {
            aCtx->ReportError( wxString::Format( _( "Missing field name argument to %s." ),
                                                 wxT( "getField()" ) ) );
        }
 
        return;
    }
 
    if( !item || !item->GetBoard() )
        return;
 
    result->SetDeferredEval(
            [item, arg]() -> wxString
            {
                if( item && item->Type() == PCB_FOOTPRINT_T )
                {
                    FOOTPRINT*      fp = static_cast<FOOTPRINT*>( item );
                    BOARD*          board = fp->GetBoard();
                    const wxString& fieldName = arg->AsString();
 
                    // getField only depends on the item, so memoize the resolved text per
                    // (item, field) to avoid the linear field-name search on every repeat.
                    ITEM_FIELD_CACHE_KEY key{ item, std::hash<wxString>{}( fieldName ) };
                    wxString             cached;
 
                    if( board && board->m_ItemFieldCache.Get( key, cached ) )
                        return cached;
 
                    PCB_FIELD* field = fp->GetField( fieldName );
                    wxString   text = field ? field->GetText() : wxString();
 
                    if( board )
                        board->m_ItemFieldCache.Set( key, text );
 
                    return text;
                }
 
                return "";
            } );
}
 
 
static void hasNetclassFunc( LIBEVAL::CONTEXT* aCtx, void* self )
{
    LIBEVAL::VALUE* arg = aCtx->Pop();
    LIBEVAL::VALUE* result = aCtx->AllocValue();
 
    result->Set( 0.0 );
    aCtx->Push( result );
 
    if( !arg || arg->AsString().IsEmpty() )
    {
        if( aCtx->HasErrorCallback() )
        {
            aCtx->ReportError( wxString::Format( _( "Missing netclass name argument to %s." ),
                                                 wxT( "hasNetclass()" ) ) );
        }
 
        return;
    }
 
    PCBEXPR_VAR_REF* vref = static_cast<PCBEXPR_VAR_REF*>( self );
    BOARD_ITEM*      item = vref ? vref->GetObject( aCtx ) : nullptr;
 
    if( !item )
        return;
 
    result->SetDeferredEval(
            [item, arg]() -> double
            {
                if( !item->IsConnected() )
                    return 0.0;
 
                BOARD_CONNECTED_ITEM* bcItem = static_cast<BOARD_CONNECTED_ITEM*>( item );
                NETCLASS*             netclass = bcItem->GetEffectiveNetClass();
 
                if( netclass && netclass->ContainsNetclassWithName( arg->AsString() ) )
                    return 1.0;
 
                return 0.0;
            } );
}
 
 
static void hasExactNetclassFunc( LIBEVAL::CONTEXT* aCtx, void* self )
{
    LIBEVAL::VALUE* arg = aCtx->Pop();
    LIBEVAL::VALUE* result = aCtx->AllocValue();
 
    result->Set( 0.0 );
    aCtx->Push( result );
 
    if( !arg || arg->AsString().IsEmpty() )
    {
        if( aCtx->HasErrorCallback() )
        {
            aCtx->ReportError( wxString::Format( _( "Missing netclass name argument to %s." ),
                                                 wxT( "hasExactNetclass()" ) ) );
        }
 
        return;
    }
 
    PCBEXPR_VAR_REF* vref = static_cast<PCBEXPR_VAR_REF*>( self );
    BOARD_ITEM*      item = vref ? vref->GetObject( aCtx ) : nullptr;
 
    if( !item )
        return;
 
    result->SetDeferredEval(
            [item, arg]() -> double
            {
                if( !item->IsConnected() )
                    return 0.0;
 
                BOARD_CONNECTED_ITEM* bcItem = static_cast<BOARD_CONNECTED_ITEM*>( item );
                BOARD*                board = bcItem->GetBoard();
                wxString              netclassName;
 
                if( board && ( item->GetFlags() & ROUTER_TRANSIENT ) == 0 )
                {
                    std::shared_lock<std::shared_mutex> readLock( board->m_CachesMutex );
 
                    auto it = board->m_ItemNetclassCache.find( item );
 
                    if( it != board->m_ItemNetclassCache.end() )
                        netclassName = it->second;
                }
 
                if( netclassName.empty() )
                {
                    NETCLASS* netclass = bcItem->GetEffectiveNetClass();
 
                    if( netclass )
                        netclassName = netclass->GetName();
 
                    if( board && !netclassName.empty() && ( item->GetFlags() & ROUTER_TRANSIENT ) == 0 )
                    {
                        std::unique_lock<std::shared_mutex> writeLock( board->m_CachesMutex );
                        board->m_ItemNetclassCache[item] = netclassName;
                    }
                }
 
                return ( netclassName == arg->AsString() ) ? 1.0 : 0.0;
            } );
}
 
 
static void hasComponentClassFunc( LIBEVAL::CONTEXT* aCtx, void* self )
{
    LIBEVAL::VALUE* arg = aCtx->Pop();
    LIBEVAL::VALUE* result = aCtx->AllocValue();
 
    result->Set( 0.0 );
    aCtx->Push( result );
 
    if( !arg || arg->AsString().IsEmpty() )
    {
        if( aCtx->HasErrorCallback() )
        {
            aCtx->ReportError( wxString::Format( _( "Missing component class name argument to %s." ),
                                                 wxT( "hasComponentClass()" ) ) );
        }
 
        return;
    }
 
    PCBEXPR_VAR_REF* vref = static_cast<PCBEXPR_VAR_REF*>( self );
    BOARD_ITEM*      item = vref ? vref->GetObject( aCtx ) : nullptr;
 
    if( !item )
        return;
 
    result->SetDeferredEval(
            [item, arg]() -> double
            {
                FOOTPRINT* footprint = nullptr;
 
                if( item->Type() == PCB_FOOTPRINT_T )
                    footprint = static_cast<FOOTPRINT*>( item );
                else
                    footprint = item->GetParentFootprint();
 
                if( !footprint )
                    return 0.0;
 
                const COMPONENT_CLASS* compClass = footprint->GetComponentClass();
 
                if( compClass && compClass->ContainsClassName( arg->AsString() ) )
                    return 1.0;
 
                return 0.0;
            } );
}
 
 
static void customPropertyFunc( LIBEVAL::CONTEXT* aCtx, void* self )
{
    LIBEVAL::VALUE*  arg    = aCtx->Pop();
    PCBEXPR_VAR_REF* vref   = static_cast<PCBEXPR_VAR_REF*>( self );
    BOARD_ITEM*      item   = vref ? vref->GetObject( aCtx ) : nullptr;
    LIBEVAL::VALUE*  result = aCtx->AllocValue();
 
    result->Set( "" );
    aCtx->Push( result );
 
    if( !arg )
    {
        if( aCtx->HasErrorCallback() )
        {
            aCtx->ReportError( wxString::Format( _( "Missing property name argument to %s." ),
                                                 wxT( "customProperty()" ) ) );
        }
 
        return;
    }
 
    if( !item )
        return;
 
    result->SetDeferredEval(
            [item, arg]() -> wxString
            {
                const wxString key = arg->AsString();
                wxString       value;
 
                if( item && item->GetCustomProperty( key, value ) )
                    return value;
 
                if( FOOTPRINT* parentFp = item ? item->GetParentFootprint() : nullptr )
                {
                    if( parentFp->GetCustomProperty( key, value ) )
                        return value;
                }
 
                return wxString();
            } );
}
 
 
static void hasCustomPropertyFunc( LIBEVAL::CONTEXT* aCtx, void* self )
{
    LIBEVAL::VALUE*  arg    = aCtx->Pop();
    PCBEXPR_VAR_REF* vref   = static_cast<PCBEXPR_VAR_REF*>( self );
    BOARD_ITEM*      item   = vref ? vref->GetObject( aCtx ) : nullptr;
    LIBEVAL::VALUE*  result = aCtx->AllocValue();
 
    result->Set( 0.0 );
    aCtx->Push( result );
 
    if( !arg )
    {
        if( aCtx->HasErrorCallback() )
        {
            aCtx->ReportError( wxString::Format( _( "Missing property name argument to %s." ),
                                                 wxT( "hasCustomProperty()" ) ) );
        }
 
        return;
    }
 
    if( !item )
        return;
 
    result->SetDeferredEval(
            [item, arg]() -> double
            {
                const wxString key = arg->AsString();
                wxString       value;
 
                if( item && item->GetCustomProperty( key, value ) )
                    return 1.0;
 
                if( FOOTPRINT* parentFp = item ? item->GetParentFootprint() : nullptr )
                {
                    if( parentFp->GetCustomProperty( key, value ) )
                        return 1.0;
                }
 
                return 0.0;
            } );
}
 
 
PCBEXPR_BUILTIN_FUNCTIONS::PCBEXPR_BUILTIN_FUNCTIONS()
{
    RegisterAllFunctions();
}
 
 
void PCBEXPR_BUILTIN_FUNCTIONS::RegisterAllFunctions()
{
    m_funcs.clear();
 
    RegisterFunc( wxT( "existsOnLayer('x')" ), existsOnLayerFunc );
 
    RegisterFunc( wxT( "isPlated()" ), isPlatedFunc );
 
    // Geometry-dependent functions depend on item position/shape rather than item properties.
    // The third argument marks them so that CreateFuncCall() can detect them automatically.
    RegisterFunc( wxT( "insideCourtyard('x') DEPRECATED" ), intersectsCourtyardFunc, true );
    RegisterFunc( wxT( "insideFrontCourtyard('x') DEPRECATED" ), intersectsFrontCourtyardFunc, true );
    RegisterFunc( wxT( "insideBackCourtyard('x') DEPRECATED" ), intersectsBackCourtyardFunc, true );
    RegisterFunc( wxT( "intersectsCourtyard('x')" ), intersectsCourtyardFunc, true );
    RegisterFunc( wxT( "intersectsFrontCourtyard('x')" ), intersectsFrontCourtyardFunc, true );
    RegisterFunc( wxT( "intersectsBackCourtyard('x')" ), intersectsBackCourtyardFunc, true );
 
    RegisterFunc( wxT( "insideArea('x') DEPRECATED" ), intersectsKeepoutFunc, true );
    RegisterFunc( wxT( "intersectsArea('x')" ), intersectsAreaFunc, true );
    RegisterFunc( wxT( "intersectsKeepout('x')" ), intersectsKeepoutFunc, true );
    RegisterFunc( wxT( "enclosedByArea('x')" ), enclosedByAreaFunc, true );
 
    RegisterFunc( wxT( "isMicroVia()" ), isMicroVia );
    RegisterFunc( wxT( "isBlindVia()" ), isBlindVia );
    RegisterFunc( wxT( "isBuriedVia()" ), isBuriedVia );
    RegisterFunc( wxT( "isBlindBuriedVia()" ), isBlindBuriedViaFunc );
    RegisterFunc( wxT( "isStackedVia()" ), isStackedViaFunc );
 
    RegisterFunc( wxT( "memberOf('x') DEPRECATED" ), memberOfGroupFunc );
    RegisterFunc( wxT( "memberOfGroup('x')" ), memberOfGroupFunc );
    RegisterFunc( wxT( "memberOfFootprint('x')" ), memberOfFootprintFunc );
    RegisterFunc( wxT( "memberOfSheet('x')" ), memberOfSheetFunc );
    RegisterFunc( wxT( "memberOfSheetOrChildren('x')" ), memberOfSheetOrChildrenFunc );
 
    RegisterFunc( wxT( "fromTo('x','y')" ), fromToFunc );
    RegisterFunc( wxT( "isCoupledDiffPair()" ), isCoupledDiffPairFunc );
    RegisterFunc( wxT( "inDiffPair('x')" ), inDiffPairFunc );
    RegisterFunc( wxT( "inNetChain('x')" ), inNetChainFunc );
    RegisterFunc( wxT( "hasNetChain()" ), hasNetChainFunc );
    RegisterFunc( wxT( "inNetChainClass('x')" ), inNetChainClassFunc );
 
    RegisterFunc( wxT( "getField('x')" ), getFieldFunc );
 
    RegisterFunc( wxT( "hasNetclass('x')" ), hasNetclassFunc );
    RegisterFunc( wxT( "hasExactNetclass('x')" ), hasExactNetclassFunc );
    RegisterFunc( wxT( "hasComponentClass('x')" ), hasComponentClassFunc );
 
    RegisterFunc( wxT( "customProperty('x')" ), customPropertyFunc );
    RegisterFunc( wxT( "hasCustomProperty('x')" ), hasCustomPropertyFunc );
}