Create Importer class to enable import error logging (closes #530).

src/CMakeLists.txt

@@ -51,6 +51,7 @@ set(SOURCE_FILES
   ${CMAKE_CURRENT_SOURCE_DIR}/generator.cpp
   ${CMAKE_CURRENT_SOURCE_DIR}/generatorprofile.cpp
   ${CMAKE_CURRENT_SOURCE_DIR}/importedentity.cpp
+  ${CMAKE_CURRENT_SOURCE_DIR}/importer.cpp
   ${CMAKE_CURRENT_SOURCE_DIR}/importsource.cpp
   ${CMAKE_CURRENT_SOURCE_DIR}/issue.cpp
   ${CMAKE_CURRENT_SOURCE_DIR}/logger.cpp
@@ -77,6 +78,7 @@ set(GIT_API_HEADER_FILES
   ${CMAKE_CURRENT_SOURCE_DIR}/api/libcellml/generator.h
   ${CMAKE_CURRENT_SOURCE_DIR}/api/libcellml/generatorprofile.h
   ${CMAKE_CURRENT_SOURCE_DIR}/api/libcellml/importedentity.h
+  ${CMAKE_CURRENT_SOURCE_DIR}/api/libcellml/importer.h
   ${CMAKE_CURRENT_SOURCE_DIR}/api/libcellml/importsource.h
   ${CMAKE_CURRENT_SOURCE_DIR}/api/libcellml/issue.h
   ${CMAKE_CURRENT_SOURCE_DIR}/api/libcellml/logger.h

src/api/libcellml/importer.h

@@ -0,0 +1,179 @@
+/*
+Copyright libCellML Contributors
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+#pragma once
+
+#include <string>
+
+#include "libcellml/logger.h"
+#include "libcellml/types.h"
+
+namespace libcellml {
+
+/**
+ * @brief The Importer class.
+ *
+ * The Importer class is for representing a CellML Importer.
+ */
+class LIBCELLML_EXPORT Importer: public Logger
+{
+public:
+    ~Importer() override; /**< Destructor */
+    Importer(const Importer &rhs) = delete; /**< Copy constructor */
+    Importer(Importer &&rhs) noexcept = delete; /**< Move constructor */
+    Importer &operator=(Importer rhs) = delete; /**< Assignment operator */
+
+    /**
+     * @brief Create an @c Importer object.
+     *
+     * Factory method to create an @c Importer.  Create a
+     * blank importer with::
+     *
+     *   auto importer = libcellml::Importer::create();
+     *
+     * @return A smart pointer to an @c Importer object.
+     */
+    static ImporterPtr create() noexcept;
+
+    /**
+     * @brief Flatten the @p model.
+     *
+     * Instantiate all imports and removes them from the @p model.
+     * The result is a self-contained model requiring no external
+     * resources and having no imports.
+     *
+     * @sa clone
+     * 
+     * @param model A @c ModelPtr whose imports will be resolved.
+     * 
+     * @return If the operation is successful, a new @c ModelPtr to the flattened model; otherwise, the @c nullptr.
+     */
+    ModelPtr flattenModel(const ModelPtr &model);
+
+    /**
+     * @brief Resolve all imports in the @p model.
+     *
+     * Resolve all @c Component and @c Units imports by loading the models
+     * from local disk through relative URLs.  The @p baseFile is used to determine
+     * the full path to the source model relative to this one.
+     * @param model The @c Model whose imports need resolution.
+     * @param baseFile The @c std::string location on local disk of the source @c Model.
+     */
+    void resolveImports(ModelPtr &model, const std::string &baseFile);
+
+    /**
+     * @brief Return the number of models present in the importer's library.
+     *
+     * @return The number of models present in the importer's library.
+     */
+    size_t libraryCount();
+
+    /**
+     * @brief Retrieve the @c ModelPtr instance from the importer library which was loaded
+     *        from the given @p key.
+     *
+     * @return A @c ModelPtr instance.
+     */
+    ModelPtr library(const std::string &key);
+
+    /**
+     * @brief Get a model from the library at the given @p index.
+     *
+     * Return a reference to the model at the index @p index for this
+     * importer's library. If the index is not valid a @c nullptr is returned. The valid
+     * range for the index is [0, \#library items).
+     *
+     * @param index The index of the model to return.
+     *
+     * @return A reference to the model at the given index on success, @c nullptr otherwise.
+     */
+    ModelPtr library(const size_t &index);
+
+    /**
+     * @brief Manually add a local @c ModelPtr model instance to the importer library,
+     *        using the given @p key as a reference.
+     *
+     * If the given key already exists in the library, the function will return false
+     * and the library will not be changed.
+     * 
+     * @sa replaceModel
+     *
+     * @param model a @c ModelPtr instance to add.
+     * @param key a @c std::string representing the key to associate with the model.
+     *
+     * @return @c true if the model was added, @c false if it was not.
+     */
+    bool addModel(const ModelPtr &model, const std::string &key);
+
+    /**
+     * @brief Replace a @c ModelPtr model instance in the importer library,
+     *        using the given @p key as a reference.
+     *
+     * If the given key already exists in the library, the function will replace its
+     * model with the one supplied, and return @c true.
+     *
+     * If the given key does not exist, the function will return @c false, and
+     * the library will be unchanged.
+     *
+     * @sa addModel.
+     *
+     * @param model a @c ModelPtr instance to replace the current one.
+     * @param key a @c std::string representing the key at which to replace the model.
+     *
+     * @return @c true if the model was replaced, @c false if it was not.
+     */
+    bool replaceModel(const ModelPtr &model, const std::string &key);
+
+    /**
+     * @brief Retrieve the pair of URL key and import reference at the given index.
+     *
+     * This is taken from the list of dependencies for the models which have been resolved,
+     * and is what will break if those external files are ever moved or renamed.
+     *
+     * The first attribute of the returned pair is the URL at which the imported model was
+     * accessed and under which it is now stored in the library as its key, and the second attribute
+     * is the import reference.
+     *
+     * @return a @c std::pair of @c std::strings.
+     */
+    std::pair<std::string, std::string> externalDependency(size_t index) const;
+
+    /**
+     * @brief Get the number of external dependencies in the library.
+     *
+     * Return the number of dependencies for the models which have been resolved by this
+     * importer.
+     *
+     * @return the number of external dependencies.
+     */
+    size_t externalDependencyCount() const;
+
+    /**
+     * @brief Clear the links with other models from all import sources.
+     * 
+     * Clear the links with other models from all import sources.
+     */
+    void clearImports(ModelPtr &model);
+
+private:
+    Importer(); /**< Constructor */
+    explicit Importer(const std::string &name); /**< Constructor with std::string parameter*/
+
+    struct ImporterImpl; /**< Forward declaration for pImpl idiom. */
+    ImporterImpl *mPimpl; /**< Private member to implementation pointer */
+};
+
+} // namespace libcellml

src/api/libcellml/model.h

@@ -307,17 +307,6 @@ class LIBCELLML_EXPORT Model: public ComponentEntity
      */
     bool hasImports() const;
 
-    /**
-     * @brief Resolve all imports in this model.
-     *
-     * Resolve all @c Component and @c Units imports by loading the models
-     * from local disk through relative URLs.  The @p baseFile is used to determine
-     * the full path to the source model relative to this one.
-     *
-     * @param baseFile The @c std::string location on local disk of the source @c Model.
-     */
-    void resolveImports(const std::string &baseFile);
-
     /**
      * @brief Test if this model has unresolved imports.
      *
@@ -338,19 +327,6 @@ class LIBCELLML_EXPORT Model: public ComponentEntity
      */
     ModelPtr clone() const;
 
-    /**
-     * @brief Flatten this model.
-     *
-     * Instantiates all imports and removes them from this model.
-     * The result is a self-contained model requiring no external
-     * resources and having no imports.
-     *
-     * The effects of this method cannot be undone.
-     *
-     * @sa clone
-     */
-    void flatten();
-
     /**
      * @brief Fix @c Variable interfaces throughout the model.
      *

src/api/libcellml/module/libcellml

@@ -27,6 +27,7 @@ limitations under the License.
 #include "libcellml/component.h"
 #include "libcellml/generator.h"
 #include "libcellml/generatorprofile.h"
+#include "libcellml/importer.h"
 #include "libcellml/importsource.h"
 #include "libcellml/issue.h"
 #include "libcellml/logger.h"

src/api/libcellml/types.h

@@ -21,14 +21,16 @@ limitations under the License.
 namespace libcellml {
 
 // General classes.
-class Issue; /**< Forward declaration of Issue class. */
-using IssuePtr = std::shared_ptr<Issue>; /**< Type definition for shared issue pointer. */
 class Generator; /**< Forward declaration of Generator class. */
 using GeneratorPtr = std::shared_ptr<Generator>; /**< Type definition for shared generator pointer. */
 class GeneratorProfile; /**< Forward declaration of GeneratorProfile class. */
 using GeneratorProfilePtr = std::shared_ptr<GeneratorProfile>; /**< Type definition for shared generator variable pointer. */
 class GeneratorVariable; /**< Forward declaration of GeneratorVariable class. */
 using GeneratorVariablePtr = std::shared_ptr<GeneratorVariable>; /**< Type definition for shared generator variable pointer. */
+class Importer; /**< Forward declaration of Importer class. */
+using ImporterPtr = std::shared_ptr<Importer>; /**< Type definition for shared importer pointer. */
+class Issue; /**< Forward declaration of Issue class. */
+using IssuePtr = std::shared_ptr<Issue>; /**< Type definition for shared issue pointer. */
 class Logger; /**< Forward declaration of Parser class. */
 using LoggerPtr = std::shared_ptr<Logger>; /**< Type definition for shared parser pointer. */
 class Parser; /**< Forward declaration of Parser class. */

src/bindings/interface/importer.i

@@ -0,0 +1,58 @@
+%module(package="libcellml") importer
+
+#define LIBCELLML_EXPORT
+
+%import "createconstructor.i"
+%import "logger.i"
+%import "types.i"
+
+%feature("docstring") libcellml::Importer
+"Manages all importing operations between CellML models.";
+
+%feature("docstring") libcellml::Importer::resolveImports
+"Resolves all imports in this model.
+
+Resolves all component and units imports by loading the
+models from local disk through relative URLs. The ``baseFile`` is used to
+determine the full path to the source model relative to this one.";
+
+%feature("docstring") libcellml::Importer::flattenModel
+"Instantiate all imported components and units and return a self-contained model.";
+
+%feature("docstring") libcellml::Importer::libraryCount
+"Returns the number of models loaded into the importer's library."
+
+%feature("docstring") libcellml::Importer::library
+"Returns the model instance stored at the given URL in the library.
+The URL string must be the absolute path to the document, including both the filename
+and the baseFile path."
+
+%feature("docstring") libcellml::Importer::addModel
+"Manually add a local model instance into the library under the URL key provided.
+Returns True if the model was added, and False if the URL key already exists."
+
+%feature("docstring") libcellml::Importer::replaceModel
+"Manually replace an existing library model instance with the one provided.
+Returns True if the URL key is found in the library and the model is added,
+and False if the URL key does not exist."
+
+%feature("docstring") libcellml::Importer::externalDependencyCount
+"Returns the number of external dependencies accessed while resolving all
+the models passed to this importer."
+
+%feature("docstring") libcellml::Importer::externalDependency
+"Returns a pairs of strings at the given index. The first item in the pair is the external URL
+at which imports for models which have been resolved by the importer were accessed (and under
+which are now stored in the library). The second item is the import reference."
+
+%feature("docstring") libcellml::Importer::clearImports
+"Clears the links with other models from all import sources."
+
+%{
+#include "libcellml/importer.h"
+%}
+
+%create_constructor(Importer)
+
+%include "libcellml/types.h"
+%include "libcellml/importer.h"

src/bindings/interface/model.i

@@ -48,13 +48,6 @@ Only the first matching Units is removed and returned.";
 %feature("docstring") libcellml::Model::unitsCount
 "Returns the number of units this model contains.";
 
-%feature("docstring") libcellml::Model::resolveImports
-"Resolves all imports in this model.
-
-Resolves all :class:`Component` and :class:`Units` imports by loading the
-models from local disk through relative urls. The ``baseFile`` is used to
-determine the full path to the source model relative to this one.";
-
 %feature("docstring") libcellml::Model::hasUnresolvedImports
 "Tests if this model has unresolved imports.";
 
@@ -70,9 +63,6 @@ determine the full path to the source model relative to this one.";
 %feature("docstring") libcellml::Model::hasImports
 "Determine if any Component or Units is an import.";
 
-%feature("docstring") libcellml::Model::flatten
-"Instantiate all imported Components and Units to make this model self-contained.";
-
 %feature("docstring") libcellml::Model::fixVariableInterfaces
 "Fix variable interfaces throughout the model.";
 

src/bindings/interface/types.i

@@ -10,6 +10,7 @@ Only meant to be included, shouldn't be passed to cmake as a module!
 %shared_ptr(libcellml::Entity)
 %shared_ptr(libcellml::Generator)
 %shared_ptr(libcellml::GeneratorProfile)
+%shared_ptr(libcellml::Importer)
 %shared_ptr(libcellml::ImportSource)
 %shared_ptr(libcellml::ImportedEntity)
 %shared_ptr(libcellml::Issue)

src/bindings/python/CMakeLists.txt

@@ -24,6 +24,7 @@ set(SWIG_INTERFACE_SRCS
     ../interface/entity.i
     ../interface/generator.i
     ../interface/generatorprofile.i
+    ../interface/importer.i
     ../interface/importsource.i
     ../interface/importedentity.i
     ../interface/issue.i

src/bindings/python/__init__.py

@@ -12,6 +12,7 @@
 from libcellml.generator import Generator
 from libcellml.generator import GeneratorVariable
 from libcellml.generatorprofile import GeneratorProfile
+from libcellml.importer import Importer
 from libcellml.importsource import ImportSource
 from libcellml.issue import Issue
 from libcellml.model import Model