class_library.h 17.4 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25
/*
 * This program source code file is part of KiCad, a free EDA CAD application.
 *
 * Copyright (C) 2004 Jean-Pierre Charras, jaen-pierre.charras@gipsa-lab.inpg.com
 * Copyright (C) 2008-2011 Wayne Stambaugh <stambaughw@verizon.net>
 * Copyright (C) 2004-2011 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
 */

26 27 28 29
/**
 * @file class_library.h
 * @brief Definition for component library class.
 */
charras's avatar
charras committed
30 31 32 33

#ifndef CLASS_LIBRARY_H
#define CLASS_LIBRARY_H

34 35
#include <wx/filename.h>

36
#include <class_libentry.h>
charras's avatar
charras committed
37

38

39
class LINE_READER;
40
class OUTPUTFORMATTER;
41 42


43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73
/*
 * Component Library version and file header  macros.
 */
#define LIB_VERSION_MAJOR 2
#define LIB_VERSION_MINOR 3

/* Must be the first line of component library (.lib) files. */
#define LIBFILE_IDENT     "EESchema-LIBRARY Version"

#define LIB_VERSION( major, minor ) ( major * 100 + minor )

#define IS_LIB_CURRENT_VERSION( major, minor )              \
    (                                                       \
        LIB_VERSION( major1, minor1 ) ==                    \
        LIB_VERSION( LIB_VERSION_MAJOR, LIB_VERSION_MINOR)  \
    )

/*
 * Library versions 2.3 and lower use the old separate library (.lib) and
 * document (.dcm) files.  Component libraries after 2.3 merged the library
 * and document files into a single library file.  This macro checks if the
 * library version supports the old format
 */
#define USE_OLD_DOC_FILE_FORMAT( major, minor )                 \
    ( LIB_VERSION( major, minor ) <= LIB_VERSION( 2, 3 ) )

/* Must be the first line of component library document (.dcm) files. */
#define DOCFILE_IDENT     "EESchema-DOCLIB  Version 2.0"

#define DOC_EXT           wxT( "dcm" )

charras's avatar
charras committed
74

75 76
/* Helpers for creating a list of component libraries. */
class CMP_LIBRARY;
77 78
class wxRegEx;

79 80 81 82 83 84

typedef boost::ptr_vector< CMP_LIBRARY > CMP_LIBRARY_LIST;

extern bool operator<( const CMP_LIBRARY& item1, const CMP_LIBRARY& item2 );


85
/**
86 87
 * Class CMP_LIBRARY
 * is used to load, save, search, and otherwise manipulate
88 89
 * component library files.
 */
90
class CMP_LIBRARY
charras's avatar
charras committed
91
{
92 93 94 95 96 97 98 99 100 101
    int                type;            ///< Library type indicator.
    wxFileName         fileName;        ///< Library file name.
    wxDateTime         timeStamp;       ///< Library save time and date.
    int                versionMajor;    ///< Library major version number.
    int                versionMinor;    ///< Library minor version number.
    bool               isCache;         /**< False for the "standard" libraries,
                                             True for the library cache */
    wxString           header;          ///< first line of loaded library.
    bool               isModified;      ///< Library modification status.
    LIB_ALIAS_MAP      aliases;         ///< Map of aliases objects associated with the library.
102 103 104 105

    static CMP_LIBRARY_LIST libraryList;
    static wxArrayString    libraryListSortOrder;

106
    friend class LIB_COMPONENT;
107

charras's avatar
charras committed
108
public:
109 110
    CMP_LIBRARY( int aType, const wxFileName& aFileName );
    CMP_LIBRARY( int aType, const wxString& aFileName )
111
    {
112
        CMP_LIBRARY( aType, wxFileName( aFileName ) );
113 114
    }
    ~CMP_LIBRARY();
115

charras's avatar
charras committed
116
    /**
117
     * Function Save
118
     * writes library to \a aFormatter.
119
     *
120 121
     * @param aFormatter An #OUTPUTFORMATTER object to write the library to.
     * @return True if success writing to \a aFormatter.
122
     */
123
    bool Save( OUTPUTFORMATTER& aFormatter );
124 125

    /**
126 127
     * Function SaveDocs
     * write the library document information to \a aFormatter.
128
     *
129 130
     * @param aFormatter An #OUTPUTFORMATTER object to write the library documentation to.
     * @return True if success writing to \a aFormatter.
charras's avatar
charras committed
131
     */
132
    bool SaveDocs( OUTPUTFORMATTER& aFormatter );
charras's avatar
charras committed
133

134 135 136
    /**
     * Load library from file.
     *
137
     * @param aErrorMsg - Error message if load fails.
138
     * @return True if load was successful otherwise false.
139
     */
140
    bool Load( wxString& aErrorMsg );
141

142
    bool LoadDocs( wxString& aErrorMsg );
143

charras's avatar
charras committed
144
private:
145
    bool SaveHeader( OUTPUTFORMATTER& aFormatter );
146

147
    bool LoadHeader( LINE_READER& aLineReader );
148
    void LoadAliases( LIB_COMPONENT* aComponent );
149

150
public:
151 152 153
    /**
     * Get library entry status.
     *
154
     * @return True if there are no entries in the library.
155
     */
156
    bool IsEmpty() const
157
    {
158
        return aliases.empty();
159 160 161
    }

    /**
162 163
     * Function GetCount
     * returns the number of entries in the library.
164 165 166
     *
     * @return The number of component and alias entries.
     */
167
    int GetCount() const
168
    {
169
        return aliases.size();
170 171
    }

172
    bool IsModified() const
173
    {
174
        return isModified;
175 176
    }

177
    bool IsCache() const { return isCache; }
178

179
    void SetCache( void ) { isCache = true; }
180

181 182 183 184 185 186 187
    /**
     * Function IsReadOnly
     * @return true if current user does not have write access to the library file.
     */
    bool IsReadOnly() const { return !fileName.IsFileWritable(); }

    /**
188 189
     * Load a string array with the names of all the entries in this library.
     *
190 191 192
     * @param aNames - String array to place entry names into.
     * @param aSort - Sort names if true.
     * @param aMakeUpperCase - Force entry names to upper case.
193
     */
194
    void GetEntryNames( wxArrayString& aNames, bool aSort = true,
195
                        bool aMakeUpperCase =
196
#ifdef KICAD_KEEPCASE
197
                                              false
198 199
#else
                                              true
200 201
#endif
                        );
202 203 204 205 206 207 208 209

    /**
     * Load string array with entry names matching name and/or key word.
     *
     * This currently mimics the old behavior of calling KeyWordOk() and
     * WildCompareString().  The names array will be populated with the
     * library entry names that meat the search criteria on exit.
     *
210 211 212 213
     * @param aNames - String array to place entry names into.
     * @param aNameSearch - Name wild card search criteria.
     * @param aKeySearch - Key word search criteria.
     * @param aSort - Sort names if true.
214
     */
215
    void SearchEntryNames( std::vector<wxArrayString>& aNames,
216 217 218
                           const wxString& aNameSearch = wxEmptyString,
                           const wxString& aKeySearch = wxEmptyString,
                           bool aSort = true );
219

220 221 222
    /**
     * Find components in library by key word regular expression search.
     *
223
     * @param aNames - String array to place found component names into.
224
     * @param aRe - Regular expression used to search component key words.
225
     * @param aSort - Sort component name list.
226
     */
227
    void SearchEntryNames( wxArrayString& aNames, const wxRegEx& aRe, bool aSort = true );
228

229
    /**
230
     * Checks \a aComponent for name conflict in the library.
231
     *
232
     * @param aComponent - The component to check.
233
     * @return True if a conflict exists.  Otherwise false.
234
     */
235
    bool Conflicts( LIB_COMPONENT* aComponent );
236 237

    /**
238
     * Find entry by name.
239
     *
240 241
     * @param aName - Name of entry, case insensitive.
     * @return Entry if found.  NULL if not found.
242
     */
243
    LIB_ALIAS* FindEntry( const wxString& aName );
244

245
    /**
246
     * Find component by \a aName.
247
     *
248
     * This is a helper for FindEntry so casting a LIB_ALIAS pointer to
249
     * a LIB_COMPONENT pointer is not required.
250
     *
251 252
     * @param aName - Name of component, case insensitive.
     * @return Component if found.  NULL if not found.
253
     */
254
    LIB_COMPONENT* FindComponent( const wxString& aName );
255 256

    /**
257
     * Find alias by \a nName.
258
     *
259
     * This is a helper for FindEntry so casting a LIB_ALIAS pointer to
260
     * a LIB_ALIAS pointer is not required.
261
     *
262 263
     * @param aName - Name of alias, case insensitive.
     * @return Alias if found.  NULL if not found.
264
     */
265
    LIB_ALIAS* FindAlias( const wxString& aName )
266
    {
267
        return (LIB_ALIAS*) FindEntry( aName );
268 269 270
    }

    /**
271
     * Add a new \a aAlias entry to the library.
272 273 274 275 276 277 278
     *
     * First check if a component or alias with the same name already exists
     * in the library and add alias if no conflict occurs.  Once the alias
     * is added to the library it is owned by the library.  Deleting the
     * alias pointer will render the library unstable.  Use RemoveEntry to
     * remove the alias from the library.
     *
279 280
     * @param aAlias - Alias to add to library.
     * @return True if alias added to library.  False if a conflict exists.
281
     */
282
    bool AddAlias( LIB_ALIAS* aAlias );
283

284
    /**
285
     * Add \a aComponent entry to library.
286 287 288 289
     * Note a component can have an alias list,
     * so these alias will be added in library.
     * Conflicts can happen if aliases are already existing.
     * User is asked to choose what alias is removed (existing, or new)
290 291
     * @param aComponent - Component to add.
     * @return Added component if successful.
292
     */
293
    LIB_COMPONENT* AddComponent( LIB_COMPONENT* aComponent );
294 295

    /**
296
     * Safely remove \a aEntry from the library and return the next entry.
297
     *
298 299 300 301
     * The next entry returned depends on the entry being removed.  If the entry being
     * remove also removes the component, then the next entry from the list is returned.
     * If the entry being used only removes an alias from a component, then the next alias
     * of the component is returned.
302
     *
303
     * @param aEntry - Entry to remove from library.
304
     * @return The next entry in the library or NULL if the library is empty.
305
     */
306
    LIB_ALIAS* RemoveEntry( LIB_ALIAS* aEntry );
307

308 309
    /**
     * Replace an existing component entry in the library.
310 311
     * Note a component can have an alias list,
     * so these alias will be added in library (and previously existing alias removed)
312 313
     * @param aOldComponent - The component to replace.
     * @param aNewComponent - The new component.
314
     */
315 316
    LIB_COMPONENT* ReplaceComponent( LIB_COMPONENT* aOldComponent,
                                     LIB_COMPONENT* aNewComponent );
317

318 319 320 321 322
    /**
     * Return the first entry in the library.
     *
     * @return The first entry or NULL if the library has no entries.
     */
323
    LIB_ALIAS* GetFirstEntry();
324 325

    /**
326
     * Find next library entry by \a aName.
327 328 329 330
     *
     * If the name of the entry is the last entry in the library, the first
     * entry in the list is returned.
     *
331 332
     * @param aName - Name of current entry.
     * @return Next entry if entry name is found. Otherwise NULL.
333
     */
334
    LIB_ALIAS* GetNextEntry( const wxString& aName );
335 336 337


    /**
338
     * Find previous library entry by \a aName.
339 340 341 342
     *
     * If the name of the entry is the first entry in the library, the last
     * entry in the list is returned.
     *
343
     * @param aName - Name of current entry.
344
     * @return Previous entry if entry name is found, otherwise NULL.
345
     */
346
    LIB_ALIAS* GetPreviousEntry( const wxString& aName );
347 348 349 350

    /**
     * Return the file name without path or extension.
     *
351
     * @return Name of library file.
352
     */
353
    wxString GetName() const { return fileName.GetName(); }
354 355

    /**
356 357
     * Function GetFullFileName
     * returns the full file library name with path and extension.
358
     *
359
     * @return wxString - Full library file name with path and extension.
360
     */
361
    wxString GetFullFileName() { return fileName.GetFullPath(); }
362 363

    /**
364
     * Function GetLogicalName
Dick Hollenbeck's avatar
Dick Hollenbeck committed
365 366
     * returns the logical name of the library.
     * @return wxString - The logical name of this library.
367
     */
Dick Hollenbeck's avatar
Dick Hollenbeck committed
368 369 370 371 372 373 374 375 376 377 378 379
    wxString GetLogicalName()
    {
        /*  for now is the filename without path or extension.

            Technically the library should not know its logical name!
            This will eventually come out of a pair of lookup tables using a
            reverse lookup using the full name or library pointer as a key.
            Search will be by project lookup table and then user lookup table if
            not found.
        */
        return fileName.GetName();
    }
380 381 382 383 384


    /**
     * Function SetFileName
     * sets the component library file name.
385
     *
386
     * @param aFileName - New library file name.
387
     */
388
    void SetFileName( const wxFileName aFileName )
389
    {
390 391
        if( aFileName != fileName )
            fileName = aFileName;
392 393 394 395 396 397 398 399 400
    }

    /*
     * The following static methods are for manipulating the list of
     * component libraries.  This eliminates the need for yet another
     * global variable ( formerly g_LibraryList ) and gives some measure
     * of safety from abusing the library list.
     */

401 402 403
    /**
     * Function LibraryExists
     * tests for existence of a library.
404 405
     *
     * @param aLibptr - aLibptr.
406
     * @return bool - true if exists, else false
407 408 409
     */

    static bool LibraryExists( const CMP_LIBRARY* aLibptr );
410

411
    /**
412 413
     * Function LoadLibrary
     * loads a component library file.
414
     *
415 416
     * @param aFileName - File name of the component library to load.
     * @param aErrorMsg - Error message if the component library failed to load.
417 418
     * @return Library object if library file loaded successfully,
     *         otherwise NULL.
419
     */
420
    static CMP_LIBRARY* LoadLibrary( const wxFileName& aFileName, wxString& aErrorMsg );
421 422

    /**
423
     * Function AddLibrary
424
     * adds a component library to the library list.
425
     *
426 427
     * @param aFileName - File name object of component library.
     * @param aErrorMsg - Error message if the component library failed to load.
428
     * @return True if library loaded properly otherwise false.
429
     */
430
    static bool AddLibrary( const wxFileName& aFileName, wxString& aErrorMsg );
431 432

    /**
433
     * Function AddLibrary
434
     * inserts a component library into the library list.
435
     *
436
     * @param aFileName - File name object of component library.
437 438
     * @param aErrorMsg - Error message if the component library failed to load.
     * @param aIterator - Iterator to insert library in front of.
439
     * @return True if library loaded properly otherwise false.
440
     */
441 442
    static bool AddLibrary( const wxFileName& aFileName, wxString& aErrorMsg,
                            CMP_LIBRARY_LIST::iterator& aIterator );
443 444

    /**
445 446
     * Function RemoveLibrary
     * removes a component library from the library list.
447
     *
448
     * @param aName - Name of component library to remove.
449
     */
450
    static void RemoveLibrary( const wxString& aName );
451

452 453
    static void RemoveAllLibraries() { libraryList.clear(); }

454
    /**
455 456
     * Function FindLibrary
     * finds a component library by \a aName.
457
     *
458 459
     * @param aName - Library file name without path or extension to find.
     * @return Component library if found, otherwise NULL.
460
     */
461
    static CMP_LIBRARY* FindLibrary( const wxString& aName );
462 463

    /**
464 465
     * Function GetLibraryNames
     * returns the list of component library file names without path and extension.
466
     *
467 468
     * @param aSorted - Sort the list of name if true.  Otherwise use the
     *                  library load order.
469
     * @return The list of library names.
470
     */
471
    static wxArrayString GetLibraryNames( bool aSorted = true );
472

473
    /**
474 475
     * Function FindLibraryComponent
     * searches all libraries in the list for a component.
476 477 478 479
     *
     * A component object will always be returned.  If the entry found
     * is an alias.  The root component will be found and returned.
     *
480
     * @param aComponentName - Name of component to search for.
481
     * @param aLibraryName - Name of the library to search for component.
482
     * @return The component object if found, otherwise NULL.
483
     */
484 485
    static LIB_COMPONENT* FindLibraryComponent( const wxString& aComponentName,
                                                const wxString& aLibraryName = wxEmptyString );
486 487

    /**
488 489
     * Function FindLibraryEntry
     * searches all libraries in the list for an entry.
490 491 492
     *
     * The object can be either a component or an alias.
     *
493 494
     * @param aEntryName - Name of entry to search for.
     * @param aLibraryName - Name of the library to search.
495
     * @return The entry object if found, otherwise NULL.
496
     */
497 498
    static LIB_ALIAS* FindLibraryEntry( const wxString& aEntryName,
                                        const wxString& aLibraryName = wxEmptyString );
499 500

    /**
501 502
     * Function RemoveCacheLibrary
     * removes all cache libraries from library list.
503
     */
504
    static void RemoveCacheLibrary();
505

506
    static int GetLibraryCount() { return libraryList.size(); }
507

508
    static CMP_LIBRARY_LIST& GetLibraryList()
509
    {
510
        return libraryList;
511 512
    }

513
    static void SetSortOrder( const wxArrayString& aSortOrder )
514
    {
515
        libraryListSortOrder = aSortOrder;
516 517 518 519
    }

    static wxArrayString& GetSortOrder( void )
    {
520
        return libraryListSortOrder;
521
    }
charras's avatar
charras committed
522 523
};

524 525 526 527

/**
 * Case insensitive library name comparison.
 */
528 529
extern bool operator==( const CMP_LIBRARY& aLibrary, const wxString& aName );
extern bool operator!=( const CMP_LIBRARY& aLibrary, const wxString& aName );
530

charras's avatar
charras committed
531
#endif  //  CLASS_LIBRARY_H