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 <nlohmann/json.hpp>
25 #include <utility>
26 #include <wx/string.h>
27 
28 #include <core/optional.h>
29 
30 class wxConfigBase;
31 class NESTED_SETTINGS;
32 class PARAM_BASE;
33 class SETTINGS_MANAGER;
34 
35 
36 enum class SETTINGS_LOC {
37  USER,
38  PROJECT,
39  COLORS,
40  NESTED,
41  NONE,
42 };
43 
44 
46 {
47 public:
48  JSON_SETTINGS( const std::string& aFilename, SETTINGS_LOC aLocation, int aSchemaVersion ) :
49  JSON_SETTINGS( aFilename, aLocation, aSchemaVersion, true, true, true ) {}
50 
51  JSON_SETTINGS( const std::string& aFilename, SETTINGS_LOC aLocation, int aSchemaVersion,
52  bool aCreateIfMissing, bool aCreateIfDefault, bool aWriteFile );
53 
54  virtual ~JSON_SETTINGS();
55 
56  std::string GetFilename() const { return m_filename; }
57 
58  wxString GetFullFilename() const;
59 
60  SETTINGS_LOC GetLocation() const { return m_location; }
61 
62  void SetLegacyFilename( const std::string& aFilename ) { m_legacy_filename = aFilename; }
63 
67  virtual void Load();
68 
74  virtual bool Store();
75 
81  virtual bool LoadFromFile( const std::string& aDirectory = "" );
82 
88  virtual bool SaveToFile( const std::string& aDirectory = "", bool aForce = false );
89 
93  void ResetToDefaults();
94 
101  OPT<nlohmann::json> GetJson( const std::string& aPath ) const;
102 
110  template<typename ValueType>
111  OPT<ValueType> Get( const std::string& aPath ) const
112  {
113  if( OPT<nlohmann::json> ret = GetJson( aPath ) )
114  {
115  try
116  {
117  return ret->get<ValueType>();
118  }
119  catch( ... )
120  {
121  }
122  }
123 
124  return NULLOPT;
125  }
126 
134  template<typename ValueType>
135  void Set( const std::string& aPath, ValueType aVal )
136  {
137  ( *this )[PointerFromString( aPath ) ] = aVal;
138  }
139 
149  virtual bool Migrate();
150 
157  virtual bool MigrateFromLegacy( wxConfigBase* aLegacyConfig );
158 
167  void AddNestedSettings( NESTED_SETTINGS* aSettings );
168 
173  void ReleaseNestedSettings( NESTED_SETTINGS* aSettings );
174 
175  void SetManager( SETTINGS_MANAGER* aManager )
176  {
177  m_manager = aManager;
178  }
179 
185  static nlohmann::json::json_pointer PointerFromString( std::string aPath );
186 
187 protected:
188 
196  template<typename ValueType>
197  bool fromLegacy( wxConfigBase* aConfig, const std::string& aKey, const std::string& aDest );
198 
205  bool fromLegacyString( wxConfigBase* aConfig, const std::string& aKey,
206  const std::string& aDest );
207 
214  bool fromLegacyColor( wxConfigBase* aConfig, const std::string& aKey,
215  const std::string& aDest );
216 
217  virtual wxString getFileExt() const
218  {
219  return wxT( "json" );
220  }
221 
222  virtual wxString getLegacyFileExt() const
223  {
224  return wxEmptyString;
225  }
226 
228  std::string m_filename;
229 
231  std::string m_legacy_filename;
232 
235 
237  std::vector<PARAM_BASE*> m_params;
238 
240  std::vector<NESTED_SETTINGS*> m_nested_settings;
241 
244 
250 
253 
256 
259 
262 
265 
267  std::vector<nlohmann::json::json_pointer> m_preserved_paths;
268 };
269 
270 // Specializations to allow conversion between wxString and std::string via JSON_SETTINGS API
271 
272 template<> OPT<wxString> JSON_SETTINGS::Get( const std::string& aPath ) const;
273 
274 template<> void JSON_SETTINGS::Set<wxString>( const std::string& aPath, wxString aVal );
275 
276 // Specializations to allow directly reading/writing wxStrings from JSON
277 
278 void to_json( nlohmann::json& aJson, const wxString& aString );
279 
280 void from_json( const nlohmann::json& aJson, wxString& aString );
281 
282 #endif
void ResetToDefaults()
Resets all parameters to default values.
std::vector< nlohmann::json::json_pointer > m_preserved_paths
A list of JSON pointers that are preserved during a read-update-write to disk.
virtual bool Store()
Stores the current parameters into the JSON document represented by this object Note: this doesn't do...
std::string m_filename
The filename (not including path) of this settings file.
std::vector< PARAM_BASE * > m_params
The list of parameters (owned by this object)
void from_json(const nlohmann::json &aJson, wxString &aString)
virtual bool SaveToFile(const std::string &aDirectory="", bool aForce=false)
bool m_createIfMissing
Whether or not the backing store file should be created it if doesn't exist.
virtual bool LoadFromFile(const std::string &aDirectory="")
Loads the backing file from disk and then calls Load()
virtual wxString getLegacyFileExt() const
SETTINGS_LOC
Definition: json_settings.h:36
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....
void SetLegacyFilename(const std::string &aFilename)
Definition: json_settings.h:62
wxString GetFullFilename() const
nlohmann::json json
Definition: gerbview.cpp:40
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.
OPT< ValueType > Get(const std::string &aPath) const
Fetches a value from within the JSON document.
void to_json(nlohmann::json &aJson, const wxString &aString)
The color scheme directory (e.g. ~/.config/kicad/colors/)
virtual 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.
const auto NULLOPT
Definition: optional.h:9
The settings directory inside a project folder.
SETTINGS_LOC GetLocation() const
Definition: json_settings.h:60
void SetManager(SETTINGS_MANAGER *aManager)
std::string m_legacy_filename
The filename of the wxConfig legacy file (if different from m_filename)
JSON_SETTINGS(const std::string &aFilename, SETTINGS_LOC aLocation, int aSchemaVersion)
Definition: json_settings.h:48
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)
SETTINGS_LOC m_location
The location of this settings file (.
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.
The main config directory (e.g. ~/.config/kicad/)
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.
std::string GetFilename() const
Definition: json_settings.h:56
virtual ~JSON_SETTINGS()
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
static nlohmann::json::json_pointer PointerFromString(std::string aPath)
Builds a JSON pointer based on a given string.
virtual bool MigrateFromLegacy(wxConfigBase *aLegacyConfig)
Migrates from wxConfig to JSON-based configuration.
int m_schemaVersion
Version of this settings schema.
virtual void Load()
Updates the parameters of this object based on the current JSON document contents.
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...
bool m_writeFile
Whether or not the backing store file should be written.