KiCad PCB EDA Suite
Loading...
Searching...
No Matches
json_settings.h
Go to the documentation of this file.
1/*
2 * This program source code file is part of KiCad, a free EDA CAD application.
3 *
4 * Copyright (C) 2020 Jon Evans <[email protected]>
5 * Copyright The KiCad Developers, see AUTHORS.txt for contributors.
6 *
7 * This program is free software: you can redistribute it and/or modify it
8 * under the terms of the GNU General Public License as published by the
9 * Free Software Foundation, either version 3 of the License, or (at your
10 * option) any later version.
11 *
12 * This program is distributed in the hope that it will be useful, but
13 * WITHOUT ANY WARRANTY; without even the implied warranty of
14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 * General Public License for more details.
16 *
17 * You should have received a copy of the GNU General Public License
18 * along with this program. If not, see <https://www.gnu.org/licenses/>.
19 */
20
21#ifndef _JSON_SETTINGS_H
22#define _JSON_SETTINGS_H
23
24#include <core/wx_stl_compat.h>
25
26#include <utility>
27#include <wx/string.h>
28
29#include <functional>
30#include <optional>
31#include <nlohmann/json_fwd.hpp>
32#include <json_conversions.h>
33
34#include <kicommon.h>
35
36class wxConfigBase;
37class NESTED_SETTINGS;
38class PARAM_BASE;
39class PROJECT;
41
42class wxAuiPaneInfo;
43struct BOM_FIELD;
44struct BOM_PRESET;
45struct BOM_FMT_PRESET;
46struct GRID;
47
48namespace KIGFX
49{
50class COLOR4D;
51enum class CROSS_HAIR_MODE : int;
52};
53
54#define traceSettings wxT( "KICAD_SETTINGS" )
55
64
65
68
70{
71public:
72 friend class NESTED_SETTINGS;
73
74 JSON_SETTINGS( const wxString& aFilename, SETTINGS_LOC aLocation, int aSchemaVersion ) :
75 JSON_SETTINGS( aFilename, aLocation, aSchemaVersion, true, true, true )
76 {}
77
78 JSON_SETTINGS( const wxString& aFilename, SETTINGS_LOC aLocation, int aSchemaVersion,
79 bool aCreateIfMissing, bool aCreateIfDefault, bool aWriteFile );
80
81 virtual ~JSON_SETTINGS();
82
83 // We own at least one list of raw pointers. Don't let the compiler fill in copy c'tors that
84 // will only land us in trouble.
85 JSON_SETTINGS( const JSON_SETTINGS& ) = delete;
87
88 wxString GetFilename() const { return m_filename; }
89
90 wxString GetFullFilename() const;
91
92 void SetFilename( const wxString& aFilename ) { m_filename = aFilename; }
93
94 void SetLocation( SETTINGS_LOC aLocation ) { m_location = aLocation; }
96
101 virtual const PROJECT* GetOwningProject() const { return nullptr; }
102
103 void SetLegacyFilename( const wxString& aFilename ) { m_legacy_filename = aFilename; }
104
105 bool IsReadOnly() const { return !m_writeFile; }
106 void SetReadOnly( bool aReadOnly ) { m_writeFile = !aReadOnly; }
107
115
120
121 nlohmann::json& At( const std::string& aPath );
122 bool Contains( const std::string& aPath ) const;
123
124 JSON_SETTINGS_INTERNALS* Internals();
125
129 virtual void Load();
130
136 virtual bool Store();
137
143 virtual bool LoadFromFile( const wxString& aDirectory = "" );
144
152 bool LoadFromBuffer( const std::string& aContents );
153
160 virtual bool SaveToFile( const wxString& aDirectory = "", bool aForce = false );
161
166 bool IsFileSynced() const { return m_fileSynced; }
167
174 bool LastSaveFailed() const { return m_lastSaveFailed; }
175
177 bool IsFutureFormat() const { return m_isFutureFormat; }
178
182 void ResetToDefaults();
183
190 std::optional<nlohmann::json> GetJson( const std::string& aPath ) const;
191
199 template<typename ValueType>
200 std::optional<ValueType> Get( const std::string& aPath ) const;
201
209 template<typename ValueType>
210 void Set( const std::string& aPath, ValueType aVal );
211
212 virtual std::map<std::string, nlohmann::json> GetFileHistories();
213
223 bool Migrate();
224
231 virtual bool MigrateFromLegacy( wxConfigBase* aLegacyConfig );
232
240 void AddNestedSettings( NESTED_SETTINGS* aSettings );
241
246 void ReleaseNestedSettings( NESTED_SETTINGS* aSettings );
247
248 void SetManager( SETTINGS_MANAGER* aManager )
249 {
250 m_manager = aManager;
251 }
252
260 static bool SetIfPresent( const nlohmann::json& aObj, const std::string& aPath, wxString& aTarget );
261
269 static bool SetIfPresent( const nlohmann::json& aObj, const std::string& aPath, bool& aTarget );
270
278 static bool SetIfPresent( const nlohmann::json& aObj, const std::string& aPath, int& aTarget );
279
287 static bool SetIfPresent( const nlohmann::json& aObj, const std::string& aPath, unsigned int& aTarget );
288
289 const std::string FormatAsString();
290
291 bool LoadFromRawFile( const wxString& aPath );
292
293protected:
295 const nlohmann::json& originalJson() const;
296
305 void registerMigration( int aOldSchemaVersion, int aNewSchemaVersion,
306 std::function<bool(void)> aMigrator );
307
315 template<typename ValueType>
316 bool fromLegacy( wxConfigBase* aConfig, const std::string& aKey, const std::string& aDest );
317
324 bool fromLegacyString( wxConfigBase* aConfig, const std::string& aKey,
325 const std::string& aDest );
326
333 bool fromLegacyColor( wxConfigBase* aConfig, const std::string& aKey,
334 const std::string& aDest );
335
340 bool flushToStore();
341
346 std::string formatFileContents();
347
348 virtual wxString getFileExt() const
349 {
350 return wxT( "json" );
351 }
352
353 virtual wxString getLegacyFileExt() const
354 {
355 return wxEmptyString;
356 }
357
366 template<typename ResultType>
367 static ResultType fetchOrDefault( const nlohmann::json& aJson, const std::string& aKey,
368 ResultType aDefault = ResultType() );
369
371 wxString m_filename;
372
375
378
380 std::vector<PARAM_BASE*> m_params;
381
383 std::vector<NESTED_SETTINGS*> m_nested_settings;
384
387
393
396
399
402
405
408
411
414
417
420
422 std::map<int, std::pair<int, std::function<bool()>>> m_migrators;
423
424 std::unique_ptr<JSON_SETTINGS_INTERNALS> m_internals;
425
426private:
434 bool parseAndMigrate( const std::function<bool( nlohmann::json& )>& aParse, bool& aMigrated,
435 bool& aParseError );
436};
437
438// Specializations to allow conversion between wxString and std::string via JSON_SETTINGS API
439
440template<> KICOMMON_API std::optional<wxString> JSON_SETTINGS::Get( const std::string& aPath ) const;
441
442template<> KICOMMON_API void JSON_SETTINGS::Set<wxString>( const std::string& aPath, wxString aVal );
443
444// Specializations to allow directly reading/writing wxStrings from JSON
445
446KICOMMON_API void to_json( nlohmann::json& aJson, const wxString& aString );
447
448KICOMMON_API void from_json( const nlohmann::json& aJson, wxString& aString );
449
450extern template std::optional<bool> JSON_SETTINGS::Get<bool>( const std::string& aPath ) const;
451extern template std::optional<double> JSON_SETTINGS::Get<double>( const std::string& aPath ) const;
452extern template std::optional<float> JSON_SETTINGS::Get<float>( const std::string& aPath ) const;
453extern template std::optional<int> JSON_SETTINGS::Get<int>( const std::string& aPath ) const;
454extern template std::optional<unsigned int> JSON_SETTINGS::Get<unsigned int>( const std::string& aPath ) const;
455extern template std::optional<unsigned long long> JSON_SETTINGS::Get<unsigned long long>( const std::string& aPath ) const;
456extern template std::optional<std::string> JSON_SETTINGS::Get<std::string>( const std::string& aPath ) const;
457extern template std::optional<nlohmann::json> JSON_SETTINGS::Get<nlohmann::json>( const std::string& aPath ) const;
458extern template std::optional<KIGFX::COLOR4D> JSON_SETTINGS::Get<KIGFX::COLOR4D>( const std::string& aPath ) const;
459extern template std::optional<BOM_FIELD> JSON_SETTINGS::Get<BOM_FIELD>( const std::string& aPath ) const;
460extern template std::optional<BOM_PRESET> JSON_SETTINGS::Get<BOM_PRESET>( const std::string& aPath ) const;
461extern template std::optional<BOM_FMT_PRESET> JSON_SETTINGS::Get<BOM_FMT_PRESET>( const std::string& aPath ) const;
462extern template std::optional<GRID> JSON_SETTINGS::Get<GRID>( const std::string& aPath ) const;
463extern template std::optional<wxPoint> JSON_SETTINGS::Get<wxPoint>( const std::string& aPath ) const;
464extern template std::optional<wxSize> JSON_SETTINGS::Get<wxSize>( const std::string& aPath ) const;
465extern template std::optional<wxRect> JSON_SETTINGS::Get<wxRect>( const std::string& aPath ) const;
466extern template std::optional<wxAuiPaneInfo> JSON_SETTINGS::Get<wxAuiPaneInfo>( const std::string& aPath ) const;
467extern template std::optional<KIGFX::CROSS_HAIR_MODE> JSON_SETTINGS::Get<KIGFX::CROSS_HAIR_MODE>( const std::string& aPath ) const;
468
469#endif
KICAD_PLUGIN_EXPORT SCENEGRAPH * Load(char const *aFileName)
Read a model file and creates a generic display structure.
virtual wxString getFileExt() const
bool IsFutureFormat() const
void Set(const std::string &aPath, ValueType aVal)
Stores a value into the JSON document Will throw an exception if ValueType isn't something that the l...
JSON_SETTINGS & operator=(const JSON_SETTINGS &)=delete
wxString m_filename
The filename (not including path) of this settings file (inicode)
SETTINGS_MANAGER * m_manager
A pointer to the settings manager managing this file (may be null)
bool IsFileSynced() const
bool m_fileSynced
True once the store has been synchronized with an on-disk file (loaded or saved)
SETTINGS_LOC GetLocation() const
bool m_isFutureFormat
Set to true if this settings is loaded from a file with a newer schema version than is known.
std::vector< NESTED_SETTINGS * > m_nested_settings
Nested settings files that live inside this one, if any.
bool m_modified
True if the JSON data store has been written to since the last file write.
bool m_createIfDefault
Whether or not the backing store file should be created if all parameters are still at their default ...
JSON_SETTINGS(const JSON_SETTINGS &)=delete
void SetLocation(SETTINGS_LOC aLocation)
bool m_writeFile
Whether or not the backing store file should be written.
virtual const PROJECT * GetOwningProject() const
Project-located settings override this to report the project they belong to so their save path is res...
void SetManager(SETTINGS_MANAGER *aManager)
bool IsReadOnly() const
void SetReadOnly(bool aReadOnly)
bool parseAndMigrate(const std::function< bool(nlohmann::json &)> &aParse, bool &aMigrated, bool &aParseError)
Parses a document into the store through aParse, then checks the schema version and migrates.
bool m_createIfMissing
Whether or not the backing store file should be created it if doesn't exist.
std::optional< ValueType > Get(const std::string &aPath) const
Fetches a value from within the JSON document.
bool m_lastSaveFailed
True if the most recent SaveToFile() had changes to write and could not write them.
std::vector< PARAM_BASE * > m_params
The list of parameters (owned by this object)
bool ResetsParamsIfMissing() const
JSON_SETTINGS(const wxString &aFilename, SETTINGS_LOC aLocation, int aSchemaVersion)
bool m_deleteLegacyAfterMigration
Whether or not to delete legacy file after migration.
std::unique_ptr< JSON_SETTINGS_INTERNALS > m_internals
friend class NESTED_SETTINGS
void SetFilename(const wxString &aFilename)
SETTINGS_LOC m_location
The location of this settings file (.
virtual wxString getLegacyFileExt() const
bool LastSaveFailed() const
SaveToFile() also returns false when it had nothing to write, so its result cannot tell a skipped sav...
bool m_resetParamsIfMissing
Whether or not to set parameters to their default value if missing from JSON on Load()
void SetLegacyFilename(const wxString &aFilename)
std::map< int, std::pair< int, std::function< bool()> > > m_migrators
A map of starting schema version to a pair of <ending version, migrator function>
int m_schemaVersion
Version of this settings schema.
wxString m_legacy_filename
The filename of the wxConfig legacy file (if different from m_filename)
wxString GetFilename() const
A color representation with 4 components: red, green, blue, alpha.
Definition color4d.h:101
NESTED_SETTINGS is a JSON_SETTINGS that lives inside a JSON_SETTINGS.
Container for project specific data.
Definition project.h:63
@ NONE
Definition eda_fill.h:42
KICOMMON_API void to_json(nlohmann::json &aJson, const wxString &aString)
SETTINGS_LOC
@ TOOLBARS
The toolbar directory (e.g. ~/.config/kicad/toolbars/)
@ PROJECT
The settings directory inside a project folder.
@ USER
The main config directory (e.g. ~/.config/kicad/)
@ COLORS
The color scheme directory (e.g. ~/.config/kicad/colors/)
@ NESTED
Not stored in a file, but inside another JSON_SETTINGS.
KICOMMON_API void from_json(const nlohmann::json &aJson, wxString &aString)
#define KICOMMON_API
Definition kicommon.h:27
The Cairo implementation of the graphics abstraction layer.
Definition eda_group.h:30
Common grid settings, available to every frame.