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 /// Adds a path in which resources are searched in a persistent variable. Paths
76 /// are accumulated each time this function is called. It is searched after the
77 /// path given by the environment variable but before the path that can be
78 /// found with the sentinel .drake-resource-sentinel. This can be used to
79 /// find data in installed distributions of drake (or in pydrake). The given
80 /// path must be absolute or else throws runtime_error.
81 void AddResourceSearchPath(std::string root_directory);
82
83 /// Gets current root directory value from a persistent variable.
84 std::vector<std::string> GetResourceSearchPaths();
85
86 /// Attempts to locate a Drake resource named by the given @p resource_path.
87 /// The @p resource_path refers to the relative path within the Drake source
88 /// repository, prepended with drake/. For example, to find the source
89 /// file examples/pendulum/Pendulum.urdf, the @p resource_path would be
90 /// drake/examples/pendulum/Pendulum.urdf. Paths that do not start with
91 /// drake/ will return a failed result.
92 ///
93 /// The search scans for the resource in the following places and in
94 /// the following order: 1) in the DRAKE_RESOURCE_ROOT environment variable
95 /// 2) in the directories specified by AddResourceSearchPath() and 3) in the
96 /// drake source workspace. If all of these are unavailable, or do not have the
97 /// resource, then it will return a failed result.
98 FindResourceResult FindResource(std::string resource_path);
99
100 /// Convenient wrapper for querying FindResource(resource_path) followed by
101 /// FindResourceResult::get_absolute_path_or_throw().
102 std::string FindResourceOrThrow(std::string resource_path);
103
104 /// The name of the environment variable that provides the first place where
105 /// FindResource attempts to look. The environment variable is allowed to be
106 /// unset or empty; in that case, FindResource will attempt to use other
107 /// locations without complaint.
108 ///
109 /// The value is guaranteed to be "DRAKE_RESOURCE_ROOT". (For some users, it
110 /// may be easier to hard-code a value than refer to this constant.)
111 ///
112 /// When the environment variable is set, resources are sought in relation to
113 /// it by appending the FindResource() resource_path to the environment
114 /// variable (with an intermediate / as appropriate). For example, if the
115 /// resource_path is drake/examples/pendulum/Pendulum.urdf and the
116 /// DRAKE_RESOURCE_ROOT is set to /home/someuser/foo then the resource will
117 /// be sought at /home/someuser/foo/drake/examples/pendulum/Pendulum.urdf.
118 ///
119 /// The intended use of this variable is to seek resources from an installed
120 /// copy of Drake, in case other methods have failed.
121 extern const char* const kDrakeResourceRootEnvironmentVariableName;
122
123 } // 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:217
static FindResourceResult make_empty()
Returns an empty error result (no requested resource).
Definition: find_resource.cc:80
Definition: automotive_demo.cc:90
std::string FindResourceOrThrow(std::string resource_path)
Convenient wrapper for querying FindResource(resource_path) followed by FindResourceResult::get_absol...
Definition: find_resource.cc:313
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:69
Result FindResource(string resource_path)
Attempts to locate a Drake resource named by the given resource_path.
Definition: find_resource.cc:241
std::string get_resource_path() const
Returns the resource_path asked of FindResource.
Definition: find_resource.cc:54
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:25
stx::optional< T > optional
Definition: drake_optional.h:22
optional< std::string > get_absolute_path() const
Returns the absolute path to the resource, iff the resource was found.
Definition: find_resource.cc:20
#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:37
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:231
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:58
Provides careful macros to selectively enable or disable the special member functions for copy-constr...