Merge pull request #3 from saurabhb17/master

secondary files

1 files changed, 635 insertions, 0 deletions

diff --git a/include/fp_lib_table.h b/include/fp_lib_table.h
new file mode 100644
index 0000000..a56897a
--- /dev/null
+++ b/include/fp_lib_table.h
@@ -0,0 +1,635 @@
+/*
+ * This program source code file is part of KiCad, a free EDA CAD application.
+ *
+ * Copyright (C) 2010-2012 SoftPLC Corporation, Dick Hollenbeck <dick@softplc.com>
+ * Copyright (C) 2012 Wayne Stambaugh <stambaughw@verizon.net>
+ * Copyright (C) 2012-2015 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 FP_LIB_TABLE_H_
+#define FP_LIB_TABLE_H_
+
+#include <macros.h>
+#include <vector>
+#include <map>
+#include <io_mgr.h>
+#include <project.h>
+#include <boost/interprocess/exceptions.hpp>
+
+#define FP_LATE_ENVVAR  1           ///< late=1/early=0 environment variable expansion
+
+class wxFileName;
+class OUTPUTFORMATTER;
+class MODULE;
+class FP_LIB_TABLE_LEXER;
+class FPID;
+
+/**
+ * Class FP_LIB_TABLE
+ * holds FP_LIB_TABLE::ROW records (rows), and can be searched based on library nickName.
+ * <p>
+ * This class owns the <b>footprint library table</b>, 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 footprint
+ * library table had  the following columns:
+ * <ul>
+ * <li> Logical Library Name (Nickname)
+ * <li> Library Type, used to determine which plugin to load to access the library.
+ * <li> Library URI.  The full URI to the library source, form dependent on Type.
+ * <li> Options, used for as yet to be defined information such as user names or passwords
+ * </ul>
+ * <p>
+ * The Library Type can be one of:
+ * <ul>
+ * <li> "file"
+ * <li> "ftp"
+ * <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> "ftp://kicad.org/partlib/trunk"
+ * <li> "http://kicad.org/partlib"
+ * </ul>
+ * <p>
+ * The footprint 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 FP_LIB_TABLE : public PROJECT::_ELEM
+{
+    friend class DIALOG_FP_LIB_TABLE;
+
+public:
+
+    /**
+     * Class ROW
+     * holds a record identifying a footprint library accessed by the appropriate #PLUGIN
+     * object in the #FP_LIB_TABLE.
+     */
+    class ROW
+    {
+        friend class FP_LIB_TABLE;
+        friend class DIALOG_FP_LIB_TABLE;
+
+    public:
+
+        typedef IO_MGR::PCB_FILE_T   LIB_T;
+
+        ROW() :
+            type( IO_MGR::KICAD ),
+            properties( 0 )
+        {
+        }
+
+        ROW( const wxString& aNick, const wxString& aURI, const wxString& aType,
+             const wxString& aOptions, const wxString& aDescr = wxEmptyString ) :
+            nickName( aNick ),
+            description( aDescr ),
+            properties( 0 )
+        {
+            SetOptions( aOptions ),
+            SetFullURI( aURI );
+            SetType( aType );
+        }
+
+        ROW( const ROW& a );
+
+        ~ROW()
+        {
+            delete properties;
+        }
+
+        ROW& operator=( const ROW& r );
+
+        /// Used in DIALOG_FP_LIB_TABLE for detecting an edit.
+        bool operator==( const ROW& r ) const;
+
+        bool operator!=( const ROW& r ) const   { return !( *this == r ); }
+
+        //-----<accessors>------------------------------------------------------
+
+        /**
+         * Function GetNickName
+         * returns the short name of this library table row.
+         */
+        const wxString& GetNickName() const         { return nickName; }
+
+        /**
+         * Function SetNickName
+         * changes the logical name of this library, useful for an editor.
+         */
+        void SetNickName( const wxString& aNickName ) { nickName = aNickName; }
+
+        /**
+         * Function GetType
+         * returns the type of LIB represented by this row.
+         */
+        const wxString GetType() const              { return IO_MGR::ShowType( type ); }
+
+        /**
+         * Function SetType
+         * changes the type represented by this row.
+         */
+        void SetType( const wxString& aType );
+
+        /**
+         * Function GetFullURI
+         * returns 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;
+
+        /**
+         * Function SetFullURI
+         * changes the full URI for the library.
+         */
+        void SetFullURI( const wxString& aFullURI );
+
+        /**
+         * Function GetOptions
+         * returns the options string, which may hold a password or anything else needed to
+         * instantiate the underlying LIB_SOURCE.
+         */
+        const wxString& GetOptions() const          { return options; }
+
+        /**
+         * Function SetOptions
+         */
+        void SetOptions( const wxString& aOptions )
+        {
+            options = aOptions;
+
+            // set PROPERTIES* from options
+            setProperties( ParseOptions( TO_UTF8( aOptions ) ) );
+        }
+
+        /**
+         * Function GetDescr
+         * returns the description of the library referenced by this row.
+         */
+        const wxString& GetDescr() const            { return description; }
+
+        /**
+         * Function SetDescr
+         * changes the description of the library referenced by this row.
+         */
+        void SetDescr( const wxString& aDescr )     { description = aDescr; }
+
+        /**
+         * Function GetProperties
+         * returns the constant PROPERTIES for this library (ROW).  These are
+         * the "options" in a table.
+         */
+        const PROPERTIES* GetProperties() const     { return properties; }
+
+        //-----</accessors>-----------------------------------------------------
+
+        /**
+         * 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, boost::interprocess::lock_exception );
+
+    private:
+
+        /**
+         * Function setProperties
+         * sets this ROW's PROPERTIES by taking ownership of @a aProperties.
+         * @param aProperties ownership is given over to this ROW.
+         */
+        void setProperties( const PROPERTIES* aProperties )
+        {
+            delete properties;
+            properties = aProperties;
+        }
+
+        void setPlugin( PLUGIN* aPlugin )
+        {
+            plugin.set( aPlugin );
+        }
+
+        wxString        nickName;
+        wxString        uri_user;           ///< what user entered from UI or loaded from disk
+
+#if !FP_LATE_ENVVAR
+        wxString        uri_expanded;       ///< from ExpandSubstitutions()
+#endif
+
+        LIB_T           type;
+        wxString        options;
+        wxString        description;
+
+        const PROPERTIES*   properties;
+        PLUGIN::RELEASER    plugin;
+    };
+
+    /**
+     * Constructor FP_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 FP_LIB_TABLE which is searched only when
+     *                       a row is not found in this table.  No ownership is
+     *                       taken of aFallBackTable.
+     */
+    FP_LIB_TABLE( FP_LIB_TABLE* aFallBackTable = NULL );
+
+    ~FP_LIB_TABLE();
+
+    /// Delete all rows.
+    void Clear()
+    {
+        rows.clear();
+        nickIndex.clear();
+    }
+
+    bool operator==( const FP_LIB_TABLE& r ) const
+    {
+        if( rows.size() == r.rows.size() )
+        {
+            unsigned i;
+            for( i = 0; i < rows.size() && rows[i] == r.rows[i];  ++i )
+                ;
+
+            if( i == rows.size() )
+                return true;
+        }
+
+        return false;
+    }
+
+    bool operator!=( const FP_LIB_TABLE& r ) const  { return !( *this == r ); }
+
+    int     GetCount()                              { return rows.size(); }
+
+    ROW&    At( int aIndex )                        { return rows[aIndex]; }
+
+    /**
+     * 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>
+     * (fp_lib_table
+     *   (lib (name LOGICAL)(descr DESCRIPTION)(uri FULL_URI)(type TYPE)(options OPTIONS))
+     *   (lib (name LOGICAL)(descr DESCRIPTION)(uri FULL_URI)(type TYPE)(options OPTIONS))
+     *   (lib (name LOGICAL)(descr DESCRIPTION)(uri FULL_URI)(type TYPE)(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( FP_LIB_TABLE_LEXER* aParser ) throw( IO_ERROR, PARSE_ERROR );
+
+    /**
+     * Function ParseOptions
+     * 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.
+     * <p>
+     * Typically aOptionsList comes from the "options" field within a 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 fp lib table, this formatting is handled for you.
+     */
+    static PROPERTIES* ParseOptions( const std::string& aOptionsList );
+
+    /**
+     * Function FormatOptions
+     * returns a list of options from the aProperties parameter.  The name=value
+     * pairs will be separted 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 PROPERTIES* aProperties );
+
+    /**
+     * 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, boost::interprocess::lock_exception );
+
+    /**
+     * Function GetLogicalLibs
+     * returns the logical library names, all of them that are pertinent to
+     * a lookup done on this FP_LIB_TABLE.
+     */
+    std::vector<wxString> GetLogicalLibs();
+
+    //-----<PLUGIN API SUBSET, REBASED ON aNickname>---------------------------
+
+    /**
+     * Function FootprintEnumerate
+     * returns a list of footprint names contained within the library given by
+     * @a aNickname.
+     *
+     * @param aNickname is a locator for the "library", it is a "name"
+     *     in FP_LIB_TABLE::ROW
+     *
+     * @return wxArrayString - is the array of available footprint names inside
+     *   a library
+     *
+     * @throw IO_ERROR if the library cannot be found, or footprint cannot be loaded.
+     */
+    wxArrayString FootprintEnumerate( const wxString& aNickname );
+
+    /**
+     * Function FootprintLoad
+     * loads a footprint having @a aFootprintName from the library given by @a aNickname.
+     *
+     * @param aNickname is a locator for the "library", it is a "name"
+     *     in FP_LIB_TABLE::ROW
+     *
+     * @param aFootprintName is the name of the footprint to load.
+     *
+     * @return  MODULE* - if found caller owns it, else NULL if not found.
+     *
+     * @throw   IO_ERROR if the library cannot be found or read.  No exception
+     *          is thrown in the case where aFootprintName cannot be found.
+     */
+    MODULE* FootprintLoad( const wxString& aNickname, const wxString& aFootprintName );
+
+    /**
+     * Enum SAVE_T
+     * is the set of return values from FootprintSave() below.
+     */
+    enum SAVE_T
+    {
+        SAVE_OK,
+        SAVE_SKIPPED,
+    };
+
+    /**
+     * Function FootprintSave
+     * will write @a aFootprint to an existing library given by @a aNickname.
+     * If a footprint by the same name already exists, it is replaced.
+     *
+     * @param aNickname is a locator for the "library", it is a "name"
+     *     in FP_LIB_TABLE::ROW
+     *
+     * @param aFootprint is what to store in the library. The caller continues
+     *    to own the footprint after this call.
+     *
+     * @param aOverwrite when true means overwrite any existing footprint by the
+     *  same name, else if false means skip the write and return SAVE_SKIPPED.
+     *
+     * @return SAVE_T - SAVE_OK or SAVE_SKIPPED.  If error saving, then IO_ERROR is thrown.
+     *
+     * @throw IO_ERROR if there is a problem saving.
+     */
+    SAVE_T FootprintSave( const wxString& aNickname, const MODULE* aFootprint, bool aOverwrite = true );
+
+    /**
+     * Function FootprintDelete
+     * deletes the @a aFootprintName from the library given by @a aNickname.
+     *
+     * @param aNickname is a locator for the "library", it is a "name"
+     *     in FP_LIB_TABLE::ROW
+     *
+     * @param aFootprintName is the name of a footprint to delete from the specified library.
+     *
+     * @throw IO_ERROR if there is a problem finding the footprint or the library, or deleting it.
+     */
+    void FootprintDelete( const wxString& aNickname, const wxString& aFootprintName );
+
+    /**
+     * Function IsFootprintLibWritable
+     * returns true iff the library given by @a aNickname is writable.  (Often
+     * system libraries are read only because of where they are installed.)
+     *
+     * @throw IO_ERROR if no library at aLibraryPath exists.
+     */
+    bool IsFootprintLibWritable( const wxString& aNickname );
+
+    void FootprintLibDelete( const wxString& aNickname );
+
+    void FootprintLibCreate( const wxString& aNickname );
+
+    //-----</PLUGIN API SUBSET, REBASED ON aNickname>---------------------------
+
+    /**
+     * Function FootprintLoadWithOptionalNickname
+     * loads a footprint having @a aFootprintId with possibly an empty nickname.
+     *
+     * @param aFootprintId the [nickname] & fooprint name of the footprint to load.
+     *
+     * @return  MODULE* - if found caller owns it, else NULL if not found.
+     *
+     * @throw   IO_ERROR if the library cannot be found or read.  No exception
+     *          is thrown in the case where aFootprintName cannot be found.
+     * @throw   PARSE_ERROR if @a aFootprintId is not parsed OK.
+     */
+    MODULE* FootprintLoadWithOptionalNickname( const FPID& aFootprintId )
+        throw( IO_ERROR, PARSE_ERROR, boost::interprocess::lock_exception );
+
+    /**
+     * Function GetDescription
+     * returns the library desicription from @a aNickname, or an empty string
+     * if aNickname does not exist.
+     */
+    const wxString GetDescription( const wxString& aNickname );
+
+    /**
+     * 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 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( const ROW& aRow, bool doReplace = false );
+
+    /**
+     * Function FindRow
+     * returns a ROW if aNickName is found in this table or in any chained
+     * fallBack table fragment.  The PLUGIN is loaded and attached
+     * to the "plugin" field of the ROW if not already loaded.
+     *
+     * @throw IO_ERROR if aNickName cannot be found.
+     */
+    const ROW* FindRow( const wxString& aNickName ) throw( IO_ERROR );
+
+    /**
+     * Function FindRowByURI
+     * returns a #FP_LIB_TABLE::ROW if aURE is found in this table or in any chained
+     * fallBack table fragments, else NULL.
+     */
+    const ROW* FindRowByURI( const wxString& aURI );
+
+    /**
+     * Function IsEmpty
+     * @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 );
+
+    /**
+     * Function ExpandSubstitutions
+     * replaces any environment variable references with their values and is
+     * here to fully embellish the ROW::uri in a platform independent way.
+     * This enables (fp_lib_table)s to have platform dependent environment
+     * variables in them, allowing for a uniform table across platforms.
+     */
+    static const wxString ExpandSubstitutions( const wxString& aString );
+
+    /**
+     * Function LoadGlobalTable
+     * loads the global footprint library table into \a aTable.
+     *
+     * This probably should be move into the application object when KiCad is changed
+     * to a single process application.  This is the least painful solution for the
+     * time being.
+     *
+     * @param aTable the #FP_LIB_TABLE object to load.
+     * @return true if the global library table exists and is loaded properly.
+     * @throw IO_ERROR if an error occurs attempting to load the footprint library
+     *                 table.
+     */
+    static bool LoadGlobalTable( FP_LIB_TABLE& aTable )
+        throw (IO_ERROR, PARSE_ERROR, boost::interprocess::lock_exception );
+
+    /**
+     * Function GetGlobalTableFileName
+     * @return the platform specific global footprint library path and file name.
+     */
+    static wxString GetGlobalTableFileName();
+
+#if 0
+    /**
+     * Function GetFileName
+     * @return the footprint library file name.
+     */
+    static const wxString GetFileName();
+#endif
+
+    /**
+     * Function GlobalPathEnvVarVariableName
+     * returns the name of the environment variable used to hold the directory of
+     * locally installed "KiCad sponsored" system footprint libraries.  These can
+     * be either legacy or pretty format.  The only thing special about this
+     * particular environment variable is that it is set automatically by
+     * KiCad on program startup, <b>iff</b> it is not set already in the environment.
+     */
+    static const wxString GlobalPathEnvVariableName();
+
+    /**
+     * Function Load
+     * loads the footprint library table using the path defined in \a aFileName with
+     * \a 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 ) throw( IO_ERROR );
+
+    /**
+     * Function Save
+     * writes this table to aFileName in s-expression form.
+     * @param aFileName is the name of the file to write to.
+     */
+    void Save( const wxString& aFileName ) const
+        throw( IO_ERROR, boost::interprocess::lock_exception );
+
+protected:
+
+    /**
+     * Function findRow
+     * returns a ROW if aNickname is found in this table or in any chained
+     * fallBack table fragment, else NULL.
+     */
+    ROW* findRow( const wxString& aNickname ) const;
+
+    void reindex()
+    {
+        nickIndex.clear();
+
+        for( ROWS_CITER it = rows.begin();  it != rows.end();  ++it )
+            nickIndex.insert( INDEX_VALUE( it->nickName, it - rows.begin() ) );
+    }
+
+    void ensureIndex()
+    {
+        // The dialog lib table editor may not maintain the nickIndex.
+        // Lazy indexing may be required.  To handle lazy indexing, we must enforce
+        // that "nickIndex" is either empty or accurate, but never inaccurate.
+        if( !nickIndex.size() )
+            reindex();
+    }
+
+    typedef std::vector<ROW>            ROWS;
+    typedef ROWS::iterator              ROWS_ITER;
+    typedef ROWS::const_iterator        ROWS_CITER;
+
+    ROWS            rows;
+
+    /// this is a non-owning index into the ROWS table
+    typedef std::map<wxString,int>      INDEX;              // "int" is std::vector array index
+    typedef INDEX::iterator             INDEX_ITER;
+    typedef INDEX::const_iterator       INDEX_CITER;
+    typedef INDEX::value_type           INDEX_VALUE;
+
+    /// this particular key is the nickName within each row.
+    INDEX           nickIndex;
+
+    FP_LIB_TABLE*   fallBack;
+};
+
+
+extern FP_LIB_TABLE GFootprintTable;        // KIFACE scope.
+
+#endif  // FP_LIB_TABLE_H_