kicad_diff_types.h

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 3
 * of the License, or (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, you may find one here:
 * http://www.gnu.org/licenses/gpl-3.0.html
 */
 
#ifndef KICAD_DIFF_TYPES_H
#define KICAD_DIFF_TYPES_H
 
#include <kicommon.h>
#include <kiid.h>
#include <math/box2.h>
#include <math/vector2d.h>
#include <gal/color4d.h>
#include <layer_ids.h>
 
#include <json_common.h>
#include <wx/string.h>
 
#include <cstdint>
#include <functional>
#include <map>
#include <optional>
#include <string>
#include <variant>
#include <vector>
 
 
enum class EDA_UNITS;
struct EDA_IU_SCALE;
 
 
namespace KICAD_DIFF
{

enum class DISPLAY_HINT
{
    NONE,
    DISTANCE,   
    COORD,      
    ANGLE       
};

enum class CHANGE_KIND
{
    ADDED,
    REMOVED,
    MODIFIED,
    COLLISION,       // independent add of same KIID on both sides
    DUPLICATE_UUID   // same KIID appears twice in one document
};
 

inline const wxString DOC_PROP_PAGE_FORMAT      = wxS( "Page Format" );
inline const wxString DOC_PROP_PAGE_ORIENTATION = wxS( "Page Orientation" );
inline const wxString DOC_PROP_BOARD_THICKNESS  = wxS( "Board Thickness" );
inline const wxString DOC_PROP_LAYER_STACKUP    = wxS( "Layer Stackup" );
inline const wxString DOC_PROP_DRC_SEVERITIES   = wxS( "DRC Severity Overrides" );
inline const wxString DOC_PROP_ERC_SEVERITIES   = wxS( "ERC Severity Overrides" );
inline const wxString DOC_PROP_DRAWING_SHEET    = wxS( "Drawing Sheet File" );
inline const wxString DOC_PROP_NET_CLASSES      = wxS( "Net Classes" );
inline const wxString DOC_PROP_CUSTOM_RULES     = wxS( "Custom DRC Rules" );
inline const wxString DOC_PROP_FP_LIB_TABLE     = wxS( "Footprint Library Table" );
inline const wxString DOC_PROP_SYM_LIB_TABLE    = wxS( "Symbol Library Table" );
inline const wxString DOC_PROP_EMBED_FONTS      = wxS( "Embed Fonts" );

inline const wxString DOC_PROP_EMBEDDED_FILE    = wxS( "Embedded File: " );

inline const wxString DOC_PROP_TITLE = wxS( "Title" );
inline const wxString DOC_PROP_DATE = wxS( "Date" );
inline const wxString DOC_PROP_REVISION = wxS( "Revision" );
inline const wxString DOC_PROP_COMPANY = wxS( "Company" );

inline const wxString DOC_PROP_PLOT_OPTIONS = wxS( "Plot Options" );
inline const wxString DOC_PROP_LEGACY_TEARDROPS = wxS( "Legacy Teardrops" );

inline const wxString DOC_PROP_BOARD_PROPERTY = wxS( "Board Property: " );
inline const wxString DOC_PROP_VARIANT = wxS( "Variant: " );

inline constexpr int DOC_TITLE_BLOCK_COMMENTS = 9;
 
inline wxString DocPropComment( int aIndex )
{
    return wxString::Format( wxS( "Comment %d" ), aIndex + 1 );
}
 

inline const KIID& SchScreenSentinelKiid()
{
    static const KIID sentinel{ std::string( "5c50ee00-0000-4000-8000-000000000000" ) };
    return sentinel;
}
 

inline KIID_PATH LibraryItemKiidPath( const wxString& aName )
{
    KIID_PATH path;
    path.emplace_back( KIID::FromDeterministicString( aName ) );
 
    return path;
}
 

template<typename SeverityMap>
inline std::string SummarizeSeverities( const SeverityMap& aMap )
{
    std::size_t h = 0;
 
    for( const auto& [code, sev] : aMap )
        h ^= std::hash<int>{}( code ) + std::hash<int>{}( static_cast<int>( sev ) );
 
    return wxString::Format( wxS( "%zu override(s) (hash %zx)" ),
                             aMap.size(), h ).ToStdString();
}
 

class KICOMMON_API DIFF_VALUE
{
public:
    enum class T
    {
        NONE,
        BOOL,
        INT,
        INT64,
        DOUBLE,
        STRING,
        KIID,
        VECTOR2I,
        BOX2I,
        COLOR,
        LAYER,
        ENUM,
        POLYGON_SET
    };

    using EnumValue = std::pair<int, std::string>;
 
    using PolygonSet = std::vector<std::vector<std::vector<VECTOR2I>>>;
 
    using Storage = std::variant<std::monostate, bool, int, int64_t, double, std::string, KIID, VECTOR2I, BOX2I,
                                 KIGFX::COLOR4D, PCB_LAYER_ID, EnumValue, PolygonSet>;
 
    DIFF_VALUE() : m_type( T::NONE ), m_value( std::monostate{} ) {}
 
    static DIFF_VALUE FromBool( bool aValue );
    static DIFF_VALUE FromInt( int aValue );
    static DIFF_VALUE FromInt64( int64_t aValue );
    static DIFF_VALUE FromDouble( double aValue );
    static DIFF_VALUE FromString( const wxString& aValue );
    static DIFF_VALUE FromString( const std::string& aValue );
    static DIFF_VALUE FromKiid( const KIID& aValue );
    static DIFF_VALUE FromVector2I( const VECTOR2I& aValue );
    static DIFF_VALUE FromBox2I( const BOX2I& aValue );
    static DIFF_VALUE FromColor( const KIGFX::COLOR4D& aValue );
    static DIFF_VALUE FromLayer( PCB_LAYER_ID aLayer );
    static DIFF_VALUE FromEnum( int aValue, const std::string& aLabel );
    static DIFF_VALUE FromPolygonSet( PolygonSet aValue );
 
    T              GetType() const { return m_type; }
    const Storage& GetStorage() const { return m_value; }
 
    bool      AsBool() const;
    int       AsInt() const;
    int64_t   AsInt64() const;
    double    AsDouble() const;
    wxString  AsString() const;
    KIID      AsKiid() const;
    VECTOR2I  AsVector2I() const;
    BOX2I     AsBox2I() const;
    KIGFX::COLOR4D AsColor() const;
    PCB_LAYER_ID   AsLayer() const;
    EnumValue AsEnum() const;
    const PolygonSet& AsPolygonSet() const;

    DIFF_VALUE WithDisplayHint( DISPLAY_HINT aHint ) const
    {
        DIFF_VALUE v = *this;
        v.m_displayHint = aHint;
        return v;
    }
 
    DISPLAY_HINT GetDisplayHint() const { return m_displayHint; }

    wxString ToDisplayString() const;

    wxString ToDisplayString( EDA_UNITS aUnits, const EDA_IU_SCALE& aScale ) const;
 
    bool operator==( const DIFF_VALUE& aOther ) const;
    bool operator!=( const DIFF_VALUE& aOther ) const { return !( *this == aOther ); }
 
    nlohmann::json    ToJson() const;
    static DIFF_VALUE FromJson( const nlohmann::json& aJson );
 
private:
    T            m_type;
    Storage      m_value;

    DISPLAY_HINT m_displayHint = DISPLAY_HINT::NONE;
};
 

struct KICOMMON_API PROPERTY_DELTA
{
    wxString   name;
    DIFF_VALUE before;
    DIFF_VALUE after;
 
    bool operator==( const PROPERTY_DELTA& aOther ) const;
    nlohmann::json        ToJson() const;
    static PROPERTY_DELTA FromJson( const nlohmann::json& aJson );
};
 

struct KICOMMON_API ITEM_CHANGE
{
    KIID_PATH                   id;
    wxString                    typeName;
    CHANGE_KIND                 kind = CHANGE_KIND::MODIFIED;
    std::vector<PROPERTY_DELTA> properties;
    BOX2I                       bbox;
    std::optional<wxString>     refdes;
    std::vector<ITEM_CHANGE>    children;
 
    bool operator==( const ITEM_CHANGE& aOther ) const;
    nlohmann::json     ToJson() const;
    static ITEM_CHANGE FromJson( const nlohmann::json& aJson );
};
 

struct KICOMMON_API DOCUMENT_DIFF
{
    wxString                 path;       // identifier for the document being diffed
    wxString                 docType;    // "kicad_pcb", "kicad_sch", "kicad_sym", "pretty", ...
    std::vector<ITEM_CHANGE> changes;
 
    bool   Empty() const { return changes.empty(); }
    size_t Size()  const { return changes.size(); }
 
    nlohmann::json       ToJson() const;
    static DOCUMENT_DIFF FromJson( const nlohmann::json& aJson );
};
 

struct KICOMMON_API PROJECT_DIFF
{
    std::vector<DOCUMENT_DIFF> documents;
 
    bool Empty() const;
 
    nlohmann::json      ToJson() const;
    static PROJECT_DIFF FromJson( const nlohmann::json& aJson );
};
 
 
KICOMMON_API const char* ChangeKindToString( CHANGE_KIND aKind );
KICOMMON_API CHANGE_KIND ChangeKindFromString( const std::string& aKind );
 

KICOMMON_API std::string FormatDiffAsText( const DOCUMENT_DIFF& aDiff, const wxString& aLabelA,
                                           const wxString& aLabelB, EDA_UNITS aUnits,
                                           const EDA_IU_SCALE& aScale );
 

KICOMMON_API bool WriteDiffOutput( const std::string& aContent, const wxString& aOutputPath );
 

KICOMMON_API std::map<KIID_PATH, const ITEM_CHANGE*>
IndexChangesByKiid( const DOCUMENT_DIFF& aDiff );
 

KICOMMON_API std::map<wxString, const PROPERTY_DELTA*>
IndexPropertiesByName( const ITEM_CHANGE& aChange );
 

inline bool ChangeInvalidatesZone( const ITEM_CHANGE& aChange )
{
    return aChange.typeName == wxS( "ZONE" )
        || aChange.typeName == wxS( "PCB_TRACK" )
        || aChange.typeName == wxS( "PCB_ARC" )
        || aChange.typeName == wxS( "PCB_VIA" )
        || aChange.typeName == wxS( "FOOTPRINT" )
        || aChange.typeName == wxS( "PAD" );
}
 

inline bool ChangeRequiresConnectivityRebuild( const ITEM_CHANGE& aChange )
{
    // Class names match SCH_ITEM::GetClass() / BOARD_ITEM::GetClass() exactly,
    // because the differ stores `GetClass()` in `ITEM_CHANGE::typeName`. Net
    // carriers (anything that can change net membership at its endpoints) and
    // connection markers (junction, no-connect) all belong here — missing one
    // means the merge engine skips the connectivity recompute and the saved
    // board / schematic ships with a stale netlist.
    return aChange.typeName == wxS( "PCB_TRACK" )
        || aChange.typeName == wxS( "PCB_ARC" )
        || aChange.typeName == wxS( "PCB_VIA" )
        || aChange.typeName == wxS( "PCB_SHAPE" )    // copper-layer shapes carry nets
        || aChange.typeName == wxS( "PAD" )
        || aChange.typeName == wxS( "SCH_LINE" )
        || aChange.typeName == wxS( "SCH_PIN" )
        || aChange.typeName == wxS( "SCH_SYMBOL" )   // pin positions move with the symbol
        || aChange.typeName == wxS( "SCH_LABEL" )
        || aChange.typeName == wxS( "SCH_GLOBALLABEL" )
        || aChange.typeName == wxS( "SCH_HIERLABEL" )
        || aChange.typeName == wxS( "SCH_DIRECTIVE_LABEL" )
        || aChange.typeName == wxS( "SCH_JUNCTION" )
        || aChange.typeName == wxS( "SCH_NO_CONNECT" )
        || aChange.typeName == wxS( "SCH_SHEET_PIN" )
        || aChange.typeName == wxS( "SCH_BUS_WIRE_ENTRY" )
        || aChange.typeName == wxS( "SCH_BUS_BUS_ENTRY" )
        || aChange.typeName == wxS( "SCH_SHEET" )         // pin / file / pos affects nets
        || aChange.typeName == wxS( "SCH_RULE_AREA" );    // feeds resolved netclass caches
}
 
} // namespace KICAD_DIFF
 
#endif // KICAD_DIFF_TYPES_H