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 (C) 2020 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 <http://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>
 
class wxConfigBase;
class NESTED_SETTINGS;
class PARAM_BASE;
class SETTINGS_MANAGER;
 
extern const wxChar* const traceSettings;
 
enum class SETTINGS_LOC {
 USER, 
 PROJECT, 
 COLORS, 
 NESTED, 
 NONE, 
};
 
 
class JSON_SETTINGS_INTERNALS;
 
class 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();
 
 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; }
 
 void SetLegacyFilename( const wxString& aFilename ) { m_legacy_filename = aFilename; }
 
 bool IsReadOnly() const { return !m_writeFile; }
 void SetReadOnly( bool aReadOnly ) { m_writeFile = !aReadOnly; }
 
 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 );
 
 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 );
 
 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() const;
 
 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_deleteLegacyAfterMigration;
 
 bool m_resetParamsIfMissing;
 
 int m_schemaVersion;
 
 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<> std::optional<wxString> JSON_SETTINGS::Get( const std::string& aPath ) const;
 
template<> void JSON_SETTINGS::Set<wxString>( const std::string& aPath, wxString aVal );
 
// Specializations to allow directly reading/writing wxStrings from JSON
 
void to_json( nlohmann::json& aJson, const wxString& aString );
 
void from_json( const nlohmann::json& aJson, wxString& aString );
 
#endif