kicad/new/sch_lib_table.h

/*
 * 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_