389 lines
13 KiB
C++
389 lines
13 KiB
C++
/*
|
|
* This program source code file is part of KiCad, a free EDA CAD application.
|
|
*
|
|
* Copyright (C) 2010 SoftPLC Corporation, Dick Hollenbeck <dick@softplc.com>
|
|
* Copyright (C) 2010 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 SCH_LIB_TABLE_H_
|
|
#define SCH_LIB_TABLE_H_
|
|
|
|
#include <string>
|
|
#include <boost/ptr_container/ptr_map.hpp>
|
|
|
|
#include <import_export.h>
|
|
#include <sch_lib.h>
|
|
|
|
class OUTPUTFORMATTER;
|
|
class SCH_LIB_TABLE_LEXER;
|
|
|
|
|
|
namespace SCH {
|
|
|
|
class LPID;
|
|
class PART;
|
|
|
|
/**
|
|
* Class LIB_TABLE
|
|
* holds LIB_TABLE::ROW records, and can be searched in a very high speed
|
|
* way based on logical library name.
|
|
* <p>
|
|
* This class owns the <b>library table</b>, which is like fstab in concept and maps logical
|
|
* library name to library URI, type, and options. It has the following columns:
|
|
* <ul>
|
|
* <li> Logical Library Name
|
|
* <li> Library Type
|
|
* <li> Library URI. The full URI to the library source, form dependent on Type.
|
|
* <li> Options, used for access, such as password
|
|
* </ul>
|
|
* <p>
|
|
* The Library Type can be one of:
|
|
* <ul>
|
|
* <li> "dir"
|
|
* <li> "schematic" i.e. a parts list from another schematic.
|
|
* <li> "subversion"
|
|
* <li> "http"
|
|
* </ul>
|
|
* <p>
|
|
* 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:
|
|
* <ul>
|
|
* <li> "file://C:/mylibdir"
|
|
* <li> "file://home/user/kicadwork/jtagboard.sch"
|
|
* <li> "svn://kicad.org/partlib/trunk"
|
|
* <li> "http://kicad.org/partlib"
|
|
* </ul>
|
|
* <p>
|
|
* The applicable library table is built up from several additive rows (table fragments),
|
|
* and the final table is a (conceptual) merging of the table fragments. Two
|
|
* anticipated sources of the rows are a personal table, and a schematic resident
|
|
* table. The schematic resident table rows are considered a higher priority in
|
|
* the final dynamically assembled library table. A row in the schematic
|
|
* contribution to the library table takes precedence over the personal table
|
|
* if there is a collision on logical library name, otherwise the rows simply
|
|
* combine without issue to make up the applicable library table.
|
|
*
|
|
* @author Dick Hollenbeck
|
|
*/
|
|
class MY_API LIB_TABLE
|
|
{
|
|
public:
|
|
|
|
/**
|
|
* Class ROW
|
|
* holds a record identifying a LIB in the LIB_TABLE.
|
|
*/
|
|
class ROW
|
|
{
|
|
friend class LIB_TABLE;
|
|
|
|
public:
|
|
|
|
/**
|
|
* Function GetLogicalName
|
|
* returns the logical name of this library table entry.
|
|
*/
|
|
const STRING& GetLogicalName() const
|
|
{
|
|
return logicalName;
|
|
}
|
|
|
|
/**
|
|
* Function GetType
|
|
* returns the type of LIB represented by this record.
|
|
*/
|
|
const STRING& GetType() const
|
|
{
|
|
return libType;
|
|
}
|
|
|
|
/**
|
|
* Function GetFullURI
|
|
* returns the full location specifying URI for the LIB.
|
|
*/
|
|
const STRING& GetFullURI() const
|
|
{
|
|
return fullURI;
|
|
}
|
|
|
|
/**
|
|
* Function GetOptions
|
|
* returns the options string, which may hold a password or anything else needed to
|
|
* instantiate the underlying LIB_SOURCE.
|
|
*/
|
|
const STRING& GetOptions() const
|
|
{
|
|
return options;
|
|
}
|
|
|
|
~ROW()
|
|
{
|
|
delete lib;
|
|
}
|
|
|
|
/**
|
|
* Function Format
|
|
* serializes 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
|
|
throw( IO_ERROR );
|
|
|
|
protected:
|
|
|
|
ROW( LIB_TABLE* aOwner ) :
|
|
owner( aOwner ),
|
|
lib( 0 )
|
|
{}
|
|
|
|
/**
|
|
* Function SetLogicalName
|
|
* changes the logical name of this library, useful for an editor.
|
|
*/
|
|
void SetLogicalName( const STRING& aLogicalName )
|
|
{
|
|
logicalName = aLogicalName;
|
|
}
|
|
|
|
/**
|
|
* Function SetType
|
|
* changes the type represented by this record.
|
|
*/
|
|
void SetType( const STRING& aType )
|
|
{
|
|
libType = aType;
|
|
}
|
|
|
|
/**
|
|
* Function SetFullURI
|
|
* changes the full URI for the library, useful from a library table editor.
|
|
*/
|
|
void SetFullURI( const STRING& aFullURI )
|
|
{
|
|
fullURI = aFullURI;
|
|
}
|
|
|
|
/**
|
|
* Function SetOptions
|
|
* changes the options string for this record, and is useful from
|
|
* the library table editor.
|
|
*/
|
|
void SetOptions( const STRING& aOptions )
|
|
{
|
|
options = aOptions;
|
|
}
|
|
|
|
private:
|
|
LIB_TABLE* owner;
|
|
STRING logicalName;
|
|
STRING libType;
|
|
STRING fullURI;
|
|
STRING options;
|
|
|
|
LIB* lib; ///< ownership of the loaded LIB is here
|
|
};
|
|
|
|
/**
|
|
* Constructor LIB_TABLE
|
|
* builds 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 record is not found in this table. No ownership is taken of aFallBackTable.
|
|
*/
|
|
LIB_TABLE( LIB_TABLE* aFallBackTable = NULL );
|
|
|
|
/**
|
|
* Function Parse
|
|
* fills this table fragment from information in the input stream \a aParser, which
|
|
* is a DSNLEXER customized for the grammar needed to describe instances of this object.
|
|
* The entire textual element spec is <br>
|
|
*
|
|
* <pre>
|
|
* (lib_table
|
|
* (lib (logical LOGICAL)(type TYPE)(full_uri FULL_URI)(options OPTIONS))
|
|
* (lib (logical LOGICAL)(type TYPE)(full_uri FULL_URI)(options OPTIONS))
|
|
* (lib (logical LOGICAL)(type TYPE)(full_uri FULL_URI)(options OPTIONS))
|
|
* )
|
|
* </pre>
|
|
*
|
|
* When this function is called, the input token stream given by \a aParser
|
|
* is assumed to be positioned at the '^' in the following example, i.e. just
|
|
* after the identifying keyword and before the content specifying stuff.
|
|
* <br>
|
|
* (lib_table ^ (....) )
|
|
*
|
|
* @param aParser is the input token stream of keywords and symbols.
|
|
*/
|
|
void Parse( SCH_LIB_TABLE_LEXER* aParser ) throw( IO_ERROR, PARSE_ERROR );
|
|
|
|
/**
|
|
* Function Format
|
|
* serializes 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 throw( IO_ERROR );
|
|
|
|
/**
|
|
* Function LookupPart
|
|
* finds and loads a PART, and parses it. As long as the part is
|
|
* accessible in any LIB_SOURCE, opened or not opened, this function
|
|
* will find it and load it into its containing LIB, even if that means
|
|
* having to open a LIB in this table that was not previously opened.
|
|
*
|
|
* @param aLogicalPartID holds the partName and may also hold the logicalLibName. If
|
|
* logicalLibName is empty, then @a aFallBackLib should not be NULL.
|
|
*
|
|
* @param aFallBackLib is used only if aLogicalPartID has an empty logicalLibName.
|
|
* This is for the case when an LPID has no logicalLibName because the LPID is using
|
|
* a partName from the same LIB as was the referring content.
|
|
*
|
|
* @return PART* - this will never be NULL, and no ownership is transfered because
|
|
* all PARTs live in LIBs. You only get to point to them in some LIB. If the PART
|
|
* cannot be found, then an exception is thrown.
|
|
*
|
|
* @throw IO_ERROR if any problem occurs or if the part cannot be found.
|
|
*/
|
|
PART* LookupPart( const LPID& aLogicalPartID, LIB* aFallBackLib = NULL ) throw( IO_ERROR );
|
|
|
|
/**
|
|
* Function GetLogicalLibs
|
|
* returns the logical library names, all of them that are in pertinent to
|
|
* a lookup done on this LIB_TABLE.
|
|
*/
|
|
STRINGS GetLogicalLibs();
|
|
|
|
//----<read accessors>----------------------------------------------------
|
|
// the returning of a const STRING* tells if not found, but might be too
|
|
// promiscuous?
|
|
|
|
/**
|
|
* Function GetLibURI
|
|
* returns the full library path from a logical library name.
|
|
* @param aLogicalLibraryName is the short name for the library of interest.
|
|
* @return const STRING* - or NULL if not found.
|
|
*/
|
|
const STRING* GetLibURI( const STRING& aLogicalLibraryName ) const
|
|
{
|
|
const ROW* row = FindRow( aLogicalLibraryName );
|
|
return row ? &row->fullURI : 0;
|
|
}
|
|
|
|
/**
|
|
* Function GetLibType
|
|
* returns the type of a logical library.
|
|
* @param aLogicalLibraryName is the short name for the library of interest.
|
|
* @return const STRING* - or NULL if not found.
|
|
*/
|
|
const STRING* GetLibType( const STRING& aLogicalLibraryName ) const
|
|
{
|
|
const ROW* row = FindRow( aLogicalLibraryName );
|
|
return row ? &row->libType : 0;
|
|
}
|
|
|
|
/**
|
|
* Function GetLibOptions
|
|
* returns the options string for \a aLogicalLibraryName.
|
|
* @param aLogicalLibraryName is the short name for the library of interest.
|
|
* @return const STRING* - or NULL if not found.
|
|
*/
|
|
const STRING* GetLibOptions( const STRING& aLogicalLibraryName ) const
|
|
{
|
|
const ROW* row = FindRow( aLogicalLibraryName );
|
|
return row ? &row->options : 0;
|
|
}
|
|
|
|
//----</read accessors>---------------------------------------------------
|
|
|
|
#if 1 || defined(DEBUG)
|
|
/// implement the tests in here so we can honor the priviledge levels of the
|
|
/// accessors, something difficult to do from int main(int, char**)
|
|
void Test();
|
|
#endif
|
|
|
|
protected: // only a table editor can use these
|
|
|
|
/**
|
|
* Function InsertRow
|
|
* adds 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 logicalName, 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( std::auto_ptr<ROW>& aRow, bool doReplace = false );
|
|
|
|
/**
|
|
* Function FindRow
|
|
* returns a ROW* if aLogicalName is found in this table or in any chained
|
|
* fallBack table fragment, else NULL.
|
|
*/
|
|
ROW* FindRow( const STRING& aLogicalName ) const;
|
|
|
|
private:
|
|
|
|
/**
|
|
* Function lookupLib
|
|
* finds or loads a LIB based on @a aLogicalPartID or @a aFallBackLib.
|
|
* If the LIB is already loaded then it is returned as is, else it is loaded.
|
|
*
|
|
* @param aLogicalPartID holds the partName and may also hold the logicalLibName. If
|
|
* logicalLibName is empty, then @a aFallBackLib should not be NULL.
|
|
*
|
|
* @param aFallBackLib is used only if aLogicalPartID has an empty logicalLibName.
|
|
* This is for the case when an LPID has no logicalLibName because the LPID is using
|
|
* a partName from the same LIB as was the referring content.
|
|
*
|
|
* @return LIB* - this will never be NULL, and no ownership is transfered because
|
|
* all LIBs live in the LIB_TABLEs. You only get to point to them in some LIB_TABLE.
|
|
* If the LIB cannot be found, then an exception is thrown.
|
|
*
|
|
* @throw IO_ERROR if any problem occurs or if the LIB cannot be found or cannot be loaded.
|
|
*/
|
|
LIB* lookupLib( const LPID& aLogicalPartID, LIB* aFallBackLib = NULL ) throw( IO_ERROR );
|
|
|
|
/**
|
|
* Function loadLib
|
|
* loads a LIB using information in @a aRow. Call only if LIB not
|
|
* already loaded.
|
|
*/
|
|
void loadLib( ROW* aRow ) throw( IO_ERROR );
|
|
|
|
typedef boost::ptr_map<STRING, ROW> ROWS;
|
|
typedef ROWS::iterator ROWS_ITER;
|
|
typedef ROWS::const_iterator ROWS_CITER;
|
|
|
|
ROWS rows;
|
|
LIB_TABLE* fallBack;
|
|
};
|
|
|
|
} // namespace SCH
|
|
|
|
#endif // SCH_LIB_TABLE_H_
|