Drake
find_resource.h
Go to the documentation of this file.
1 #pragma once
2 
3 #include <string>
4 #include <vector>
5 
9 
10 namespace drake {
11 
12 /// Models the outcome of drake::FindResource. After a call to FindResource,
13 /// typical calling code would use get_absolute_path_or_throw().
14 /// Alternatively, get_absolute_path() will return an `optional<string>`, which
15 /// can be manually checked to contain a value before using the path. If the
16 /// resource was not found, get_error_message() will contain an error message.
17 ///
18 /// For a given FindResourceResult instance, exactly one of get_absolute_path()
19 /// or get_error_message() will contain a value. (Similarly, exactly one of
20 /// them will not contain a value.)
22  public:
24 
25  /// Returns the absolute path to the resource, iff the resource was found.
27 
28  /// Either returns the get_absolute_path() iff the resource was found,
29  /// or else throws runtime_error.
30  std::string get_absolute_path_or_throw() const;
31 
32  /// Returns the error message, iff the resource was not found.
33  /// The string will never be empty; only the optional can be empty.
35 
36  /// Returns the resource_path asked of FindResource.
37  /// (This may be empty only in the make_empty() case.)
38  std::string get_resource_path() const;
39 
40  /// Returns a success result (the requested resource was found).
41  /// @pre neither string parameter is empty
42  /// @param resource_path the value passed to FindResource
43  /// @param base_path an absolute base path that precedes resource_path
45  std::string resource_path, std::string absolute_path);
46 
47  /// Returns an error result (the requested resource was NOT found).
48  /// @pre neither string parameter is empty
49  /// @param resource_path the value passed to FindResource
51  std::string resource_path, std::string error_message);
52 
53  /// Returns an empty error result (no requested resource).
55 
56  private:
57  FindResourceResult() = default;
58  void CheckInvariants();
59 
60  // The path as requested by the user.
61  std::string resource_path_;
62 
63  // The absolute path where resource_path was found, if success.
64  optional<std::string> absolute_path_;
65 
66  // An error message, permitted to be present only when base_path is empty.
67  //
68  // All three of resource_path, base_path, and error_message can be empty
69  // (e.g., a default-constructed and/or moved-from object), which represents
70  // resource-not-found along with an unspecified non-empty default error
71  // message from get_error_message().
72  optional<std::string> error_message_;
73 };
74 
75 
76 
77 /// Adds a path in which resources are searched in a persistent variable. Paths
78 /// are accumulated each time this function is called. It is searched after the
79 /// path given by the environment variable but before the path that can be
80 /// found with the sentinel `.drake-resource-sentinel`. This can be used to
81 /// find data in installed distributions of drake (or in `pydrake`).
82 void AddResourceSearchPath(std::string root_directory);
83 
84 /// Gets current root directory value from a persistent variable.
85 std::vector<std::string> GetResourceSearchPaths();
86 
87 /// Attempts to locate a Drake resource named by the given @p resource_path.
88 /// The @p resource_path refers to the relative path within the Drake
89 /// repository, e.g., `drake/examples/pendulum/Pendulum.urdf`. Paths that do
90 /// not start with "drake/" will return a failed result.
91 ///
92 /// The search scans for the resource in the following places and in
93 /// the following order: 1) in the DRAKE_RESOURCE_ROOT environment variable
94 /// 2) in the directories specified by `AddResourceSearchPath()` and 3) in the
95 /// drake source workspace. If all of these are unavailable, or do not have the
96 /// then it will return a failed result.
97 FindResourceResult FindResource(std::string resource_path);
98 
99 /// Convenient wrapper for querying FindResource(resource_path) followed by
100 /// FindResourceResult::get_absolute_path_or_throw().
101 std::string FindResourceOrThrow(std::string resource_path);
102 
103 /// The name of the environment variable that provides the first place where
104 /// FindResource attempts to look. The environment variable is allowed to be
105 /// unset or empty; in that case, FindResource will attempt to use other
106 /// locations without complaint.
107 ///
108 /// The value is guaranteed to be "DRAKE_RESOURCE_ROOT". (For some users, it
109 /// may be easier to hard-code a value than refer to this constant.)
110 extern const char* const kDrakeResourceRootEnvironmentVariableName;
111 
112 } // namespace drake
const char *const kDrakeResourceRootEnvironmentVariableName
The name of the environment variable that provides the first place where FindResource attempts to loo...
Definition: find_resource.cc:165
static FindResourceResult make_empty()
Returns an empty error result (no requested resource).
Definition: find_resource.cc:79
Definition: automotive_demo.cc:88
std::string FindResourceOrThrow(std::string resource_path)
Convenient wrapper for querying FindResource(resource_path) followed by FindResourceResult::get_absol...
Definition: find_resource.cc:239
static FindResourceResult make_error(std::string resource_path, std::string error_message)
Returns an error result (the requested resource was NOT found).
Definition: find_resource.cc:68
Result FindResource(string resource_path)
Attempts to locate a Drake resource named by the given resource_path.
Definition: find_resource.cc:187
std::string get_resource_path() const
Returns the resource_path asked of FindResource.
Definition: find_resource.cc:53
std::string get_absolute_path_or_throw() const
Either returns the get_absolute_path() iff the resource was found, or else throws runtime_error...
Definition: find_resource.cc:24
stx::optional< T > optional
Definition: drake_optional.h:14
optional< std::string > get_absolute_path() const
Returns the absolute path to the resource, iff the resource was found.
Definition: find_resource.cc:19
#define DRAKE_DEFAULT_COPY_AND_MOVE_AND_ASSIGN(Classname)
DRAKE_DEFAULT_COPY_AND_MOVE_AND_ASSIGN defaults the special member functions for copy-construction, copy-assignment, move-construction, and move-assignment.
Definition: drake_copyable.h:57
Provides Drake&#39;s assertion implementation.
Provides drake::optional as an alias for the appropriate implementation of std::optional or std::expe...
optional< std::string > get_error_message() const
Returns the error message, iff the resource was not found.
Definition: find_resource.cc:36
Models the outcome of drake::FindResource.
Definition: find_resource.h:21
std::vector< string > GetResourceSearchPaths()
Gets current root directory value from a persistent variable.
Definition: find_resource.cc:179
static FindResourceResult make_success(std::string resource_path, std::string absolute_path)
Returns a success result (the requested resource was found).
Definition: find_resource.cc:57
Provides careful macros to selectively enable or disable the special member functions for copy-constr...
void AddResourceSearchPath(string search_path)
Adds a path in which resources are searched in a persistent variable.
Definition: find_resource.cc:183