A collection of SYMBOL_LIB objects. More...

#include <symbol_library.h>

Inheritance diagram for SYMBOL_LIBS:

Public Member Functions
KICAD_T	Type () override

	SYMBOL_LIBS ()

int	GetModifyHash ()
	Return the modification hash for all libraries. More...

SYMBOL_LIB *	AddLibrary (const wxString &aFileName)
	Allocate and adds a symbol library to the library list. More...

SYMBOL_LIB *	AddLibrary (const wxString &aFileName, SYMBOL_LIBS::iterator &aIterator)
	Insert a symbol library into the library list. More...

void	LoadAllLibraries (PROJECT *aProject, bool aShowProgress=true)
	Load all of the project's libraries into this container, which should be cleared before calling it. More...

SYMBOL_LIB *	FindLibrary (const wxString &aName)
	Find a symbol library by aName. More...

SYMBOL_LIB *	FindLibraryByFullFileName (const wxString &aFullFileName)

SYMBOL_LIB *	GetCacheLibrary ()

wxArrayString	GetLibraryNames (bool aSorted=true)
	Return the list of symbol library file names without path and extension. More...

LIB_SYMBOL *	FindLibSymbol (const LIB_ID &aLibId, const wxString &aLibraryName=wxEmptyString)
	Search all libraries in the list for a symbol. More...

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. More...

int	GetLibraryCount ()

Static Public Member Functions
static void	IncrementModifyGeneration ()

static int	GetModifyGeneration ()

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). More...

static const wxString	CacheName (const wxString &aFullProjectFilename)
	Return the name of the cache library after potentially fixing it from an older naming scheme. More...

Static Public Attributes
static int	s_modify_generation = 1
	helper for GetModifyHash() More...

static std::mutex	s_generationMutex

Detailed Description

A collection of SYMBOL_LIB objects.

It extends from PROJECT::_ELEM so it can be hung in the PROJECT. It does not use any UI calls, but rather simply throws an IO_ERROR when there is a problem.

Definition at line 195 of file symbol_library.h.

Constructor & Destructor Documentation

◆ SYMBOL_LIBS()

SYMBOL_LIBS::SYMBOL_LIBS ( )

inline

Definition at line 203 of file symbol_library.h.

     {
         IncrementModifyGeneration();
     }

References IncrementModifyGeneration().

Member Function Documentation

◆ AddLibrary() [1/2]

SYMBOL_LIB * SYMBOL_LIBS::AddLibrary ( const wxString & aFileName )

Allocate and adds a symbol library to the library list.

Parameters

aFileName is the file name object of symbol library.

Exceptions

IO_ERROR if there's any problem loading.

Definition at line 254 of file symbol_library.cpp.

 {
     SYMBOL_LIB* lib;
 
     wxFileName fn = aFileName;
     // Don't reload the library if it is already loaded.
     lib = FindLibrary( fn.GetName() );
 
     if( lib )
         return lib;
 
     try
     {
         lib = SYMBOL_LIB::LoadLibrary( aFileName );
         push_back( lib );
 
         return lib;
     }
     catch( ... )
     {
         return nullptr;
     }
 }

References FindLibrary(), and SYMBOL_LIB::LoadLibrary().

Referenced by LoadAllLibraries().

◆ AddLibrary() [2/2]

SYMBOL_LIB * SYMBOL_LIBS::AddLibrary	(	const wxString &	aFileName,
		SYMBOL_LIBS::iterator &	aIterator
	)

Insert a symbol library into the library list.

Parameters

aFileName	is the file name object of symbol library.
aIterator	is an iterator to insert library in front of.

Returns: the new SYMBOL_LIB, which remains owned by this SYMBOL_LIBS container.

Exceptions

IO_ERROR if there's any problem loading.

Definition at line 279 of file symbol_library.cpp.

 {
     // Don't reload the library if it is already loaded.
     wxFileName fn( aFileName );
     SYMBOL_LIB* lib = FindLibrary( fn.GetName() );
 
     if( lib )
         return lib;
 
     try
     {
         lib = SYMBOL_LIB::LoadLibrary( aFileName );
 
         if( aIterator >= begin() && aIterator < end() )
             insert( aIterator, lib );
         else
             push_back( lib );
 
         return lib;
     }
     catch( ... )
     {
         return nullptr;
     }
 }

References FindLibrary(), and SYMBOL_LIB::LoadLibrary().

◆ CacheName()

const wxString SYMBOL_LIBS::CacheName ( const wxString & aFullProjectFilename )

static

Return the name of the cache library after potentially fixing it from an older naming scheme.

That is, the old file is renamed if needed.

Parameters

aFullProjectFilename is the *.pro filename with absolute path.

Definition at line 458 of file symbol_library.cpp.

 {
     wxFileName  name = aFullProjectFilename;
 
     name.SetName( name.GetName() + "-cache" );
     name.SetExt( LegacySymbolLibFileExtension );
 
     if( name.FileExists() )
         return name.GetFullPath();
 
     return wxEmptyString;
 }

References LegacySymbolLibFileExtension, and name.

Referenced by LoadAllLibraries().

◆ FindLibrary()

SYMBOL_LIB * SYMBOL_LIBS::FindLibrary ( const wxString & aName )

Find a symbol library by aName.

Parameters

aName is the library file name without path or extension to find.

Returns: the symbol library if found, otherwise NULL.

Definition at line 306 of file symbol_library.cpp.

 {
     for( SYMBOL_LIBS::iterator it = begin();  it!=end();  ++it )
     {
         if( it->GetName() == aName )
             return &*it;
     }
 
     return nullptr;
 }

Referenced by AddLibrary().

◆ FindLibraryByFullFileName()

SYMBOL_LIB * SYMBOL_LIBS::FindLibraryByFullFileName ( const wxString & aFullFileName )

Definition at line 330 of file symbol_library.cpp.

 {
     for( SYMBOL_LIBS::iterator it = begin();  it!=end();  ++it )
     {
         if( it->GetFullFileName() == aFullFileName )
             return &*it;
     }
 
     return nullptr;
 }

◆ FindLibraryNearEntries()

void SYMBOL_LIBS::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.

Helper function used in dialog to find all candidates. During a long time, eeschema was using a case insensitive search. Therefore, for old schematics (<= 2013), or libs, for some symbols, the chip name (name of alias in lib) can be broken. This function can be used to display a list of candidates, in symbol properties dialog.

Parameters

aEntryName	is the name of entries to search for (case insensitive).
aLibraryName	is the name of the library to search.
aCandidates	is a std::vector to store candidates.

Definition at line 385 of file symbol_library.cpp.

 {
     for( SYMBOL_LIB& lib : *this )
     {
         if( !aLibraryName.IsEmpty() && lib.GetName() != aLibraryName )
             continue;
 
         wxArrayString partNames;
 
         lib.GetSymbolNames( partNames );
 
         if( partNames.IsEmpty() )
             continue;
 
         for( size_t i = 0;  i < partNames.size();  i++ )
         {
             if( partNames[i].CmpNoCase( aEntryName ) == 0 )
                 aCandidates.push_back( lib.FindSymbol( partNames[i] ) );
         }
     }
 }

References SYMBOL_LIB::FindSymbol(), SYMBOL_LIB::GetName(), and SYMBOL_LIB::GetSymbolNames().

◆ FindLibSymbol()

LIB_SYMBOL * SYMBOL_LIBS::FindLibSymbol	(	const LIB_ID &	aLibId,
		const wxString &	aLibraryName = `wxEmptyString`
	)

Search all libraries in the list for a symbol.

A symbol object will always be returned. If the entry found is an alias. The root symbol will be found and returned.

Parameters

aLibId	is the LIB_ID of the symbol to search for.
aLibraryName	is the name of the library to search for symbol.

Returns: the symbol object if found, otherwise NULL.

Definition at line 366 of file symbol_library.cpp.

 {
     LIB_SYMBOL* part = nullptr;
 
     for( SYMBOL_LIB& lib : *this )
     {
         if( !aLibraryName.IsEmpty() && lib.GetName() != aLibraryName )
             continue;
 
         part = lib.FindSymbol( aLibId.GetLibItemName().wx_str() );
 
         if( part )
             break;
     }
 
     return part;
 }

References SYMBOL_LIB::FindSymbol(), LIB_ID::GetLibItemName(), SYMBOL_LIB::GetName(), and UTF8::wx_str().

◆ GetCacheLibrary()

SYMBOL_LIB * SYMBOL_LIBS::GetCacheLibrary ( )

Definition at line 318 of file symbol_library.cpp.

 {
     for( SYMBOL_LIBS::iterator it = begin();  it!=end();  ++it )
     {
         if( it->IsCache() )
             return &*it;
     }
 
     return nullptr;
 }

◆ GetLibraryCount()

int SYMBOL_LIBS::GetLibraryCount ( )

inline

Definition at line 313 of file symbol_library.h.

313 { return size(); }

Referenced by SCH_EDIT_FRAME::OpenProjectFiles(), and SCH_SCREEN::UpdateSymbolLinks().

◆ GetLibraryNames()

wxArrayString SYMBOL_LIBS::GetLibraryNames ( bool aSorted = true )

Return the list of symbol library file names without path and extension.

Parameters

aSorted sort the list of name if true. Otherwise use the library load order.

Returns: the list of library names.

Definition at line 342 of file symbol_library.cpp.

 {
     wxArrayString cacheNames;
     wxArrayString names;
 
     for( SYMBOL_LIB& lib : *this )
     {
         if( lib.IsCache() && aSorted )
             cacheNames.Add( lib.GetName() );
         else
             names.Add( lib.GetName() );
     }
 
     // Even sorted, the cache library is always at the end of the list.
     if( aSorted )
         names.Sort();
 
     for( unsigned int i = 0; i<cacheNames.Count(); i++ )
         names.Add( cacheNames.Item( i ) );
 
     return names;
 }

References SYMBOL_LIB::GetName(), and SYMBOL_LIB::IsCache().

◆ GetModifyGeneration()

static int SYMBOL_LIBS::GetModifyGeneration ( )

inlinestatic

Definition at line 214 of file symbol_library.h.

     {
         std::lock_guard<std::mutex> mut( SYMBOL_LIBS::s_generationMutex );
         return SYMBOL_LIBS::s_modify_generation;
     }

References s_generationMutex, and s_modify_generation.

Referenced by GetModifyHash().

◆ GetModifyHash()

int SYMBOL_LIBS::GetModifyHash ( )

Return the modification hash for all libraries.

The value returned changes on every library modification.

Definition at line 414 of file symbol_library.cpp.

 {
     int hash = 0;
 
     for( SYMBOL_LIBS::const_iterator it = begin();  it != end();  ++it )
     {
         hash += it->GetModHash();
     }
 
     // Rebuilding the cache (m_cache) does not change the GetModHash() value,
     // but changes SYMBOL_LIBS::s_modify_generation.
     // Take this change in account:
     hash += SYMBOL_LIBS::GetModifyGeneration();
 
     return hash;
 }

References GetModifyGeneration().

◆ IncrementModifyGeneration()

static void SYMBOL_LIBS::IncrementModifyGeneration ( )

inlinestatic

Definition at line 208 of file symbol_library.h.

     {
         std::lock_guard<std::mutex> mut( SYMBOL_LIBS::s_generationMutex );
         ++SYMBOL_LIBS::s_modify_generation;
     }

References s_generationMutex, and s_modify_generation.

Referenced by SCH_SEXPR_PLUGIN::cacheLib(), SCH_LEGACY_PLUGIN::cacheLib(), and SYMBOL_LIBS().

◆ LibNamesAndPaths()

void SYMBOL_LIBS::LibNamesAndPaths	(	PROJECT *	aProject,
		bool	doSave,
		wxString *	aPaths,
		wxArrayString *	aNames = `nullptr`
	)

static

Save or load the names of the currently configured symbol libraries (without paths).

Definition at line 432 of file symbol_library.cpp.

 {
     wxCHECK_RET( aProject, "Null PROJECT in LibNamesAndPaths" );
 
     PROJECT_FILE& project = aProject->GetProjectFile();
 
     if( doSave )
     {
         if( aPaths )
             project.m_LegacyLibDir = *aPaths;
 
         if( aNames )
             project.m_LegacyLibNames = *aNames;
     }
     else
     {
         if( aPaths )
             *aPaths = project.m_LegacyLibDir;
 
         if( aNames )
             *aNames = project.m_LegacyLibNames;
     }
 }

References PROJECT::GetProjectFile(), and project.

Referenced by LoadAllLibraries(), DIALOG_SYMBOL_REMAP::OnRemapSymbols(), SCH_EDIT_FRAME::OpenProjectFiles(), and LEGACY_RESCUER::WriteRescueLibrary().

◆ LoadAllLibraries()

void SYMBOL_LIBS::LoadAllLibraries	(	PROJECT *	aProject,
		bool	aShowProgress = `true`
	)

Load all of the project's libraries into this container, which should be cleared before calling it.

Note: This method is only to be used when loading legacy projects. All further symbol library access should be done via the symbol library table.

Definition at line 472 of file symbol_library.cpp.

 {
     wxString        filename;
     wxString        libs_not_found;
     SEARCH_STACK*   lib_search = aProject->SchSearchS();
 
 #if defined(DEBUG) && 0
     lib_search->Show( __func__ );
 #endif
 
     wxArrayString   lib_names;
 
     LibNamesAndPaths( aProject, false, nullptr, &lib_names );
 
     // Post symbol library table, this should be empty.  Only the cache library should get loaded.
     if( !lib_names.empty() )
     {
         APP_PROGRESS_DIALOG lib_dialog( _( "Loading Symbol Libraries" ),
                                         wxEmptyString,
                                         lib_names.GetCount(),
                                         nullptr,
                                         false,
                                         wxPD_APP_MODAL );
 
         if( aShowProgress )
         {
             lib_dialog.Show();
         }
 
         wxString progress_message;
 
         for( unsigned i = 0; i < lib_names.GetCount();  ++i )
         {
             if( aShowProgress )
             {
                 lib_dialog.Update( i, wxString::Format( _( "Loading %s..." ), lib_names[i] ) );
             }
 
             // lib_names[] does not store the file extension. Set it.
             // Remember lib_names[i] can contain a '.' in name, so using a wxFileName
             // before adding the extension can create incorrect full filename
             wxString fullname = lib_names[i] + "." + LegacySymbolLibFileExtension;
             // Now the full name is set, we can use a wxFileName.
             wxFileName fn( fullname );
 
             // Skip if the file name is not valid..
             if( !fn.IsOk() )
                 continue;
 
             if( !fn.FileExists() )
             {
                 filename = lib_search->FindValidPath( fn.GetFullPath() );
 
                 if( !filename )
                 {
                     libs_not_found += fn.GetFullPath();
                     libs_not_found += '\n';
                     continue;
                 }
             }
             else
             {   // ensure the lib filename has a absolute path.
                 // If the lib has no absolute path, and is found in the cwd by fn.FileExists(),
                 // make a full absolute path, to avoid issues with load library functions which
                 // expects an absolute path.
                 if( !fn.IsAbsolute() )
                     fn.MakeAbsolute();
 
                 filename = fn.GetFullPath();
             }
 
             try
             {
                 AddLibrary( filename );
             }
             catch( const IO_ERROR& ioe )
             {
                 wxString msg;
                 msg.Printf( _( "Symbol library '%s' failed to load." ), filename );
 
                 wxLogError( msg + wxS( "\n" ) + ioe.What() );
             }
         }
     }
 
     // add the special cache library.
     wxString cache_name = CacheName( aProject->GetProjectFullName() );
     SYMBOL_LIB* cache_lib;
 
     if( !aProject->IsNullProject() && !cache_name.IsEmpty() )
     {
         try
         {
             cache_lib = AddLibrary( cache_name );
 
             if( cache_lib )
                 cache_lib->SetCache();
         }
         catch( const IO_ERROR& ioe )
         {
             wxString msg = wxString::Format( _( "Error loading symbol library '%s'." )
                                              + wxS( "\n%s" ),
                                              cache_name,
                                              ioe.What() );
 
             THROW_IO_ERROR( msg );
         }
     }
 
     // Print the libraries not found
     if( !libs_not_found.IsEmpty() )
     {
         // Use a different exception type so catch()er can route to proper use
         // of the HTML_MESSAGE_BOX.
         THROW_PARSE_ERROR( wxEmptyString, __func__, TO_UTF8( libs_not_found ), 0, 0 );
     }
 }