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:220
static FindResourceResult make_empty()
Returns an empty error result (no requested resource).
Definition: find_resource.cc:81
Definition: automotive_demo.cc:105
std::string FindResourceOrThrow(std::string resource_path)
Convenient wrapper for querying FindResource(resource_path) followed by FindResourceResult::get_absol...
Definition: find_resource.cc:317
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:70
Result FindResource(string resource_path)
Attempts to locate a Drake resource named by the given resource_path.
Definition: find_resource.cc:244
std::string get_resource_path() const
Returns the resource_path asked of FindResource.
Definition: find_resource.cc:55
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:26
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:21
#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:38
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:234
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:59
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:238