kicad-developers team mailing list archive

[Dick Hollenbeck <dick@xxxxxxxxxxx>]

> Attached is the result of the first 1/2 hour of work.  Sorry I did not
> get more time this weekend on it.
>
> More over the next several days.
>   

More now.

Almost big enough now to test against doxygen.

Dick


// Author Dick Hollenbeck <dick@xxxxxxxxxxx>


typedef std::string STRING;
typedef std::vector< STRING >  STRINGS;


const STRING StrEmpty = "";



/**
 * Class LPID (aka GUID)
 * is a Logical Part ID and consists of various portions much like a URI.  It
 * relies heavily on a logical library name to hide where actual physical library
 * sources reside.  Its static functions serve as managers of the library table to
 * map logical library names to actual library sources.
 * <p>
 * Example LPID string:
 * "kicad:passives/R".
 * <p>
 * <ul>
 * <li> "kicad" is the logical library name.
 * <li> "passives" is the category.
 * <li> "passives/R" is the partname.
 * </ul>
 * <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 password. It has the following columns:
 * <ul>
 * <li> Logical Library Name
 * <li> Library Type
 * <li> Library URI
 * <li> Password
 * </ul>
 * <p>
 * For now, the Library Type can be one of:
 * <ul>
 * <li> "dir"
 * <li> "schematic"  i.e. a parts list
 * <li> "subversion"
 * <li> "bazaar"
 * <li> "http"
 * <p>
 * For now, the Library URI types needed to support the various types can be one of:
 * <ul>
 * <li> "file://C:/mylib"
 * <li> "svn://kicad.org/partlib/trunk"
 * <li> "http://kicad.org/partlib";
 * <p>
 * The library table is built up from several sources, and is a contatonation
 * of those sources.
 */
class LPID  // aka GUID
{
    /**
     * Constructor LPID
     * takes aLPID string and parses it.  A typical LPID string uses a logical
     * library name followed by a part name.
     * e.g.: "kicad:passives/R".
     */
    LPID( const STRING& aLPID ) throw( PARSE_ERROR );

    /**
     * Function GetLogLib
     * returns the logical library portion of a LPID.
     */
    STRING  GetLogLib();

    /**
     * Function GetCategory
     * returns the category of this part id, "passives" in the example at the
     * top of the class description.
     */
    STRING  GetCategory();


    //-----<statics>-----------------------------------------------------

    /**
     * Function GetLibraryURI
     * returns the full library path from a logical library name.
     */
    static STRING  GetLibraryURI( const STRING& aLogicalLibraryName );

    /**
     * Function GetLibraryType
     * returns the type of a logical library.
     */
    static STRING GetLibraryType( const STRING& aLogicalLibraryName );

    /**
     * Function GetLogLibraries
     * returns the logical library names, all of them.
     */
    static STRINGS GetLogLibraries();
};


class LIBRARY_SOURCE
{
public:
    /*
        NRVO described:
        http://msdn.microsoft.com/en-us/library/ms364057%28VS.80%29.aspx

        Even with NRVO provided by the compilers, I don't see it being as lean as
        having the LIBARY keep an expanded member STRING for the aResult value. So I
        am heading towards passing STRING* aResult and STRINGS* aResults. Rather
        than returning a STRING.
    */


    virtual STRING GetSourceType();


    virtual void ReadPart( STRING* aResult, const STRING& aName, const STRING& aRev=StrEmpty ) throw( IOError ) = 0;

    virtual void ReadParts( STRINGS* aResults, const STRINGS& aNames ) throw( IOError ) = 0;

    virtual void GetCategories( STRINGS* aResults ) throw( IOError ) = 0;

    virtual void GetCategoricalParts( STRINGS* aResults, const STRING& aCategory ) throw( IOError ) = 0;

    virtual void GetRevisions( STRINGS* aResults, const STRING& aName ) throw( IOError ) = 0;

    virtual void FindParts( STRINGS* aResults, const STRING& aQuery ) throw( IOError ) = 0;

protected:
    STRING      sourceType;
    STRING      sourceURI;
};


class LIBRARY_SINK
{
public:
    virtual void WritePart( const STRING& aName, const STRING& aSExpression ) throw ( IOERROR ) = 0;

protected:
    STRING      sinkType;
    STRING      sinkURI;
};


class LIBRARYS
{
    static LIBRARY* MakeLIBRARY( const STRING& aLogicalLibrary ) throw( IOError );

    static LIBRARY* FindOpened( const STRING& aLogicalLibrary );

    ~LIBRARIES();


private:

    /// collection of LIBRARYs, searchable by logical name.
    std::map< STRING, LIBRARY* >    libraries;      // owns the LIBRARYs.
};




/**
 * Class LIBRARY
 * is a cache of parts.
 */
class LIBRARY
{
public:

    /**
     * Constructor LIBRARY
     *
     * @param aLogicalLibrary is the name of a well know logical library, and is
     *  known because it already exists in the library table.
     *
     * @param aLibrarySource is an open LIBRARY_SOURCE whose ownership is
     *          given over to this LIBRARY.
     *
     * @param aLibrarySink is an open LIBRARY_SINK whose ownership is given over
     *          to this LIBRARY, and it is normally NULL.
     */
     LIBRARY( const STRING& aLogicalLibrary, LIBRARY_SOURCE* aSource, LIBRARY_SINK* aSink ) :
        name( aLogicalLibrary ),
        source( aSource ),
        sink( aSink )
    {
    }

    ~LIBRARY()
    {
        delete source;
        delete sink;
    }


    /**
     * Function HasSink
     * returns true if this library has write/save capability.  Most LIBARARYs
     * are read only.
     */
    bool HasSave()  { return sink != NULL; }


    //-----<use delegates: source and sink>---------------------------------

    /**
     * Function GetPart
     * returns a PART
     */
    const PART* ReadPart( const STRING& aName ) throw( IOError ) = 0;


    void ReadParts( STRINGS* aResults, const STRINGS& aNames ) throw( IOError ) = 0;

    void GetCategories( STRINGS* aResults ) throw( IOError ) = 0;

    void GetCategoricalParts( STRINGS* aResults, const STRING& aCategory ) throw( IOError ) = 0;

    //-----<.use delegates: source and sink>--------------------------------


    //-----<hybrids>--------------------------------------------------------

    void GetRevisions( STRINGS* aResults, const STRING& aName ) throw( IOError ) = 0;

    void FindParts( STRINGS* aResults, const STRING& aQuery ) throw( IOError ) = 0;

    //-----</hybrids>-------------------------------------------------------


private:
    LIBARARY_SOURCE*    source;
    LIBRARY_SINK*       sink;

    STRING              name;
    STRING              libraryType;
    STRING              libraryURI;
};

//EOF