KiCad PCB EDA Suite
SYMBOL_LIB Class Reference

Object used to load, save, search, and otherwise manipulate symbol library files. More...

#include <symbol_library.h>

Public Member Functions

 SYMBOL_LIB (SCH_LIB_TYPE aType, const wxString &aFileName, SCH_IO_MGR::SCH_FILE_T aPluginType=SCH_IO_MGR::SCH_LEGACY)
 
 ~SYMBOL_LIB ()
 
int GetModHash () const
 
SCH_IO_MGR::SCH_FILE_T GetPluginType () const
 
void SetPluginType (SCH_IO_MGR::SCH_FILE_T aPluginType)
 
void Create (const wxString &aFileName=wxEmptyString)
 
void SetFileName (const wxString &aFileName)
 
bool IsModified () const
 
bool IsCache () const
 
void SetCache ()
 
bool IsBuffering () const
 
void EnableBuffering (bool aEnable=true)
 
void Save (bool aSaveDocFile=true)
 
bool IsReadOnly () const
 
void GetSymbolNames (wxArrayString &aNames) const
 Load a string array with the names of all the entries in this library. More...
 
void GetSymbols (std::vector< LIB_SYMBOL * > &aSymbols) const
 Load a vector with all the entries in this library. More...
 
LIB_SYMBOLFindSymbol (const wxString &aName) const
 Find LIB_SYMBOL by aName. More...
 
LIB_SYMBOLFindSymbol (const LIB_ID &aLibId) const
 
void AddSymbol (LIB_SYMBOL *aSymbol)
 Add aSymbol entry to library. More...
 
LIB_SYMBOLRemoveSymbol (LIB_SYMBOL *aEntry)
 Safely remove aEntry from the library and return the next entry. More...
 
LIB_SYMBOLReplaceSymbol (LIB_SYMBOL *aOldSymbol, LIB_SYMBOL *aNewSymbol)
 Replace an existing symbol entry in the library. More...
 
const wxString GetName () const
 Return the file name without path or extension. More...
 
wxString GetFullFileName () const
 Return the full file library name with path and extension. More...
 
const wxString GetLogicalName () const
 Return the logical name of the library. More...
 

Static Public Member Functions

static SYMBOL_LIBLoadLibrary (const wxString &aFileName)
 Allocate and load a symbol library file. More...
 

Private Attributes

SCH_LIB_TYPE type
 Library type indicator. More...
 
wxFileName fileName
 Library file name. More...
 
wxDateTime timeStamp
 Library save time and date. More...
 
int versionMajor
 Library major version number. More...
 
int versionMinor
 Library minor version number. More...
 
wxString header
 first line of loaded library. More...
 
bool isModified
 Library modification status. More...
 
int m_mod_hash
 incremented each time library is changed. More...
 
SCH_IO_MGR::SCH_FILE_T m_pluginType
 
std::unique_ptr< SCH_PLUGINm_plugin
 
std::unique_ptr< PROPERTIESm_properties
 Library properties. More...
 

Detailed Description

Object used to load, save, search, and otherwise manipulate symbol library files.

Warning
This code is obsolete with the exception of the cache library. All other symbol library I/O is managed by the SCH_IO_MGR object.

Definition at line 323 of file symbol_library.h.

Constructor & Destructor Documentation

◆ SYMBOL_LIB()

SYMBOL_LIB::SYMBOL_LIB ( SCH_LIB_TYPE  aType,
const wxString &  aFileName,
SCH_IO_MGR::SCH_FILE_T  aPluginType = SCH_IO_MGR::SCH_LEGACY 
)

Definition at line 47 of file symbol_library.cpp.

48  :
49  // start @ != 0 so each additional library added
50  // is immediately detectable, zero would not be.
52  m_pluginType( aPluginType )
53 {
54  type = aType;
55  isModified = false;
56  timeStamp = 0;
57  timeStamp = wxDateTime::Now();
58  versionMajor = 0; // Will be updated after reading the lib file
59  versionMinor = 0; // Will be updated after reading the lib file
60 
61  fileName = aFileName;
62 
63  if( !fileName.IsOk() )
64  fileName = "unnamed.lib";
65 
66  m_plugin.reset( SCH_IO_MGR::FindPlugin( m_pluginType ) );
67  m_properties = std::make_unique<PROPERTIES>();
68 }
wxDateTime timeStamp
Library save time and date.
int m_mod_hash
incremented each time library is changed.
SCH_IO_MGR::SCH_FILE_T m_pluginType
int versionMajor
Library major version number.
static int GetModifyGeneration()
std::unique_ptr< SCH_PLUGIN > m_plugin
wxFileName fileName
Library file name.
bool isModified
Library modification status.
int versionMinor
Library minor version number.
std::unique_ptr< PROPERTIES > m_properties
Library properties.
SCH_LIB_TYPE type
Library type indicator.

References fileName, isModified, m_plugin, m_pluginType, m_properties, timeStamp, type, versionMajor, and versionMinor.

◆ ~SYMBOL_LIB()

SYMBOL_LIB::~SYMBOL_LIB ( )

Definition at line 71 of file symbol_library.cpp.

72 {
73 }

Member Function Documentation

◆ AddSymbol()

void SYMBOL_LIB::AddSymbol ( LIB_SYMBOL aSymbol)

Add aSymbol entry to library.

Note
A LIB_SYMBOL can have an alias list so these alias will be added in library. and the any existing duplicate aliases will be removed from the library.
Parameters
aSymbolis the symbol to add, caller retains ownership, a clone is added.

Definition at line 177 of file symbol_library.cpp.

178 {
179  // add a clone, not the caller's copy, the plugin take ownership of the new symbol.
180  m_plugin->SaveSymbol( fileName.GetFullPath(),
181  new LIB_SYMBOL( *aSymbol->SharedPtr().get(), this ),
182  m_properties.get() );
183 
184  // If we are not buffering, the library file is updated immediately when the plugin
185  // SaveSymbol() function is called.
186  if( IsBuffering() )
187  isModified = true;
188 
189  ++m_mod_hash;
190 }
LIB_SYMBOL_SPTR SharedPtr() const
Definition: lib_symbol.h:107
int m_mod_hash
incremented each time library is changed.
bool IsBuffering() const
Define a library symbol object.
Definition: lib_symbol.h:96
std::unique_ptr< SCH_PLUGIN > m_plugin
wxFileName fileName
Library file name.
bool isModified
Library modification status.
std::unique_ptr< PROPERTIES > m_properties
Library properties.

References fileName, IsBuffering(), isModified, m_mod_hash, m_plugin, m_properties, and LIB_SYMBOL::SharedPtr().

◆ Create()

void SYMBOL_LIB::Create ( const wxString &  aFileName = wxEmptyString)

Definition at line 91 of file symbol_library.cpp.

92 {
93  wxString tmpFileName = fileName.GetFullPath();
94 
95  if( !aFileName.IsEmpty() )
96  tmpFileName = aFileName;
97 
98  m_plugin->CreateSymbolLib( tmpFileName, m_properties.get() );
99 }
std::unique_ptr< SCH_PLUGIN > m_plugin
wxFileName fileName
Library file name.
std::unique_ptr< PROPERTIES > m_properties
Library properties.

References fileName, m_plugin, and m_properties.

◆ EnableBuffering()

void SYMBOL_LIB::EnableBuffering ( bool  aEnable = true)

Definition at line 130 of file symbol_library.cpp.

131 {
132  if( aEnable )
133  (*m_properties)[ SCH_LEGACY_PLUGIN::PropBuffering ] = "";
134  else
136 }
std::unique_ptr< PROPERTIES > m_properties
Library properties.
static const char * PropBuffering
The property used internally by the plugin to enable cache buffering which prevents the library file ...

References m_properties, and SCH_LEGACY_PLUGIN::PropBuffering.

◆ FindSymbol() [1/2]

LIB_SYMBOL * SYMBOL_LIB::FindSymbol ( const wxString &  aName) const

Find LIB_SYMBOL by aName.

Parameters
aNameis the name of the symbol, case sensitive.
Returns
LIB_SYMBOL pointer symbol if found, else NULL.

Definition at line 157 of file symbol_library.cpp.

158 {
159  LIB_SYMBOL* symbol = m_plugin->LoadSymbol( fileName.GetFullPath(), aName, m_properties.get() );
160 
161  // Set the library to this even though technically the legacy cache plugin owns the
162  // symbols. This allows the symbol library table conversion tool to determine the
163  // correct library where the symbol was found.
164  if( symbol && !symbol->GetLib() )
165  symbol->SetLib( const_cast<SYMBOL_LIB*>( this ) );
166 
167  return symbol;
168 }
void SetLib(SYMBOL_LIB *aLibrary)
Definition: lib_symbol.h:177
Define a library symbol object.
Definition: lib_symbol.h:96
SYMBOL_LIB * GetLib() const
Definition: lib_symbol.h:176
std::unique_ptr< SCH_PLUGIN > m_plugin
wxFileName fileName
Library file name.
std::unique_ptr< PROPERTIES > m_properties
Library properties.

References fileName, LIB_SYMBOL::GetLib(), m_plugin, m_properties, and LIB_SYMBOL::SetLib().

Referenced by SYMBOL_LIBS::FindLibraryNearEntries(), SYMBOL_LIBS::FindLibSymbol(), FindSymbol(), SchGetLibSymbol(), and SCH_SCREEN::UpdateSymbolLinks().

◆ FindSymbol() [2/2]

LIB_SYMBOL * SYMBOL_LIB::FindSymbol ( const LIB_ID aLibId) const

Definition at line 171 of file symbol_library.cpp.

172 {
173  return FindSymbol( aLibId.Format().wx_str() );
174 }
LIB_SYMBOL * FindSymbol(const wxString &aName) const
Find LIB_SYMBOL by aName.
UTF8 Format() const
Definition: lib_id.cpp:116
wxString wx_str() const
Definition: utf8.cpp:46

References FindSymbol(), LIB_ID::Format(), and UTF8::wx_str().

◆ GetFullFileName()

wxString SYMBOL_LIB::GetFullFileName ( ) const
inline

Return the full file library name with path and extension.

Returns
the full library file name with path and extension.

Definition at line 433 of file symbol_library.h.

433 { return fileName.GetFullPath(); }
wxFileName fileName
Library file name.

References fileName.

◆ GetLogicalName()

const wxString SYMBOL_LIB::GetLogicalName ( ) const
inline

Return the logical name of the library.

Returns
The logical name of this library.

Definition at line 440 of file symbol_library.h.

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  }
wxFileName fileName
Library file name.

References fileName.

◆ GetModHash()

int SYMBOL_LIB::GetModHash ( ) const
inline
Returns
a magic number that changes if the library has changed

Definition at line 333 of file symbol_library.h.

333 { return m_mod_hash; }
int m_mod_hash
incremented each time library is changed.

References m_mod_hash.

◆ GetName()

const wxString SYMBOL_LIB::GetName ( void  ) const
inline

Return the file name without path or extension.

Returns
the name of library file.

Definition at line 426 of file symbol_library.h.

426 { return fileName.GetName(); }
wxFileName fileName
Library file name.

References fileName.

Referenced by SYMBOL_LIBS::FindLibraryNearEntries(), SYMBOL_LIBS::FindLibSymbol(), LIB_SYMBOL::GetLibraryName(), and SYMBOL_LIBS::GetLibraryNames().

◆ GetPluginType()

SCH_IO_MGR::SCH_FILE_T SYMBOL_LIB::GetPluginType ( ) const
inline

Definition at line 335 of file symbol_library.h.

335 { return m_pluginType; }
SCH_IO_MGR::SCH_FILE_T m_pluginType

References m_pluginType.

◆ GetSymbolNames()

void SYMBOL_LIB::GetSymbolNames ( wxArrayString &  aNames) const

Load a string array with the names of all the entries in this library.

Parameters
aNamesis the array to place entry names into.

Definition at line 139 of file symbol_library.cpp.

140 {
141  m_plugin->EnumerateSymbolLib( aNames, fileName.GetFullPath(), m_properties.get() );
142 
143  aNames.Sort();
144 }
std::unique_ptr< SCH_PLUGIN > m_plugin
wxFileName fileName
Library file name.
std::unique_ptr< PROPERTIES > m_properties
Library properties.

References fileName, m_plugin, and m_properties.

Referenced by SYMBOL_LIBS::FindLibraryNearEntries().

◆ GetSymbols()

void SYMBOL_LIB::GetSymbols ( std::vector< LIB_SYMBOL * > &  aSymbols) const

Load a vector with all the entries in this library.

Parameters
aSymbolsis a vector to receive the aliases.

Definition at line 147 of file symbol_library.cpp.

148 {
149  m_plugin->EnumerateSymbolLib( aSymbols, fileName.GetFullPath(), m_properties.get() );
150 
151  std::sort( aSymbols.begin(), aSymbols.end(),
152  [](LIB_SYMBOL *lhs, LIB_SYMBOL *rhs) -> bool
153  { return lhs->GetName() < rhs->GetName(); });
154 }
wxString GetName() const override
Definition: lib_symbol.h:133
Define a library symbol object.
Definition: lib_symbol.h:96
std::unique_ptr< SCH_PLUGIN > m_plugin
wxFileName fileName
Library file name.
std::unique_ptr< PROPERTIES > m_properties
Library properties.

References fileName, LIB_SYMBOL::GetName(), m_plugin, and m_properties.

Referenced by LEGACY_RESCUER::OpenRescueLibrary().

◆ IsBuffering()

bool SYMBOL_LIB::IsBuffering ( ) const

Definition at line 124 of file symbol_library.cpp.

125 {
127 }
std::unique_ptr< PROPERTIES > m_properties
Library properties.
static const char * PropBuffering
The property used internally by the plugin to enable cache buffering which prevents the library file ...

References m_properties, and SCH_LEGACY_PLUGIN::PropBuffering.

Referenced by AddSymbol(), RemoveSymbol(), and ReplaceSymbol().

◆ IsCache()

bool SYMBOL_LIB::IsCache ( ) const

Definition at line 112 of file symbol_library.cpp.

113 {
115 }
static const char * PropNoDocFile
The property used internally by the plugin to disable writing the library documentation (....
std::unique_ptr< PROPERTIES > m_properties
Library properties.

References m_properties, and SCH_LEGACY_PLUGIN::PropNoDocFile.

Referenced by SYMBOL_LIBS::GetLibraryNames(), SchGetLibSymbol(), and SCH_SCREEN::UpdateSymbolLinks().

◆ IsModified()

bool SYMBOL_LIB::IsModified ( ) const
inline

Definition at line 343 of file symbol_library.h.

344  {
345  return isModified;
346  }
bool isModified
Library modification status.

References isModified.

◆ IsReadOnly()

bool SYMBOL_LIB::IsReadOnly ( ) const
inline
Returns
true if current user does not have write access to the library file.

Definition at line 361 of file symbol_library.h.

361 { return !fileName.IsFileWritable(); }
wxFileName fileName
Library file name.

References fileName.

◆ LoadLibrary()

SYMBOL_LIB * SYMBOL_LIB::LoadLibrary ( const wxString &  aFileName)
static

Allocate and load a symbol library file.

Parameters
aFileNameis the file name of the symbol library to load.
Returns
SYMBOL_LIB* is the allocated and loaded SYMBOL_LIB, which is owned by the caller.
Exceptions
IO_ERRORif there's any problem loading the library.

Definition at line 230 of file symbol_library.cpp.

231 {
232  std::unique_ptr<SYMBOL_LIB> lib = std::make_unique<SYMBOL_LIB>( SCH_LIB_TYPE::LT_EESCHEMA,
233  aFileName );
234 
235  std::vector<LIB_SYMBOL*> parts;
236  // This loads the library.
237  lib->GetSymbols( parts );
238 
239  // Now, set the LIB_SYMBOL m_library member but it will only be used
240  // when loading legacy libraries in the future. Once the symbols in the
241  // schematic have a full #LIB_ID, this will not get called.
242  for( size_t ii = 0; ii < parts.size(); ii++ )
243  {
244  LIB_SYMBOL* part = parts[ii];
245 
246  part->SetLib( lib.get() );
247  }
248 
249  SYMBOL_LIB* ret = lib.release();
250  return ret;
251 }
Object used to load, save, search, and otherwise manipulate symbol library files.
void SetLib(SYMBOL_LIB *aLibrary)
Definition: lib_symbol.h:177
Define a library symbol object.
Definition: lib_symbol.h:96

References LT_EESCHEMA, and LIB_SYMBOL::SetLib().

Referenced by SYMBOL_LIBS::AddLibrary().

◆ RemoveSymbol()

LIB_SYMBOL * SYMBOL_LIB::RemoveSymbol ( LIB_SYMBOL aEntry)

Safely remove aEntry from the library and return the next entry.

The next entry returned depends on the entry being removed. If the entry being remove also removes the symbol, then the next entry from the list is returned. If the entry being used only removes an alias from a symbol, then the next alias of the symbol is returned.

Parameters
aEntryis the entry to remove from library.
Returns
The next entry in the library or NULL if the library is empty.

Definition at line 193 of file symbol_library.cpp.

194 {
195  wxCHECK_MSG( aEntry != nullptr, nullptr, "NULL pointer cannot be removed from library." );
196 
197  m_plugin->DeleteSymbol( fileName.GetFullPath(), aEntry->GetName(), m_properties.get() );
198 
199  // If we are not buffering, the library file is updated immediately when the plugin
200  // SaveSymbol() function is called.
201  if( IsBuffering() )
202  isModified = true;
203 
204  ++m_mod_hash;
205  return nullptr;
206 }
wxString GetName() const override
Definition: lib_symbol.h:133
int m_mod_hash
incremented each time library is changed.
bool IsBuffering() const
std::unique_ptr< SCH_PLUGIN > m_plugin
wxFileName fileName
Library file name.
bool isModified
Library modification status.
std::unique_ptr< PROPERTIES > m_properties
Library properties.

References fileName, LIB_SYMBOL::GetName(), IsBuffering(), isModified, m_mod_hash, m_plugin, and m_properties.

◆ ReplaceSymbol()

LIB_SYMBOL * SYMBOL_LIB::ReplaceSymbol ( LIB_SYMBOL aOldSymbol,
LIB_SYMBOL aNewSymbol 
)

Replace an existing symbol entry in the library.

Note
A symbol can have an alias list so these aliases will be added in library and previously existing alias removed.
Parameters
aOldSymbolis the symbol to replace.
aNewSymbolis the new symbol.

Definition at line 209 of file symbol_library.cpp.

210 {
211  wxASSERT( aOldSymbol != nullptr );
212  wxASSERT( aNewSymbol != nullptr );
213 
214  m_plugin->DeleteSymbol( fileName.GetFullPath(), aOldSymbol->GetName(), m_properties.get() );
215 
216  LIB_SYMBOL* my_part = new LIB_SYMBOL( *aNewSymbol, this );
217 
218  m_plugin->SaveSymbol( fileName.GetFullPath(), my_part, m_properties.get() );
219 
220  // If we are not buffering, the library file is updated immediately when the plugin
221  // SaveSymbol() function is called.
222  if( IsBuffering() )
223  isModified = true;
224 
225  ++m_mod_hash;
226  return my_part;
227 }
wxString GetName() const override
Definition: lib_symbol.h:133
int m_mod_hash
incremented each time library is changed.
bool IsBuffering() const
Define a library symbol object.
Definition: lib_symbol.h:96
std::unique_ptr< SCH_PLUGIN > m_plugin
wxFileName fileName
Library file name.
bool isModified
Library modification status.
std::unique_ptr< PROPERTIES > m_properties
Library properties.

References fileName, LIB_SYMBOL::GetName(), IsBuffering(), isModified, m_mod_hash, m_plugin, and m_properties.

◆ Save()

void SYMBOL_LIB::Save ( bool  aSaveDocFile = true)

Definition at line 76 of file symbol_library.cpp.

77 {
78  wxCHECK_RET( m_plugin != nullptr, wxString::Format( "no plugin defined for library `%s`.",
79  fileName.GetFullPath() ) );
80 
81  PROPERTIES props;
82 
83  if( !aSaveDocFile )
85 
86  m_plugin->SaveLibrary( fileName.GetFullPath(), &props );
87  isModified = false;
88 }
A name/value tuple with unique names and optional values.
Definition: properties.h:33
std::unique_ptr< SCH_PLUGIN > m_plugin
wxFileName fileName
Library file name.
static const char * PropNoDocFile
The property used internally by the plugin to disable writing the library documentation (....
void Format(OUTPUTFORMATTER *out, int aNestLevel, int aCtl, const CPTREE &aTree)
Output a PTREE into s-expression format via an OUTPUTFORMATTER derivative.
Definition: ptree.cpp:200
bool isModified
Library modification status.

References fileName, Format(), isModified, m_plugin, and SCH_LEGACY_PLUGIN::PropNoDocFile.

◆ SetCache()

void SYMBOL_LIB::SetCache ( )

Definition at line 118 of file symbol_library.cpp.

119 {
120  (*m_properties)[ SCH_LEGACY_PLUGIN::PropNoDocFile ] = "";
121 }
static const char * PropNoDocFile
The property used internally by the plugin to disable writing the library documentation (....

References SCH_LEGACY_PLUGIN::PropNoDocFile.

◆ SetFileName()

void SYMBOL_LIB::SetFileName ( const wxString &  aFileName)
inline

Definition at line 341 of file symbol_library.h.

341 { fileName = aFileName; }
wxFileName fileName
Library file name.

References fileName.

◆ SetPluginType()

void SYMBOL_LIB::SetPluginType ( SCH_IO_MGR::SCH_FILE_T  aPluginType)

Definition at line 102 of file symbol_library.cpp.

103 {
104  if( m_pluginType != aPluginType )
105  {
106  m_pluginType = aPluginType;
107  m_plugin.reset( SCH_IO_MGR::FindPlugin( m_pluginType ) );
108  }
109 }
SCH_IO_MGR::SCH_FILE_T m_pluginType
std::unique_ptr< SCH_PLUGIN > m_plugin

References m_plugin, and m_pluginType.

Member Data Documentation

◆ fileName

wxFileName SYMBOL_LIB::fileName
private

◆ header

wxString SYMBOL_LIB::header
private

first line of loaded library.

Definition at line 469 of file symbol_library.h.

◆ isModified

bool SYMBOL_LIB::isModified
private

Library modification status.

Definition at line 470 of file symbol_library.h.

Referenced by AddSymbol(), IsModified(), RemoveSymbol(), ReplaceSymbol(), Save(), and SYMBOL_LIB().

◆ m_mod_hash

int SYMBOL_LIB::m_mod_hash
private

incremented each time library is changed.

Definition at line 471 of file symbol_library.h.

Referenced by AddSymbol(), GetModHash(), RemoveSymbol(), and ReplaceSymbol().

◆ m_plugin

std::unique_ptr< SCH_PLUGIN > SYMBOL_LIB::m_plugin
private

◆ m_pluginType

SCH_IO_MGR::SCH_FILE_T SYMBOL_LIB::m_pluginType
private

Definition at line 473 of file symbol_library.h.

Referenced by GetPluginType(), SetPluginType(), and SYMBOL_LIB().

◆ m_properties

std::unique_ptr< PROPERTIES > SYMBOL_LIB::m_properties
private

◆ timeStamp

wxDateTime SYMBOL_LIB::timeStamp
private

Library save time and date.

Definition at line 466 of file symbol_library.h.

Referenced by SYMBOL_LIB().

◆ type

SCH_LIB_TYPE SYMBOL_LIB::type
private

Library type indicator.

Definition at line 464 of file symbol_library.h.

Referenced by SYMBOL_LIB().

◆ versionMajor

int SYMBOL_LIB::versionMajor
private

Library major version number.

Definition at line 467 of file symbol_library.h.

Referenced by SYMBOL_LIB().

◆ versionMinor

int SYMBOL_LIB::versionMinor
private

Library minor version number.

Definition at line 468 of file symbol_library.h.

Referenced by SYMBOL_LIB().


The documentation for this class was generated from the following files: