/* * This program source code file is part of KiCad, a free EDA CAD application. * * Copyright (C) 2010-2012 SoftPLC Corporation, Dick Hollenbeck * Copyright (C) 2012 Wayne Stambaugh * Copyright (C) 2012-2021 KiCad Developers, see change_log.txt for contributors. * * This program is free software; you can redistribute it and/or * modify it under the terms of the GNU General Public License * as published by the Free Software Foundation; either version 2 * of the License, or (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License * along with this program; if not, you may find one here: * http://www.gnu.org/licenses/old-licenses/gpl-2.0.html * or you may search the http://www.gnu.org website for the version 2 license, * or you may write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA */ #ifndef _LIB_TABLE_BASE_H_ #define _LIB_TABLE_BASE_H_ #include #include #include #include #include #include #include #include #include class OUTPUTFORMATTER; class LIB_TABLE_LEXER; class LIB_ID; class LIB_TABLE_ROW; class LIB_TABLE_GRID; class LIB_TABLE; class IO_ERROR; class wxWindow; typedef boost::ptr_vector< LIB_TABLE_ROW > LIB_TABLE_ROWS; typedef LIB_TABLE_ROWS::iterator LIB_TABLE_ROWS_ITER; typedef LIB_TABLE_ROWS::const_iterator LIB_TABLE_ROWS_CITER; /** * Allows boost pointer containers to make clones of the data stored in them. Since they * store pointers the data is cloned. Copying and assigning pointers would cause ownership * issues if the standard C++ containers were used. */ LIB_TABLE_ROW* new_clone( const LIB_TABLE_ROW& aRow ); /** * Hold a record identifying a library accessed by the appropriate plug in object in the * #LIB_TABLE. This is an abstract base class from which to derive library specific rows. */ class LIB_TABLE_ROW : boost::noncopyable { public: LIB_TABLE_ROW() : enabled( true ), visible( true ), m_loaded( false ), m_parent( nullptr ) { } virtual ~LIB_TABLE_ROW() { } LIB_TABLE_ROW( const wxString& aNick, const wxString& aURI, const wxString& aOptions, const wxString& aDescr = wxEmptyString, LIB_TABLE* aParent = nullptr ) : nickName( aNick ), description( aDescr ), enabled( true ), visible( true ), m_loaded( false ), m_parent( aParent ) { properties.reset(); SetOptions( aOptions ); SetFullURI( aURI ); } bool operator==( const LIB_TABLE_ROW& r ) const; bool operator!=( const LIB_TABLE_ROW& r ) const { return !( *this == r ); } /** * @return the logical name of this library table row. */ const wxString& GetNickName() const { return nickName; } /** * Change the logical name of this library, useful for an editor. */ void SetNickName( const wxString& aNickName ) { nickName = aNickName; } /** * @return true if the library was loaded without error */ bool GetIsLoaded() const { return m_loaded; } /** * Mark the row as being a loaded library */ void SetLoaded( bool aLoaded ) { m_loaded = aLoaded; }; /** * @return the enabled status of this library row */ bool GetIsEnabled() const { return enabled; } /** * Change the enabled status of this library */ void SetEnabled( bool aEnabled = true ) { enabled = aEnabled; } bool GetIsVisible() const { return visible; } void SetVisible( bool aVisible = true ) { visible = aVisible; } virtual bool Refresh() { return false; } /** * Return the type of library represented by this row. */ virtual const wxString GetType() const = 0; /** * Change the type of library represented by this row that must be implemented in the * derived object to provide the library table row type. */ virtual void SetType( const wxString& aType ) = 0; virtual bool SupportsSettingsDialog() const { return false; } virtual void ShowSettingsDialog( wxWindow* aParent ) const {} /** * Return the full location specifying URI for the LIB, either in original UI form or * in environment variable expanded form. * * @param aSubstituted Tells if caller wanted the substituted form, else not. */ const wxString GetFullURI( bool aSubstituted = false ) const; /** * Change the full URI for the library. */ void SetFullURI( const wxString& aFullURI ); /** * Return the options string, which may hold a password or anything else needed to * instantiate the underlying library plugin. */ const wxString& GetOptions() const { return options; } /** * Change the library options strings. */ void SetOptions( const wxString& aOptions ); /** * Return the description of the library referenced by this row. */ const wxString& GetDescr() const { return description; } /** * Change the description of the library referenced by this row. */ void SetDescr( const wxString& aDescr ) { description = aDescr; } LIB_TABLE* GetParent() const { return m_parent; } void SetParent( LIB_TABLE* aParent ) { m_parent = aParent; } std::mutex& GetMutex() { return m_loadMutex; } /** * Return the constant #PROPERTIES for this library (#LIB_TABLE_ROW). These are * the "options" in a table. */ const STRING_UTF8_MAP* GetProperties() const { return properties.get(); } /** * Serialize this object as utf8 text to an #OUTPUTFORMATTER, and tries to * make it look good using multiple lines and indentation. * * @param out is an #OUTPUTFORMATTER * @param nestLevel is the indentation level to base all lines of the output. * Actual indentation will be 2 spaces for each nestLevel. */ void Format( OUTPUTFORMATTER* out, int nestLevel ) const; LIB_TABLE_ROW* clone() const { return do_clone(); } protected: LIB_TABLE_ROW( const LIB_TABLE_ROW& aRow ) : nickName( aRow.nickName ), uri_user( aRow.uri_user ), options( aRow.options ), description( aRow.description ), enabled( aRow.enabled ), visible( aRow.visible ), m_loaded( aRow.m_loaded ), m_parent( aRow.m_parent ) { if( aRow.properties ) properties = std::make_unique( *aRow.properties.get() ); else properties.reset(); } void operator=( const LIB_TABLE_ROW& aRow ); private: virtual LIB_TABLE_ROW* do_clone() const = 0; void setProperties( STRING_UTF8_MAP* aProperties ); wxString nickName; wxString uri_user; ///< what user entered from UI or loaded from disk wxString options; wxString description; bool enabled = true; ///< Whether the LIB_TABLE_ROW is enabled bool visible = true; ///< Whether the LIB_TABLE_ROW is visible in choosers bool m_loaded = false; ///< Whether the LIB_TABLE_ROW is loaded LIB_TABLE* m_parent; ///< Pointer to the table this row lives in (maybe null) std::unique_ptr properties; std::mutex m_loadMutex; }; /** * Manage #LIB_TABLE_ROW records (rows), and can be searched based on library nickname. * *

* This class owns the library table, which is like fstab in concept and maps * logical library name to the library URI, type, and options. It is heavily based on * the SWEET parser work done by Dick Hollenbeck and can be seen in new/sch_lib_table.h. * A library table has the following columns: *

    *
  • Logical Library Name (Nickname) *
  • Library Type, used to determine which plugin to load to access the library. *
  • Library URI. The full URI to the library source, form dependent on Type. *
  • Options, used for as yet to be defined information such as user names or passwords *
*

*

* The Library Type can be one of: *

    *
  • "file" *
  • "ftp" *
  • "http" *
*

*

* For now, the Library URI types needed to support the various types can be one of those * shown below, which are typical of each type: *

    *
  • "file://C:/mylibdir" *
  • "ftp://kicad.org/partlib/trunk" *
  • "http://kicad.org/partlib" *
*

*

* The library table is built up from several additive entries (table fragments), and the * final table is a (conceptual) merging of the table fragments. Two anticipated sources * of the entries are a personal table saved in the KiCad configuration and a project * resident table that resides in project file. The project footprint table entries are * considered a higher priority in the final dynamically assembled library table. An row * in the project file contribution to the library table takes precedence over the personal * table if there is a collision of logical library names. Otherwise, the entries simply * combine without issue to make up the applicable library table. *

* * @author Wayne Stambaugh */ class LIB_TABLE : public PROJECT::_ELEM { public: /** * Parse the #LIB_TABLE_LEXER s-expression library table format into the appropriate * #LIB_TABLE_ROW objects. * * @param aLexer is the lexer to parse. * * @throw IO_ERROR if an I/O error occurs during parsing. * @throw PARSER_ERROR if the lexer format to parse is invalid. * @throw boost::bad_pointer if an any attempt to add an invalid pointer to the * boost::ptr_vector. * @throw boost::bad_index if an index outside the row table bounds is accessed. */ virtual void Parse( LIB_TABLE_LEXER* aLexer ) = 0; /** * Generate the table in s-expression format to \a aOutput with an indentation level * of \a aIndentLevel. * * @param aOutput is the #OUTPUTFORMATTER to format the table into. * @param aIndentLevel is the indentation level (2 spaces) to indent. * * @throw IO_ERROR if an I/O error occurs during output. * @throw boost::interprocess::lock_except if separate process attempt to access the table. */ virtual void Format( OUTPUTFORMATTER* aOutput, int aIndentLevel ) const = 0; /** * Build a library table by pre-pending this table fragment in front of \a aFallBackTable. * Loading of this table fragment is done by using Parse(). * * @param aFallBackTable is another LIB_TABLE which is searched only when * a row is not found in this table. No ownership is * taken of aFallBackTable. */ LIB_TABLE( LIB_TABLE* aFallBackTable = nullptr ); virtual ~LIB_TABLE(); /// Delete all rows. void Clear(); /** * Compares this table against another. * * This compares the row *contents* against each other. * Any fallback tables are not checked. */ bool operator==( const LIB_TABLE& r ) const { if( m_rows.size() == r.m_rows.size() ) { unsigned i; for( i = 0; i < m_rows.size() && m_rows[i] == r.m_rows[i]; ++i ) ; if( i == m_rows.size() ) return true; } return false; } bool operator!=( const LIB_TABLE& r ) const { return !( *this == r ); } /** * Get the number of rows contained in the table */ unsigned GetCount() const { return m_rows.size(); } /** * Get the 'n'th #LIB_TABLE_ROW object * @param aIndex index of row (must exist: from 0 to GetCount() - 1) * @return reference to the row */ LIB_TABLE_ROW& At( unsigned aIndex ) { return m_rows[aIndex]; } /** * @copydoc At() */ const LIB_TABLE_ROW& At( unsigned aIndex ) const { return m_rows[aIndex]; } /** * Return true if the table is empty. * * @param aIncludeFallback is used to determine if the fallback table should be * included in the test. * * @return true if the footprint library table is empty. */ bool IsEmpty( bool aIncludeFallback = true ); /** * @return the library description from @a aNickname, or an empty string * if @a aNickname does not exist. */ const wxString GetDescription( const wxString& aNickname ); /** * Test for the existence of \a aNickname in the library table. * * @param aCheckEnabled if true will only return true for enabled libraries * @return true if a library \a aNickname exists in the table. */ bool HasLibrary( const wxString& aNickname, bool aCheckEnabled = false ) const; /** * Test for the existence of \a aPath in the library table. * * @param aCheckEnabled if true will only return true for enabled libraries * @return true if a library \a aNickname exists in the table. */ bool HasLibraryWithPath( const wxString& aPath ) const; /** * Return the logical library names, all of them that are pertinent to * a look up done on this LIB_TABLE. */ std::vector GetLogicalLibs(); /** * Return the full URI of the library mapped to \a aLibNickname. */ wxString GetFullURI( const wxString& aLibNickname, bool aExpandEnvVars = true ) const; /** * Adds \a aRow if it does not already exist or if doReplace is true. If doReplace * is not true and the key for aRow already exists, the function fails and returns false. * * The key for the table is the nickName, and all in this table must be unique. * * @param aRow is the new row to insert, or to forcibly add if doReplace is true. * @param doReplace if true, means insert regardless of whether aRow's key already * exists. If false, then fail if the key already exists. * * @return bool - true if the operation succeeded. */ bool InsertRow( LIB_TABLE_ROW* aRow, bool doReplace = false ); /** * Removes a row from the table and frees the pointer * @param aRow is the row to remove * @return true if the row was found (and removed) */ bool RemoveRow( const LIB_TABLE_ROW* aRow ); /** * Replaces the Nth row with the given new row * @return true if successful */ bool ReplaceRow( size_t aIndex, LIB_TABLE_ROW* aRow ); /** * Moves a row within the table * @param aIndex is the current index of the row to move * @param aOffset is the number of positions to move it by in the table * @return true if the move resulted in a change */ bool ChangeRowOrder( size_t aIndex, int aOffset ); /** * Takes ownership of another list of rows; the original list will be freed */ void TransferRows( LIB_TABLE_ROWS& aRowsList ); /** * @return a #LIB_TABLE_ROW pointer if \a aURI is found in this table or in any chained * fallBack table fragments, else NULL. */ const LIB_TABLE_ROW* FindRowByURI( const wxString& aURI ); /** * Load the library table using the path defined by \a aFileName aFallBackTable. * * @param aFileName contains the full path to the s-expression file. * * @throw IO_ERROR if an error occurs attempting to load the footprint library * table. */ void Load( const wxString& aFileName ); /** * Write this library table to \a aFileName in s-expression form. * * @param aFileName is the name of the file to write to. */ void Save( const wxString& aFileName ) const; /** * Parses \a aOptionsList and places the result into a #PROPERTIES object which is * returned. If the options field is empty, then the returned PROPERTIES will be * a NULL pointer. * *

* Typically aOptionsList comes from the "options" field within a LIB_TABLE_ROW and * the format is simply a comma separated list of name value pairs. e.g.: * [name1[=value1][|name2[=value2]]] etc. When using the UI to create or edit * a library table, this formatting is handled for you. *

*/ static STRING_UTF8_MAP* ParseOptions( const std::string& aOptionsList ); /** * Returns a list of options from the aProperties parameter. * * The name=value pairs will be separated with the '|' character. The =value portion may * not be present. You might expect something like "name1=value1|name2=value2|flag_me". * Notice that flag_me does not have a value. This is ok. * * @param aProperties is the PROPERTIES to format or NULL. If NULL the returned * string will be empty. */ static UTF8 FormatOptions( const STRING_UTF8_MAP* aProperties ); /** * Returns the version number (0 if unset) * * @return integer version number read from table */ int GetVersion() const { return m_version; } protected: /** * Return a #LIB_TABLE_ROW if \a aNickname is found in this table or in any chained * fallBack table fragment, else NULL. * * @param aNickname is the name of the library table entry to find. * @param aCheckIfEnabled is a flag to check if the library table entry is enabled. * @return a pointer to the #LIB_TABLE_ROW found. */ LIB_TABLE_ROW* findRow( const wxString& aNickname, bool aCheckIfEnabled = false ) const; /** * Updates the env vars from older version of KiCad, provided they do not currently * resolve to anything * * @return True if the tables were modified */ bool migrate(); void reindex(); protected: LIB_TABLE* m_fallBack; /// Versioning to handle importing old tables mutable int m_version; /// Owning set of rows. // TODO: This should really be private; but the lib table grids re-use it // (without using m_rowsMap). LIB_TABLE_ROWS m_rows; /// this is a non-owning index into the LIB_TABLE_ROWS table std::map m_rowsMap; /// Mutex to protect access to the rows vector mutable std::shared_mutex m_mutex; }; #endif // _LIB_TABLE_BASE_H_