json_settings.h

Go to the documentation of this file.

/*
 * This program source code file is part of KiCad, a free EDA CAD application.
 *
 * Copyright (C) 2020 Jon Evans <[email protected]>
 * Copyright The KiCad Developers, see AUTHORS.txt for contributors.
 *
 * This program is free software: you can redistribute it and/or modify it
 * under the terms of the GNU General Public License as published by the
 * Free Software Foundation, either version 3 of the License, or (at your
 * option) any later version.
 *
 * This program is distributed in the hope that it will be useful, but
 * WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program.  If not, see <https://www.gnu.org/licenses/>.
 */
 
#ifndef _JSON_SETTINGS_H
#define _JSON_SETTINGS_H
 
#include <core/wx_stl_compat.h>
 
#include <utility>
#include <wx/string.h>
 
#include <functional>
#include <optional>
#include <nlohmann/json_fwd.hpp>
#include <json_conversions.h>
 
#include <kicommon.h>
 
class wxConfigBase;
class NESTED_SETTINGS;
class PARAM_BASE;
class PROJECT;
class SETTINGS_MANAGER;
 
class wxAuiPaneInfo;
struct BOM_FIELD;
struct BOM_PRESET;
struct BOM_FMT_PRESET;
struct GRID;
 
namespace KIGFX
{
class COLOR4D;
enum class CROSS_HAIR_MODE : int;
};
 
#define traceSettings wxT( "KICAD_SETTINGS" )
 
enum class SETTINGS_LOC {
    USER,       
    PROJECT,    
    COLORS,     
    TOOLBARS,   
    NESTED,     
    NONE,       
};
 

class JSON_SETTINGS_INTERNALS;
 
class KICOMMON_API JSON_SETTINGS
{
public:
    friend class NESTED_SETTINGS;
 
    JSON_SETTINGS( const wxString& aFilename, SETTINGS_LOC aLocation, int aSchemaVersion ) :
            JSON_SETTINGS( aFilename, aLocation, aSchemaVersion, true, true, true )
    {}
 
    JSON_SETTINGS( const wxString& aFilename, SETTINGS_LOC aLocation, int aSchemaVersion,
                   bool aCreateIfMissing, bool aCreateIfDefault, bool aWriteFile );
 
    virtual ~JSON_SETTINGS();
 
    // We own at least one list of raw pointers.  Don't let the compiler fill in copy c'tors that
    // will only land us in trouble.
    JSON_SETTINGS( const JSON_SETTINGS& ) = delete;
    JSON_SETTINGS& operator=( const JSON_SETTINGS& ) = delete;
 
    wxString GetFilename() const { return m_filename; }
 
    wxString GetFullFilename() const;
 
    void SetFilename( const wxString& aFilename ) { m_filename = aFilename; }
 
    void SetLocation( SETTINGS_LOC aLocation ) { m_location = aLocation; }
    SETTINGS_LOC GetLocation() const { return m_location; }

    virtual const PROJECT* GetOwningProject() const { return nullptr; }
 
    void SetLegacyFilename( const wxString& aFilename ) { m_legacy_filename = aFilename; }
 
    bool IsReadOnly() const { return !m_writeFile; }
    void SetReadOnly( bool aReadOnly ) { m_writeFile = !aReadOnly; }

    bool ResetsParamsIfMissing() const { return m_resetParamsIfMissing; }

 
    nlohmann::json& At( const std::string& aPath );
    bool Contains( const std::string& aPath ) const;
 
    JSON_SETTINGS_INTERNALS* Internals();

    virtual void Load();

    virtual bool Store();

    virtual bool LoadFromFile( const wxString& aDirectory = "" );

    virtual bool SaveToFile( const wxString& aDirectory = "", bool aForce = false );

    bool IsFileSynced() const { return m_fileSynced; }

    void ResetToDefaults();

    std::optional<nlohmann::json> GetJson( const std::string& aPath ) const;

    template<typename ValueType>
    std::optional<ValueType> Get( const std::string& aPath ) const;

    template<typename ValueType>
    void Set( const std::string& aPath, ValueType aVal );
 
    virtual std::map<std::string, nlohmann::json> GetFileHistories();

    bool Migrate();

    virtual bool MigrateFromLegacy( wxConfigBase* aLegacyConfig );

    void AddNestedSettings( NESTED_SETTINGS* aSettings );

    void ReleaseNestedSettings( NESTED_SETTINGS* aSettings );
 
    void SetManager( SETTINGS_MANAGER* aManager )
    {
        m_manager = aManager;
    }

    static bool SetIfPresent( const nlohmann::json& aObj, const std::string& aPath,
                              wxString& aTarget );

    static bool SetIfPresent( const nlohmann::json& aObj, const std::string& aPath, bool& aTarget );

    static bool SetIfPresent( const nlohmann::json& aObj, const std::string& aPath, int& aTarget );

    static bool SetIfPresent( const nlohmann::json& aObj, const std::string& aPath ,
                              unsigned int& aTarget );
 
    const std::string FormatAsString();
 
    bool LoadFromRawFile( const wxString& aPath );
 
protected:

    void registerMigration( int aOldSchemaVersion, int aNewSchemaVersion,
                            std::function<bool(void)> aMigrator );

    template<typename ValueType>
    bool fromLegacy( wxConfigBase* aConfig, const std::string& aKey, const std::string& aDest );

    bool fromLegacyString( wxConfigBase* aConfig, const std::string& aKey,
                           const std::string& aDest );

    bool fromLegacyColor( wxConfigBase* aConfig, const std::string& aKey,
                          const std::string& aDest );
 
    virtual wxString getFileExt() const
    {
        return wxT( "json" );
    }
 
    virtual wxString getLegacyFileExt() const
    {
        return wxEmptyString;
    }

    template<typename ResultType>
    static ResultType fetchOrDefault( const nlohmann::json& aJson, const std::string& aKey,
                                      ResultType aDefault = ResultType() );

    wxString m_filename;

    wxString m_legacy_filename;

    SETTINGS_LOC m_location;

    std::vector<PARAM_BASE*> m_params;

    std::vector<NESTED_SETTINGS*> m_nested_settings;

    bool m_createIfMissing;

    bool m_createIfDefault;

    bool m_writeFile;

    bool m_modified;

    bool m_fileSynced;

    bool m_deleteLegacyAfterMigration;

    bool m_resetParamsIfMissing;

    int m_schemaVersion;

    bool m_isFutureFormat;

    SETTINGS_MANAGER* m_manager;

    std::map<int, std::pair<int, std::function<bool()>>> m_migrators;
 
    std::unique_ptr<JSON_SETTINGS_INTERNALS> m_internals;
};
 
// Specializations to allow conversion between wxString and std::string via JSON_SETTINGS API
 
template<> KICOMMON_API std::optional<wxString> JSON_SETTINGS::Get( const std::string& aPath ) const;
 
template<> KICOMMON_API void JSON_SETTINGS::Set<wxString>( const std::string& aPath, wxString aVal );
 
// Specializations to allow directly reading/writing wxStrings from JSON
 
KICOMMON_API void to_json( nlohmann::json& aJson, const wxString& aString );
 
KICOMMON_API void from_json( const nlohmann::json& aJson, wxString& aString );
 
extern template std::optional<bool>   JSON_SETTINGS::Get<bool>( const std::string& aPath ) const;
extern template std::optional<double> JSON_SETTINGS::Get<double>( const std::string& aPath ) const;
extern template std::optional<float>  JSON_SETTINGS::Get<float>( const std::string& aPath ) const;
extern template std::optional<int>    JSON_SETTINGS::Get<int>( const std::string& aPath ) const;
extern template std::optional<unsigned int> JSON_SETTINGS::Get<unsigned int>( const std::string& aPath ) const;
extern template std::optional<unsigned long long> JSON_SETTINGS::Get<unsigned long long>( const std::string& aPath ) const;
extern template std::optional<std::string> JSON_SETTINGS::Get<std::string>( const std::string& aPath ) const;
extern template std::optional<nlohmann::json> JSON_SETTINGS::Get<nlohmann::json>( const std::string& aPath ) const;
extern template std::optional<KIGFX::COLOR4D> JSON_SETTINGS::Get<KIGFX::COLOR4D>( const std::string& aPath ) const;
extern template std::optional<BOM_FIELD> JSON_SETTINGS::Get<BOM_FIELD>( const std::string& aPath ) const;
extern template std::optional<BOM_PRESET> JSON_SETTINGS::Get<BOM_PRESET>( const std::string& aPath ) const;
extern template std::optional<BOM_FMT_PRESET> JSON_SETTINGS::Get<BOM_FMT_PRESET>( const std::string& aPath ) const;
extern template std::optional<GRID> JSON_SETTINGS::Get<GRID>( const std::string& aPath ) const;
extern template std::optional<wxPoint> JSON_SETTINGS::Get<wxPoint>( const std::string& aPath ) const;
extern template std::optional<wxSize> JSON_SETTINGS::Get<wxSize>( const std::string& aPath ) const;
extern template std::optional<wxRect> JSON_SETTINGS::Get<wxRect>( const std::string& aPath ) const;
extern template std::optional<wxAuiPaneInfo> JSON_SETTINGS::Get<wxAuiPaneInfo>( const std::string& aPath ) const;
extern template std::optional<KIGFX::CROSS_HAIR_MODE> JSON_SETTINGS::Get<KIGFX::CROSS_HAIR_MODE>( const std::string& aPath ) const;
 
#endif