KiCad PCB EDA Suite
symbol_library.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) 2015 Jean-Pierre Charras, jp.charras at wanadoo.fr
5  * Copyright (C) 2008 Wayne Stambaugh <stambaughw@gmail.com>
6  * Copyright (C) 2004-2021 KiCad Developers, see AUTHORS.txt for contributors.
7  *
8  * This program is free software; you can redistribute it and/or
9  * modify it under the terms of the GNU General Public License
10  * as published by the Free Software Foundation; either version 2
11  * of the License, or (at your option) any later version.
12  *
13  * This program is distributed in the hope that it will be useful,
14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16  * GNU General Public License for more details.
17  *
18  * You should have received a copy of the GNU General Public License
19  * along with this program; if not, you may find one here:
20  * http://www.gnu.org/licenses/old-licenses/gpl-2.0.html
21  * or you may search the http://www.gnu.org website for the version 2 license,
22  * or you may write to the Free Software Foundation, Inc.,
23  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA
24  */
25 
31 #ifndef SYMBOL_LIBRARY_H
32 #define SYMBOL_LIBRARY_H
33 
34 #include <map>
35 #include <mutex>
36 #include <boost/ptr_container/ptr_vector.hpp>
37 #include <wx/filename.h>
38 
39 #include <sch_io_mgr.h>
40 #include <project.h>
41 
42 class LIB_SYMBOL;
43 class LIB_ID;
44 class LINE_READER;
45 class OUTPUTFORMATTER;
46 class SCH_LEGACY_PLUGIN;
47 class SCH_PLUGIN;
48 
49 
50 #define DOC_EXT "dcm"
51 
52 /*
53  * Symbol Library version and file header macros.
54  */
55 #define LIB_VERSION_MAJOR 2
56 #define LIB_VERSION_MINOR 4
57 
58 /* Must be the first line of symbol library (.lib) files. */
59 #define LIBFILE_IDENT "EESchema-LIBRARY Version"
60 
61 #define LIB_VERSION( major, minor ) ( major * 100 + minor )
62 
63 #define IS_LIB_CURRENT_VERSION( major, minor ) \
64  ( \
65  LIB_VERSION( major1, minor1 ) == \
66  LIB_VERSION( LIB_VERSION_MAJOR, LIB_VERSION_MINOR) \
67  )
68 
69 /*
70  * Library versions 2.4 and lower use the old separate library (.lib) and
71  * document (.dcm) files. Symbol libraries after 2.4 merged the library
72  * and document files into a single library file. This macro checks if the
73  * library version supports the old format
74  */
75 #define USE_OLD_DOC_FILE_FORMAT( major, minor ) \
76  ( LIB_VERSION( major, minor ) <= LIB_VERSION( 2, 4 ) )
77 
78 enum class SCH_LIB_TYPE
79 {
81  LT_SYMBOL
82 };
83 
84 // Helper class to filter a list of libraries, and/or a list of SYMBOL_LIB
85 // in dialogs
87 {
88 public:
90  {
91  m_filterPowerSymbols = false;
92  m_forceLoad = false;
93  }
94 
98  void AddLib( const wxString& aLibName )
99  {
100  m_allowedLibs.Add( aLibName );
101  m_forceLoad = false;
102  }
103 
104 
108  void LoadFrom( const wxString& aLibName )
109  {
110  m_allowedLibs.Clear();
111  m_allowedLibs.Add( aLibName );
112  m_forceLoad = true;
113  }
114 
119  {
120  m_allowedLibs.Clear();
121  m_forceLoad = false;
122  }
123 
127  void FilterPowerSymbols( bool aFilterEnable )
128  {
129  m_filterPowerSymbols = aFilterEnable;
130  }
131 
132  // Accessors
133 
138 
139 
143  const wxArrayString& GetAllowedLibList() const { return m_allowedLibs; }
144 
149  const wxString& GetLibSource() const
150  {
151  static wxString dummy;
152 
153  if( m_forceLoad && m_allowedLibs.GetCount() > 0 )
154  return m_allowedLibs[0];
155  else
156  return dummy;
157  }
158 
159 private:
160  wxArrayString m_allowedLibs;
161  bool m_filterPowerSymbols;
163  bool m_forceLoad; // When true, load a symbol lib from the lib
164  // which is given in m_allowedLibs[0]
165 };
166 
167 
168 /* Helpers for creating a list of symbol libraries. */
169 class SYMBOL_LIB;
170 class wxRegEx;
171 
176 {
177  bool operator() ( const wxString& aItem1, const wxString& aItem2 ) const
178  {
179  return aItem1 < aItem2;
180  }
181 };
182 
184 
185 typedef std::map< wxString, LIB_SYMBOL*, LibSymbolMapSort > LIB_SYMBOL_MAP;
186 typedef boost::ptr_vector< SYMBOL_LIB > SYMBOL_LIBS_BASE;
187 
188 
196 {
197 public:
198  KICAD_T Type() override { return SYMBOL_LIBS_T; }
199 
200  static int s_modify_generation;
201  static std::mutex s_generationMutex;
202 
204  {
206  }
207 
209  {
210  std::lock_guard<std::mutex> mut( SYMBOL_LIBS::s_generationMutex );
212  }
213 
214  static int GetModifyGeneration()
215  {
216  std::lock_guard<std::mutex> mut( SYMBOL_LIBS::s_generationMutex );
218  }
219 
222  int GetModifyHash();
223 
230  SYMBOL_LIB* AddLibrary( const wxString& aFileName );
231 
240  SYMBOL_LIB* AddLibrary( const wxString& aFileName, SYMBOL_LIBS::iterator& aIterator );
241 
249  void LoadAllLibraries( PROJECT* aProject, bool aShowProgress=true );
250 
254  static void LibNamesAndPaths( PROJECT* aProject, bool doSave,
255  wxString* aPaths, wxArrayString* aNames = nullptr );
256 
263  static const wxString CacheName( const wxString& aFullProjectFilename );
264 
271  SYMBOL_LIB* FindLibrary( const wxString& aName );
272 
273  SYMBOL_LIB* FindLibraryByFullFileName( const wxString& aFullFileName );
274 
276 
283  wxArrayString GetLibraryNames( bool aSorted = true );
284 
295  LIB_SYMBOL* FindLibSymbol( const LIB_ID& aLibId, const wxString& aLibraryName = wxEmptyString );
296 
310  void FindLibraryNearEntries( std::vector<LIB_SYMBOL*>& aCandidates, const wxString& aEntryName,
311  const wxString& aLibraryName = wxEmptyString );
312 
313  int GetLibraryCount() { return size(); }
314 };
315 
316 
324 {
325 public:
326  SYMBOL_LIB( SCH_LIB_TYPE aType, const wxString& aFileName,
327  SCH_IO_MGR::SCH_FILE_T aPluginType = SCH_IO_MGR::SCH_LEGACY );
328  ~SYMBOL_LIB();
329 
333  int GetModHash() const { return m_mod_hash; }
334 
335  SCH_IO_MGR::SCH_FILE_T GetPluginType() const { return m_pluginType; }
336 
337  void SetPluginType( SCH_IO_MGR::SCH_FILE_T aPluginType );
338 
339  void Create( const wxString& aFileName = wxEmptyString );
340 
341  void SetFileName( const wxString& aFileName ) { fileName = aFileName; }
342 
343  bool IsModified() const
344  {
345  return isModified;
346  }
347 
348  bool IsCache() const;
349 
350  void SetCache();
351 
352  bool IsBuffering() const;
353 
354  void EnableBuffering( bool aEnable = true );
355 
356  void Save( bool aSaveDocFile = true );
357 
361  bool IsReadOnly() const { return !fileName.IsFileWritable(); }
362 
368  void GetSymbolNames( wxArrayString& aNames ) const;
369 
375  void GetSymbols( std::vector<LIB_SYMBOL*>& aSymbols ) const;
376 
383  LIB_SYMBOL* FindSymbol( const wxString& aName ) const;
384 
385  LIB_SYMBOL* FindSymbol( const LIB_ID& aLibId ) const;
386 
395  void AddSymbol( LIB_SYMBOL* aSymbol );
396 
408  LIB_SYMBOL* RemoveSymbol( LIB_SYMBOL* aEntry );
409 
419  LIB_SYMBOL* ReplaceSymbol( LIB_SYMBOL* aOldSymbol, LIB_SYMBOL* aNewSymbol );
420 
426  const wxString GetName() const { return fileName.GetName(); }
427 
433  wxString GetFullFileName() const { return fileName.GetFullPath(); }
434 
440  const wxString GetLogicalName() const
441  {
442  /* for now is the filename without path or extension.
443 
444  Technically the library should not know its logical name!
445  This will eventually come out of a pair of lookup tables using a
446  reverse lookup using the full name or library pointer as a key.
447  Search will be by project lookup table and then user lookup table if
448  not found.
449  */
450  return fileName.GetName();
451  }
452 
453 
461  static SYMBOL_LIB* LoadLibrary( const wxString& aFileName );
462 
463 private:
465  wxFileName fileName;
466  wxDateTime timeStamp;
469  wxString header;
470  bool isModified;
472 
473  SCH_IO_MGR::SCH_FILE_T m_pluginType;
474  std::unique_ptr< SCH_PLUGIN > m_plugin;
475  std::unique_ptr< PROPERTIES > m_properties;
476 };
477 
478 
482 bool operator==( const SYMBOL_LIB& aLibrary, const wxString& aName );
483 bool operator!=( const SYMBOL_LIB& aLibrary, const wxString& aName );
484 
485 #endif // SYMBOL_LIBRARY_H
bool m_filterPowerSymbols
true to filter (show only) power symbols
SCH_LIB_TYPE
wxDateTime timeStamp
Library save time and date.
bool IsCache() const
std::map< wxString, LIB_SYMBOL *, LibSymbolMapSort > LIB_SYMBOL_MAP
Symbol map used by symbol library object.
An abstract class from which implementation specific LINE_READERs may be derived to read single lines...
Definition: richio.h:80
Container for project specific data.
Definition: project.h:62
SYMBOL_LIB * AddLibrary(const wxString &aFileName)
Allocate and adds a symbol library to the library list.
const wxString & GetLibSource() const
LIB_SYMBOL * FindSymbol(const wxString &aName) const
Find LIB_SYMBOL by aName.
Object used to load, save, search, and otherwise manipulate symbol library files.
LIB_SYMBOL * FindLibSymbol(const LIB_ID &aLibId, const wxString &aLibraryName=wxEmptyString)
Search all libraries in the list for a symbol.
void Save(bool aSaveDocFile=true)
static void LibNamesAndPaths(PROJECT *aProject, bool doSave, wxString *aPaths, wxArrayString *aNames=nullptr)
Save or load the names of the currently configured symbol libraries (without paths).
void FindLibraryNearEntries(std::vector< LIB_SYMBOL * > &aCandidates, const wxString &aEntryName, const wxString &aLibraryName=wxEmptyString)
Search all libraries in the list for a LIB_SYMBOL using a case insensitive comparison.
void LoadFrom(const wxString &aLibName)
add a lib name to the allowed libraries
int GetModifyHash()
Return the modification hash for all libraries.
static const wxString CacheName(const wxString &aFullProjectFilename)
Return the name of the cache library after potentially fixing it from an older naming scheme.
int m_mod_hash
incremented each time library is changed.
bool operator!=(const SYMBOL_LIB &aLibrary, const wxString &aName)
int GetLibraryCount()
const wxString GetLogicalName() const
Return the logical name of the library.
An interface used to output 8 bit text in a convenient way.
Definition: richio.h:309
bool IsBuffering() const
LIB_SYMBOL * RemoveSymbol(LIB_SYMBOL *aEntry)
Safely remove aEntry from the library and return the next entry.
SCH_IO_MGR::SCH_FILE_T m_pluginType
A logical library item identifier and consists of various portions much like a URI.
Definition: lib_id.h:51
void EnableBuffering(bool aEnable=true)
Define a library symbol object.
Definition: lib_symbol.h:96
int versionMajor
Library major version number.
static int GetModifyGeneration()
KICAD_T
The set of class identification values stored in EDA_ITEM::m_structType.
Definition: typeinfo.h:77
SYMBOL_LIB(SCH_LIB_TYPE aType, const wxString &aFileName, SCH_IO_MGR::SCH_FILE_T aPluginType=SCH_IO_MGR::SCH_LEGACY)
void LoadAllLibraries(PROJECT *aProject, bool aShowProgress=true)
Load all of the project's libraries into this container, which should be cleared before calling it.
wxString header
first line of loaded library.
void AddLib(const wxString &aLibName)
add a lib name to the allowed libraries
void Create(const wxString &aFileName=wxEmptyString)
void AddSymbol(LIB_SYMBOL *aSymbol)
Add aSymbol entry to library.
boost::ptr_vector< SYMBOL_LIB > SYMBOL_LIBS_BASE
static LIB_SYMBOL * dummy()
Used to draw a dummy shape when a LIB_SYMBOL is not found in library.
Definition: sch_symbol.cpp:71
KICAD_T Type() override
std::unique_ptr< SCH_PLUGIN > m_plugin
void ClearLibList()
Clear the allowed libraries list (allows all libs)
bool IsModified() const
Base class that schematic file and library loading and saving plugins should derive from.
Definition: sch_io_mgr.h:152
int GetModHash() const
bool operator==(const SYMBOL_LIB &aLibrary, const wxString &aName)
Case insensitive library name comparison.
const wxString GetName() const
Return the file name without path or extension.
wxString GetFullFileName() const
Return the full file library name with path and extension.
void SetFileName(const wxString &aFileName)
static void IncrementModifyGeneration()
wxFileName fileName
Library file name.
LIB_SYMBOL * ReplaceSymbol(LIB_SYMBOL *aOldSymbol, LIB_SYMBOL *aNewSymbol)
Replace an existing symbol entry in the library.
void SetPluginType(SCH_IO_MGR::SCH_FILE_T aPluginType)
wxArrayString m_allowedLibs
a list of lib names to list some libraries if empty: no filter
wxArrayString GetLibraryNames(bool aSorted=true)
Return the list of symbol library file names without path and extension.
static int s_modify_generation
helper for GetModifyHash()
SYMBOL_LIB * FindLibraryByFullFileName(const wxString &aFullFileName)
A SCH_PLUGIN derivation for loading schematic files created before the new s-expression file format.
A collection of SYMBOL_LIB objects.
void GetSymbolNames(wxArrayString &aNames) const
Load a string array with the names of all the entries in this library.
static std::mutex s_generationMutex
SYMBOL_LIB * GetCacheLibrary()
void GetSymbols(std::vector< LIB_SYMBOL * > &aSymbols) const
Load a vector with all the entries in this library.
bool IsReadOnly() const
static SYMBOL_LIB * LoadLibrary(const wxString &aFileName)
Allocate and load a symbol library file.
bool isModified
Library modification status.
int versionMinor
Library minor version number.
void FilterPowerSymbols(bool aFilterEnable)
Set the filtering of power symbols.
std::unique_ptr< PROPERTIES > m_properties
Library properties.
SCH_IO_MGR::SCH_FILE_T GetPluginType() const
SCH_LIB_TYPE type
Library type indicator.
const wxArrayString & GetAllowedLibList() const
A PROJECT can hold stuff it knows nothing about, in the form of _ELEM derivatives.
Definition: project.h:73
SYMBOL_LIB * FindLibrary(const wxString &aName)
Find a symbol library by aName.
LIB_SYMBOL map sorting.
bool operator()(const wxString &aItem1, const wxString &aItem2) const
bool GetFilterPowerSymbols() const