io_mgr.h 20 KB
Newer Older
1 2 3 4 5 6
#ifndef IO_MGR_H_
#define IO_MGR_H_

/*
 * This program source code file is part of KICAD, a free EDA CAD application.
 *
7
 * Copyright (C) 2011-2012 SoftPLC Corporation, Dick Hollenbeck <dick@softplc.com>
8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28
 * Copyright (C) 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
 */

#include <richio.h>
29 30
#include <map>

31 32 33

class BOARD;
class PLUGIN;
34
class MODULE;
35

36 37 38 39 40
/**
 * Class PROPERTIES
 * is a name/value tuple with unique names and optional values.  The names
 * may be iterated alphabetically.
 */
41
class PROPERTIES : public std::map< std::string, UTF8 >
42 43
{
    // alphabetical tuple of name and value hereby defined.
44 45 46 47 48 49 50

public:

    /**
     * Function Value
     * fetches a property by aName and returns true if that property was found, else false.
     * If not found, aFetchedValue is not touched.
51 52 53 54
     * @param aName is the property or option to look for.
     * @param aFetchedValue is where to put the value of the property if it
     *  exists and aFetchedValue is not NULL.
     * @return bool - true if property is found, else false.
55
     */
56
    bool Value( const char* aName, UTF8* aFetchedValue = NULL ) const;
57 58
};

59 60 61

/**
 * Class IO_MGR
62
 * is a factory which returns an instance of a PLUGIN.
63 64 65 66 67 68 69 70 71 72 73 74
 */
class IO_MGR
{
public:

    /**
     * Enum PCB_FILE_T
     * is a set of file types that the IO_MGR knows about, and for which there
     * has been a plugin written.
     */
    enum PCB_FILE_T
    {
75 76
        LEGACY,         ///< Legacy Pcbnew file formats prior to s-expression.
        KICAD,          ///< S-expression Pcbnew file format.
77
        EAGLE,
78
        PCAD,
79 80
        GEDA_PCB,       ///< Geda PCB file formats.
        GITHUB,         ///< Read only http://github.com repo holding pretty footprints
81

82 83
        // add your type here.

84 85 86 87 88 89 90 91
        // ALTIUM,
        // etc.
    };

    /**
     * Function PluginFind
     * returns a PLUGIN which the caller can use to import, export, save, or load
     * design documents.  The returned PLUGIN, may be reference counted, so please
92 93
     * call PluginRelease() when you are done using the returned PLUGIN.  It may or
     * may not be code running from a DLL/DSO.
94 95 96 97 98 99 100 101 102 103 104 105
     *
     * @param aFileType is from PCB_FILE_T and tells which plugin to find.
     *
     * @return PLUGIN* - the plugin corresponding to aFileType or NULL if not found.
     *  Caller owns the returned object, and must call PluginRelease when done using it.
     */
    static PLUGIN* PluginFind( PCB_FILE_T aFileType );

    /**
     * Function PluginRelease
     * releases a PLUGIN back to the system, and may cause it to be unloaded from memory.
     *
106 107
     * @param aPlugin is the one to be released, and which is no longer usable
     *  after calling this.
108 109 110 111 112 113 114
     */
    static void PluginRelease( PLUGIN* aPlugin );

    /**
     * Function ShowType
     * returns a brief name for a plugin, given aFileType enum.
     */
115
    static const wxString ShowType( PCB_FILE_T aFileType );
116

Dick Hollenbeck's avatar
Dick Hollenbeck committed
117 118 119 120 121 122
    /**
     * Function EnumFromStr
     * returns the PCB_FILE_T from the corresponding plugin type name: "kicad", "legacy", etc.
     */
    static PCB_FILE_T EnumFromStr( const wxString& aFileType );

123 124 125 126 127 128 129 130 131 132
    /**
     * Function GetFileExtension
     * returns the file extension for \a aFileType.
     *
     * @param aFileType The #PCB_FILE_T type.
     * @return A wxString object containing the file extension for \a aFileType or an empty
     *         string if \a aFileType is invalid.
     */
    static const wxString GetFileExtension( PCB_FILE_T aFileType );

133 134 135 136 137 138
    /**
     * Function GuessPluginTypeFromLibPath
     * returns a plugin type given a footprint library's libPath.
     */
    static PCB_FILE_T GuessPluginTypeFromLibPath( const wxString& aLibPath );

139 140
    /**
     * Function Load
141 142 143
     * finds the requested PLUGIN and if found, calls the PLUGIN->Load(..) funtion
     * on it using the arguments passed to this function.  After the PLUGIN->Load()
     * function returns, the PLUGIN is Released() as part of this call.
144
     *
145
     * @param aFileType is the PCB_FILE_T of file to load.
146 147 148 149
     *
     * @param aFileName is the name of the file to load.
     *
     * @param aAppendToMe is an existing BOARD to append to, use NULL if fresh
150
     *  board load is wanted.
151 152
     *
     * @param aProperties is an associative array that allows the caller to
153
     *  pass additional tuning parameters to the PLUGIN.
154 155 156
     *
     * @return BOARD* - caller owns it, never NULL because exception thrown if error.
     *
157
     * @throw IO_ERROR if the PLUGIN cannot be found, file cannot be found,
158 159 160
     *  or file cannot be loaded.
     */
    static BOARD* Load( PCB_FILE_T aFileType, const wxString& aFileName,
161
                        BOARD* aAppendToMe = NULL, const PROPERTIES* aProperties = NULL );
162

163 164
    /**
     * Function Save
165
     * will write either a full aBoard to a storage file in a format that this
166 167 168
     * implementation knows about, or it can be used to write a portion of
     * aBoard to a special kind of export file.
     *
169 170
     * @param aFileType is the PCB_FILE_T of file to save.
     *
171 172 173
     * @param aFileName is the name of a file to save to on disk.
     * @param aBoard is the BOARD document (data tree) to save or export to disk.
     *
174 175 176 177
     * @param aBoard is the in memory document tree from which to extract information
     *  when writing to \a aFileName.  The caller continues to own the BOARD, and
     *  the plugin should refrain from modifying the BOARD if possible.
     *
178 179 180
     * @param aProperties is an associative array that can be used to tell the
     *  saver how to save the file, because it can take any number of
     *  additional named tuning arguments that the plugin is known to support.
181 182
     *  The caller continues to own this object (plugin may not delete it), and
     *  plugins should expect it to be optionally NULL.
183 184 185 186
     *
     * @throw IO_ERROR if there is a problem saving or exporting.
     */
    static void Save( PCB_FILE_T aFileType, const wxString& aFileName,
187
                      BOARD* aBoard, const PROPERTIES* aProperties = NULL );
188 189 190 191 192 193 194 195
};


/**
 * Class PLUGIN
 * is a base class that BOARD loading and saving plugins should derive from.
 * Implementations can provide either Load() or Save() functions, or both.
 * PLUGINs throw exceptions, so it is best that you wrap your calls to these
196 197 198
 * functions in a try catch block.  Plugins throw exceptions because it is illegal
 * for them to have any user interface calls in them whatsoever, i.e. no windowing
 * or screen printing at all.
199 200 201 202
 *
 * <pre>
 *   try
 *   {
203 204 205
 *        IO_MGR::Load(...);
 *   or
 *        IO_MGR::Save(...);
206
 *   }
207
 *   catch( const IO_ERROR& ioe )
208 209 210 211 212 213 214 215 216
 *   {
 *        // grab text from ioe, show in error window.
 *   }
 * </pre>
 */
class PLUGIN
{
public:

217 218
    //-----<PUBLIC PLUGIN API>-------------------------------------------------

219 220 221 222
    /**
     * Function PluginName
     * returns a brief hard coded name for this PLUGIN.
     */
223
    virtual const wxString PluginName() const = 0;
224 225 226 227 228

    /**
     * Function GetFileExtension
     * returns the file extension for the PLUGIN.
     */
229
    virtual const wxString GetFileExtension() const = 0;
230 231 232

    /**
     * Function Load
233 234 235
     * loads information from some input file format that this PLUGIN implementation
     * knows about, into either a new BOARD or an existing one. This may be used to load an
     * entire new BOARD, or to augment an existing one if @a aAppendToMe is not NULL.
236
     *
237
     * @param aFileName is the name of the file to use as input and may be foreign in
238 239
     *  nature or native in nature.
     *
240 241
     * @param aAppendToMe is an existing BOARD to append to, but if NULL then
     *   this means "do not append, rather load anew".
242 243 244
     *
     * @param aProperties is an associative array that can be used to tell the
     *  loader how to load the file, because it can take any number of
245 246 247 248
     *  additional named arguments that the plugin is known to support. These are
     *  tuning parameters for the import or load.  The caller continues to own
     *  this object (plugin may not delete it), and plugins should expect it to
     *  be optionally NULL.
249
     *
250 251
     * @return BOARD* - the successfully loaded board, or the same one as aAppendToMe
     *  if aAppendToMe was not NULL, and caller owns it.
252 253
     *
     * @throw IO_ERROR if there is a problem loading, and its contents should
254 255
     *  say what went wrong, using line number and character offsets of the
     *  input file if possible.
256
     */
257
    virtual BOARD* Load( const wxString& aFileName, BOARD* aAppendToMe,
258
                         const PROPERTIES* aProperties = NULL );
259 260 261

    /**
     * Function Save
262
     * will write @a aBoard to a storage file in a format that this
263
     * PLUGIN implementation knows about, or it can be used to write a portion of
264 265 266
     * aBoard to a special kind of export file.
     *
     * @param aFileName is the name of a file to save to on disk.
267 268 269 270
     *
     * @param aBoard is the class BOARD in memory document tree from which to
     *  extract information when writing to \a aFileName.  The caller continues to
     *  own the BOARD, and the plugin should refrain from modifying the BOARD if possible.
271 272 273
     *
     * @param aProperties is an associative array that can be used to tell the
     *  saver how to save the file, because it can take any number of
274 275 276
     *  additional named tuning arguments that the plugin is known to support.
     *  The caller continues to own this object (plugin may not delete it),
     *  and plugins should expect it to be optionally NULL.
277
     *
278
     * @throw IO_ERROR if there is a problem saving or exporting.
279
     */
280
    virtual void Save( const wxString& aFileName, BOARD* aBoard,
281
                       const PROPERTIES* aProperties = NULL );
282

283 284
    //-----<Footprint Stuff>-----------------------------

285 286 287 288
    /**
     * Function FootprintEnumerate
     * returns a list of footprint names contained within the library at @a aLibraryPath.
     *
289 290
     * @param aLibraryPath is a locator for the "library", usually a directory, file,
     *   or URL containing several footprints.
291 292
     *
     * @param aProperties is an associative array that can be used to tell the
293
     *  plugin anything needed about how to perform with respect to @a aLibraryPath.
294 295 296 297 298 299 300 301
     *  The caller continues to own this object (plugin may not delete it), and
     *  plugins should expect it to be optionally NULL.
     *
     * @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.
     */
302
    virtual wxArrayString FootprintEnumerate( const wxString& aLibraryPath,
303
            const PROPERTIES* aProperties = NULL );
304 305 306

    /**
     * Function FootprintLoad
307
     * loads a footprint having @a aFootprintName from the @a aLibraryPath containing
308 309
     * a library format that this PLUGIN knows about.
     *
310 311
     * @param aLibraryPath is a locator for the "library", usually a directory, file,
     *   or URL containing several footprints.
312 313 314 315
     *
     * @param aFootprintName is the name of the footprint to load.
     *
     * @param aProperties is an associative array that can be used to tell the
316
     *  loader implementation to do something special, because it can take any number of
317 318 319 320
     *  additional named tuning arguments that the plugin is known to support.
     *  The caller continues to own this object (plugin may not delete it), and
     *  plugins should expect it to be optionally NULL.
     *
321
     * @return  MODULE* - if found caller owns it, else NULL if not found.
322
     *
323 324
     * @throw   IO_ERROR if the library cannot be found or read.  No exception
     *          is thrown in the case where aFootprintName cannot be found.
325 326
     */
    virtual MODULE* FootprintLoad( const wxString& aLibraryPath, const wxString& aFootprintName,
327
            const PROPERTIES* aProperties = NULL );
328 329 330

    /**
     * Function FootprintSave
331 332
     * will write @a aModule to an existing library located at @a aLibraryPath.
     * If a footprint by the same name already exists, it is replaced.
333
     *
334 335
     * @param aLibraryPath is a locator for the "library", usually a directory, file,
     *   or URL containing several footprints.
336
     *
337 338
     * @param aFootprint is what to store in the library. The caller continues
     *    to own the footprint after this call.
339 340
     *
     * @param aProperties is an associative array that can be used to tell the
341
     *  saver how to save the footprint, because it can take any number of
342 343 344 345 346 347
     *  additional named tuning arguments that the plugin is known to support.
     *  The caller continues to own this object (plugin may not delete it), and
     *  plugins should expect it to be optionally NULL.
     *
     * @throw IO_ERROR if there is a problem saving.
     */
348
    virtual void FootprintSave( const wxString& aLibraryPath, const MODULE* aFootprint,
349
            const PROPERTIES* aProperties = NULL );
350 351 352

    /**
     * Function FootprintDelete
353
     * deletes @a aFootprintName from the library at @a aLibraryPath.
354
     *
355 356
     * @param aLibraryPath is a locator for the "library", usually a directory, file,
     *   or URL containing several footprints.
357
     *
358
     * @param aFootprintName is the name of a footprint to delete from the specified library.
359
     *
360
     * @param aProperties is an associative array that can be used to tell the
361
     *  library delete function anything special, because it can take any number of
362 363 364 365
     *  additional named tuning arguments that the plugin is known to support.
     *  The caller continues to own this object (plugin may not delete it), and
     *  plugins should expect it to be optionally NULL.
     *
366 367
     * @throw IO_ERROR if there is a problem finding the footprint or the library, or deleting it.
     */
368 369
    virtual void FootprintDelete( const wxString& aLibraryPath,
            const wxString& aFootprintName, const PROPERTIES* aProperties = NULL );
370 371

    /**
372 373 374 375 376
     * Function FootprintLibCreate
     * creates a new empty footprint library at @a aLibraryPath empty.  It is an
     * error to attempt to create an existing library or to attempt to create
     * on a "read only" location.
     *
377 378
     * @param aLibraryPath is a locator for the "library", usually a directory, file,
     *   or URL containing several footprints.
379 380 381 382 383 384 385 386 387
     *
     * @param aProperties is an associative array that can be used to tell the
     *  library create function anything special, because it can take any number of
     *  additional named tuning arguments that the plugin is known to support.
     *  The caller continues to own this object (plugin may not delete it), and
     *  plugins should expect it to be optionally NULL.
     *
     * @throw IO_ERROR if there is a problem finding the library, or creating it.
     */
388
    virtual void FootprintLibCreate( const wxString& aLibraryPath, const PROPERTIES* aProperties = NULL );
389 390 391

    /**
     * Function FootprintLibDelete
392 393 394
     * deletes an existing footprint library and returns true, or if library does not
     * exist returns false, or throws an exception if library exists but is read only or
     * cannot be deleted for some other reason.
395 396 397 398 399
     *
     * @param aLibraryPath is a locator for the "library", usually a directory
     *   or file which will contain footprints.
     *
     * @param aProperties is an associative array that can be used to tell the
400 401 402 403
     *  library delete implementation function anything special, because it can
     *  take any number of additional named tuning arguments that the plugin is
     *  known to support. The caller continues to own this object (plugin may
     *  not delete it), and plugins should expect it to be optionally NULL.
404
     *
405 406 407
     * @return bool - true if library deleted, false if library did not exist.
     *
     * @throw IO_ERROR if there is a problem deleting an existing library.
408
     */
409
    virtual bool FootprintLibDelete( const wxString& aLibraryPath, const PROPERTIES* aProperties = NULL );
410 411 412

    /**
     * Function IsFootprintLibWritable
413 414
     * returns true iff the library at @a aLibraryPath is writable.  (Often
     * system libraries are read only because of where they are installed.)
415
     *
416 417 418
     * @param aLibraryPath is a locator for the "library", usually a directory, file,
     *   or URL containing several footprints.
     *
419
     * @throw IO_ERROR if no library at aLibraryPath exists.
420
     */
421
    virtual bool IsFootprintLibWritable( const wxString& aLibraryPath );
422

423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450
    /**
     * Function FootprintLibOptions
     * appends supported PLUGIN options to @a aListToAppenTo along with
     * internationalized descriptions.  Options are typically appended so
     * that a derived PLUGIN can call its base class
     * function by the same name first, thus inheriting options declared there.
     * (Some base class options could pertain to all Footprint*() functions
     * in all derived PLUGINs.)  Note that since aListToAppendTo is a PROPERTIES
     * object, all options will be unique and last guy wins.
     *
     * @param aListToAppendTo holds a tuple of
     * <dl>
        <dt>option</dt>
        <dd>This eventually is what shows up into the fp-lib-table "options"
            field, possibly combined with others.</dd>
        <dt>internationalized description</dt>
        <dd>The internationalized description is displayed in DIALOG_FP_PLUGIN_OPTIONS.
     *      It may be multi-line and be quite explanatory of the option.</dd>
       </dl>
     * <br>
     *  In the future perhaps @a aListToAppendTo evolves to something capable of also
     *  holding a wxValidator for the cells in said dialog:
     *  http://forums.wxwidgets.org/viewtopic.php?t=23277&p=104180.
        This would require a 3 column list, and introducing wx GUI knowledge to
        PLUGIN, which has been avoided to date.
     */
    virtual void FootprintLibOptions( PROPERTIES* aListToAppendTo ) const;

451
    //-----</PUBLIC PLUGIN API>------------------------------------------------
Dick Hollenbeck's avatar
Dick Hollenbeck committed
452

453

454 455
    /*  The compiler writes the "zero argument" constructor for a PLUGIN
        automatically if you do not provide one. If you decide you need to
456 457
        provide a zero argument constructor of your own design, that is allowed.
        It must be public, and it is what the IO_MGR uses.  Parameters may be
458 459
        passed into a PLUGIN via the PROPERTIES variable for any of the public
        API functions which take one.
460 461
    */

462 463 464 465 466
    virtual ~PLUGIN()
    {
        //printf( "~%s", __func__ );
    };

Dick Hollenbeck's avatar
Dick Hollenbeck committed
467 468 469 470 471 472 473 474 475 476

    /**
     * Class RELEASER
     * releases a PLUGIN in the context of a potential thrown exception, through
     * its destructor.
     */
    class RELEASER
    {
        PLUGIN* plugin;

477 478 479
        // private assignment operator so it's illegal
        RELEASER& operator=( RELEASER& aOther ) { return *this; }

480 481 482
        // private copy constructor so it's illegal
        RELEASER( const RELEASER& aOther ) {}

Dick Hollenbeck's avatar
Dick Hollenbeck committed
483 484 485 486 487 488 489 490 491
    public:
        RELEASER( PLUGIN* aPlugin = NULL ) :
            plugin( aPlugin )
        {
        }

        ~RELEASER()
        {
            if( plugin )
492 493 494 495 496 497 498 499 500 501 502 503 504 505
                release();
        }

        void release()
        {
            IO_MGR::PluginRelease( plugin );
            plugin = NULL;
        }

        void set( PLUGIN* aPlugin )
        {
            if( plugin )
                release();
            plugin = aPlugin;
Dick Hollenbeck's avatar
Dick Hollenbeck committed
506 507
        }

508
        operator PLUGIN* () const
Dick Hollenbeck's avatar
Dick Hollenbeck committed
509 510 511 512
        {
            return plugin;
        }

513
        PLUGIN* operator -> () const
Dick Hollenbeck's avatar
Dick Hollenbeck committed
514 515 516 517
        {
            return plugin;
        }
    };
518 519
};

520
#endif // IO_MGR_H_