Add ParserConfig class to encapsulate file path settings

include/sdf/CMakeLists.txt

@@ -35,6 +35,7 @@ set (headers
   Noise.hh
   Param.hh
   parser.hh
+  ParserConfig.hh
   Pbr.hh
   Physics.hh
   Plane.hh

include/sdf/ParserConfig.hh

@@ -0,0 +1,130 @@
+/*
+ * Copyright 2020 Open Source Robotics Foundation
+ *
+ * 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.
+ *
+ */
+
+#ifndef SDF_PARSER_CONFIG_HH_
+#define SDF_PARSER_CONFIG_HH_
+
+#include <functional>
+#include <map>
+#include <string>
+#include <vector>
+
+#include <sdf/Error.hh>
+#include "sdf/sdf_config.h"
+#include "sdf/system_util.hh"
+
+namespace sdf
+{
+inline namespace SDF_VERSION_NAMESPACE
+{
+// Forward declare private data class.
+class ParserConfigPrivate;
+
+/// This class contains configuration options for the libsdformat parser.
+///
+/// The configuration options include:
+///   * A callback function used to locate a file from a given URI
+///   * A map from URI schemes to search directories
+///
+/// For backward compatibility, the functions sdf::setFindCallback() and
+/// sdf::addURIPath() update a singleton ParserConfig object, which can be
+/// retrieved by ParserConfig::GlobalConfig().
+///
+/// The functions sdf::readFile(), sdf::readString(), and \ref Root::Load
+/// "sdf::Root::Load()" have overloads that take a ParserConfig object. If
+/// the ParserConfig object is omitted, these functions will use the singleton
+/// ParserConfig object.
+///
+/// Example:
+/// To set an additional URI scheme search directory without affecting the
+/// global config,
+///
+/// \code{.cpp}
+///   // Copy the global config
+///   sdf::ParserConfig config = ParserConfig::GlobalConfig();
+///
+///   // Add the new scheme to the config
+///   config.AddURIPath("newScheme://", "path/to/directory");
+///
+///   // Use the new config when loading a new SDFormat file
+///   sdf::Root root;
+///   root.Load("path/to/file.sdf", config);
+/// \endcode
+class SDFORMAT_VISIBLE ParserConfig
+{
+  /// type alias for the map from URI scheme to search directories
+  public: using SchemeToPathMap =
+          std::map<std::string, std::vector<std::string> >;
+
+  /// \brief Default constructor
+  public: ParserConfig();
+
+  /// \brief Copy constructor
+  /// \param[in] _config ParserConfig to copy.
+  public: ParserConfig(const ParserConfig &_config);
+
+  /// \brief Move constructor
+  /// \param[in] _config ParserConfig to move.
+  public: ParserConfig(ParserConfig &&_config) noexcept;
+
+  /// \brief Move assignment operator.
+  /// \param[in] _config ParserConfig to move.
+  /// \return Reference to this.
+  public: ParserConfig &operator=(ParserConfig &&_config) noexcept;
+
+  /// \brief Copy assignment operator.
+  /// \param[in] _config ParserConfig to copy.
+  /// \return Reference to this.
+  public: ParserConfig &operator=(const ParserConfig &_config);
+
+  /// \brief Destructor
+  public: ~ParserConfig();
+
+  /// Mutable access to a singleton ParserConfig that serves as the global
+  /// ParserConfig object for all parsing operations
+  /// \return A mutable reference to the singleton ParserConfig object
+  public: static ParserConfig &GlobalConfig();
+
+  /// \brief Get the find file callback function
+  /// \return Immutable reference to the find file callback function
+  public: const std::function<std::string(const std::string &)> &
+          FindFileCallback() const;
+
+  /// \brief Set the callback to use when libsdformat can't find a file.
+  /// The callback should return a complete path to the requested file, or
+  /// and empty string if the file was not found in the callback.
+  /// \param[in] _cb The callback function.
+  public: void SetFindCallback(
+              std::function<std::string(const std::string &)> _cb);
+
+  /// \brief Get the URI scheme to search directories map
+  /// \return Immutable reference to the URI scheme to search directories map
+  public: const SchemeToPathMap &URIPathMap() const;
+
+  /// \brief Associate paths to a URI.
+  /// Example paramters: "model://", "/usr/share/models:~/.gazebo/models"
+  /// \param[in] _uri URI that will be mapped to _path
+  /// \param[in] _path Colon separated set of paths.
+  public: void AddURIPath(const std::string &_uri, const std::string &_path);
+
+  /// \brief Private data pointer.
+  private: ParserConfigPrivate *dataPtr;
+};
+}
+}
+
+#endif

include/sdf/Root.hh

@@ -83,13 +83,31 @@ namespace sdf
     /// an error code and message. An empty vector indicates no error.
     public: Errors Load(const std::string &_filename);
 
+    /// \brief Parse the given SDF file, and generate objects based on types
+    /// specified in the SDF file.
+    /// \param[in] _filename Name of the SDF file to parse.
+    /// \param[in] _config Custom parser configuration
+    /// \return Errors, which is a vector of Error objects. Each Error includes
+    /// an error code and message. An empty vector indicates no error.
+    public: Errors Load(
+                const std::string &_filename, const ParserConfig &_config);
+
     /// \brief Parse the given SDF string, and generate objects based on types
     /// specified in the SDF file.
     /// \param[in] _sdf SDF string to parse.
     /// \return Errors, which is a vector of Error objects. Each Error includes
     /// an error code and message. An empty vector indicates no error.
     public: Errors LoadSdfString(const std::string &_sdf);
 
+    /// \brief Parse the given SDF string, and generate objects based on types
+    /// specified in the SDF file.
+    /// \param[in] _sdf SDF string to parse.
+    /// \param[in] _config Custom parser configuration
+    /// \return Errors, which is a vector of Error objects. Each Error includes
+    /// an error code and message. An empty vector indicates no error.
+    public: Errors LoadSdfString(
+                const std::string &_sdf, const ParserConfig &_config);
+
     /// \brief Parse the given SDF pointer, and generate objects based on types
     /// specified in the SDF file.
     /// \param[in] _sdf SDF pointer to parse.

include/sdf/SDFImpl.hh

@@ -21,11 +21,12 @@
 #include <memory>
 #include <string>
 
-#include "sdf/Param.hh"
 #include "sdf/Element.hh"
+#include "sdf/Param.hh"
+#include "sdf/ParserConfig.hh"
+#include "sdf/Types.hh"
 #include "sdf/sdf_config.h"
 #include "sdf/system_util.hh"
-#include "sdf/Types.hh"
 
 #ifdef _WIN32
 // Disable warning C4251 which is triggered by
@@ -64,6 +65,21 @@ namespace sdf
                        bool _searchLocalPath = true,
                        bool _useCallback = false);
 
+  /// \brief Find the absolute path of a file.
+  /// \param[in] _filename Name of the file to find.
+  /// \param[in] _searchLocalPath True to search for the file in the current
+  /// working directory.
+  /// \param[in] _useCallback True to find a file based on a registered
+  /// callback if the file is not found via the normal mechanism.
+  /// \param[in] _config Custom parser configuration
+  /// \return File's full path.
+  SDFORMAT_VISIBLE
+  std::string findFile(const std::string &_filename,
+                       bool _searchLocalPath,
+                       bool _useCallback,
+                       const ParserConfig &_config);
+
+
   /// \brief Associate paths to a URI.
   /// Example paramters: "model://", "/usr/share/models:~/.gazebo/models"
   /// \param[in] _uri URI that will be mapped to _path
@@ -78,7 +94,6 @@ namespace sdf
   SDFORMAT_VISIBLE
   void setFindCallback(std::function<std::string (const std::string &)> _cb);
 
-
   /// \brief Base SDF class
   class SDFORMAT_VISIBLE SDF
   {