KiCad PCB EDA Suite
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 <jon@craftyjon.com>
5  * Copyright (C) 2020 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 along
18  * with this program. If not, see <http://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 <core/optional.h>
30 #include <nlohmann/json_fwd.hpp>
31 
32 class wxConfigBase;
33 class NESTED_SETTINGS;
34 class PARAM_BASE;
35 class SETTINGS_MANAGER;
36 
44 extern const wxChar* const traceSettings;
45 
46 enum class SETTINGS_LOC {
47  USER,
48  PROJECT,
49  COLORS,
50  NESTED,
51  NONE,
52 };
53 
54 
57 
59 {
60 public:
61  friend class NESTED_SETTINGS;
62 
63  JSON_SETTINGS( const wxString& aFilename, SETTINGS_LOC aLocation, int aSchemaVersion ) :
64  JSON_SETTINGS( aFilename, aLocation, aSchemaVersion, true, true, true ) {}
65 
66  JSON_SETTINGS( const wxString& aFilename, SETTINGS_LOC aLocation, int aSchemaVersion,
67  bool aCreateIfMissing, bool aCreateIfDefault, bool aWriteFile );
68 
69  virtual ~JSON_SETTINGS();
70 
71  wxString GetFilename() const { return m_filename; }
72 
73  wxString GetFullFilename() const;
74 
75  void SetFilename( const wxString& aFilename ) { m_filename = aFilename; }
76 
77  SETTINGS_LOC GetLocation() const { return m_location; }
78 
79  void SetLegacyFilename( const wxString& aFilename ) { m_legacy_filename = aFilename; }
80 
81  bool IsReadOnly() const { return !m_writeFile; }
82  void SetReadOnly( bool aReadOnly ) { m_writeFile = !aReadOnly; }
83 
89  nlohmann::json& At( const std::string& aPath );
90  bool Contains( const std::string& aPath ) const;
91  size_t Count( const std::string& aPath ) const;
92 
94 
98  virtual void Load();
99 
105  virtual bool Store();
106 
112  virtual bool LoadFromFile( const wxString& aDirectory = "" );
113 
119  virtual bool SaveToFile( const wxString& aDirectory = "", bool aForce = false );
120 
124  void ResetToDefaults();
125 
131  bool IsDefault( const std::string& aParamName );
132 
139  OPT<nlohmann::json> GetJson( const std::string& aPath ) const;
140 
148  template<typename ValueType>
149  OPT<ValueType> Get( const std::string& aPath ) const;
150 
158  template<typename ValueType>
159  void Set( const std::string& aPath, ValueType aVal );
160 
170  bool Migrate();
171 
178  virtual bool MigrateFromLegacy( wxConfigBase* aLegacyConfig );
179 
188  void AddNestedSettings( NESTED_SETTINGS* aSettings );
189 
194  void ReleaseNestedSettings( NESTED_SETTINGS* aSettings );
195 
196  void SetManager( SETTINGS_MANAGER* aManager )
197  {
198  m_manager = aManager;
199  }
200 
207  static bool SetIfPresent( const nlohmann::json& aObj, const std::string& aPath,
208  wxString& aTarget );
209 
216  static bool SetIfPresent( const nlohmann::json& aObj, const std::string& aPath, bool& aTarget );
217 
224  static bool SetIfPresent( const nlohmann::json& aObj, const std::string& aPath, int& aTarget );
225 
232  static bool SetIfPresent( const nlohmann::json& aObj, const std::string& aPath,
233  unsigned int& aTarget );
234 protected:
235 
244  void registerMigration( int aOldSchemaVersion, int aNewSchemaVersion,
245  std::function<bool(void)> aMigrator );
246 
254  template<typename ValueType>
255  bool fromLegacy( wxConfigBase* aConfig, const std::string& aKey, const std::string& aDest );
256 
263  bool fromLegacyString( wxConfigBase* aConfig, const std::string& aKey,
264  const std::string& aDest );
265 
272  bool fromLegacyColor( wxConfigBase* aConfig, const std::string& aKey,
273  const std::string& aDest );
274 
275  virtual wxString getFileExt() const
276  {
277  return wxT( "json" );
278  }
279 
280  virtual wxString getLegacyFileExt() const
281  {
282  return wxEmptyString;
283  }
284 
286  wxString m_filename;
287 
290 
293 
295  std::vector<PARAM_BASE*> m_params;
296 
298  std::vector<NESTED_SETTINGS*> m_nested_settings;
299 
302 
308 
311 
314 
317 
320 
323 
325  std::map<int, std::pair<int, std::function<bool()>>> m_migrators;
326 
327  std::unique_ptr<JSON_SETTINGS_INTERNALS> m_internals;
328 };
329 
330 // Specializations to allow conversion between wxString and std::string via JSON_SETTINGS API
331 
332 template<> OPT<wxString> JSON_SETTINGS::Get( const std::string& aPath ) const;
333 
334 template<> void JSON_SETTINGS::Set<wxString>( const std::string& aPath, wxString aVal );
335 
336 // Specializations to allow directly reading/writing wxStrings from JSON
337 
338 void to_json( nlohmann::json& aJson, const wxString& aString );
339 
340 void from_json( const nlohmann::json& aJson, wxString& aString );
341 
342 #endif
void ResetToDefaults()
Resets all parameters to default values.
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...
virtual bool Store()
Stores the current parameters into the JSON document represented by this object Note: this doesn't do...
JSON_SETTINGS_INTERNALS * Internals()
std::vector< PARAM_BASE * > m_params
The list of parameters (owned by this object)
void from_json(const nlohmann::json &aJson, wxString &aString)
bool m_createIfMissing
Whether or not the backing store file should be created it if doesn't exist.
void SetReadOnly(bool aReadOnly)
Definition: json_settings.h:82
wxString GetFilename() const
Definition: json_settings.h:71
virtual wxString getLegacyFileExt() const
SETTINGS_LOC
Definition: json_settings.h:46
virtual bool LoadFromFile(const wxString &aDirectory="")
Loads the backing file from disk and then calls Load()
OPT< nlohmann::json > GetJson(const std::string &aPath) const
Fetches a JSON object that is a subset of this JSON_SETTINGS object, using a path of the form "key1....
wxString GetFullFilename() const
nlohmann::json json
Definition: gerbview.cpp:41
nlohmann::json & At(const std::string &aPath)
Wrappers for the underlying JSON API so that most consumers don't need json.hpp All of these function...
void AddNestedSettings(NESTED_SETTINGS *aSettings)
Transfers ownership of a given NESTED_SETTINGS to this object.
bool m_deleteLegacyAfterMigration
Whether or not to delete legacy file after migration.
void to_json(nlohmann::json &aJson, const wxString &aString)
The color scheme directory (e.g. ~/.config/kicad/colors/)
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>
wxString m_filename
The filename (not including path) of this settings file (inicode)
bool Migrate()
Migrates the schema of this settings from the version in the file to the latest version.
NESTED_SETTINGS is a JSON_SETTINGS that lives inside a JSON_SETTINGS.
virtual bool SaveToFile(const wxString &aDirectory="", bool aForce=false)
wxString m_legacy_filename
The filename of the wxConfig legacy file (if different from m_filename)
The settings directory inside a project folder.
std::unique_ptr< JSON_SETTINGS_INTERNALS > m_internals
SETTINGS_LOC GetLocation() const
Definition: json_settings.h:77
static bool SetIfPresent(const nlohmann::json &aObj, const std::string &aPath, wxString &aTarget)
Sets the given string if the given key/path is present.
void SetManager(SETTINGS_MANAGER *aManager)
std::vector< NESTED_SETTINGS * > m_nested_settings
Nested settings files that live inside this one, if any.
No directory prepended, full path in filename (used for PROJECT_FILE)
JSON_SETTINGS(const wxString &aFilename, SETTINGS_LOC aLocation, int aSchemaVersion)
Definition: json_settings.h:63
SETTINGS_LOC m_location
The location of this settings file (.
bool IsDefault(const std::string &aParamName)
Checks if the current state of a parameter matches its default value.
Not stored in a file, but inside another JSON_SETTINGS.
bool fromLegacyString(wxConfigBase *aConfig, const std::string &aKey, const std::string &aDest)
Translates a legacy wxConfig string value to a given JSON pointer value.
bool m_resetParamsIfMissing
Whether or not to set parameters to their default value if missing from JSON on Load()
bool fromLegacyColor(wxConfigBase *aConfig, const std::string &aKey, const std::string &aDest)
Translates a legacy COLOR4D stored in a wxConfig string to a given JSON pointer value.
void registerMigration(int aOldSchemaVersion, int aNewSchemaVersion, std::function< bool(void)> aMigrator)
Registers a migration from one schema version to another.
OPT< ValueType > Get(const std::string &aPath) const
Fetches a value from within the JSON document.
The main config directory (e.g. ~/.config/kicad/)
bool IsReadOnly() const
Definition: json_settings.h:81
boost::optional< T > OPT
Definition: optional.h:7
bool fromLegacy(wxConfigBase *aConfig, const std::string &aKey, const std::string &aDest)
Translates a legacy wxConfig value to a given JSON pointer value.
bool Contains(const std::string &aPath) const
virtual ~JSON_SETTINGS()
const wxChar *const traceSettings
Flag to enable debug output of settings operations and management.
void SetFilename(const wxString &aFilename)
Definition: json_settings.h:75
bool m_createIfDefault
Whether or not the backing store file should be created if all parameters are still at their default ...
void ReleaseNestedSettings(NESTED_SETTINGS *aSettings)
Saves and frees a nested settings object, if it exists within this one.
SETTINGS_MANAGER * m_manager
A pointer to the settings manager managing this file (may be null)
virtual wxString getFileExt() const
virtual bool MigrateFromLegacy(wxConfigBase *aLegacyConfig)
Migrates from wxConfig to JSON-based configuration.
void SetLegacyFilename(const wxString &aFilename)
Definition: json_settings.h:79
int m_schemaVersion
Version of this settings schema.
virtual void Load()
Updates the parameters of this object based on the current JSON document contents.
size_t Count(const std::string &aPath) const
bool m_writeFile
Whether or not the backing store file should be written.