Drake
find_resource.h
Go to the documentation of this file.
1 #pragma once
2 
3 #include <string>
4 #include <vector>
5 
6 #include "drake/common/drake_assert.h"
7 #include "drake/common/drake_copyable.h"
8 #include "drake/common/drake_optional.h"
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`).
80 void AddResourceSearchPath(std::string root_directory);
81 
82 /// Gets current root directory value from a persistent variable.
83 std::vector<std::string> GetResourceSearchPaths();
84 
85 /// Attempts to locate a Drake resource named by the given @p resource_path.
86 /// The @p resource_path refers to the relative path within the Drake source
87 /// repository, prepended with `drake/`. For example, to find the source
88 /// file `examples/pendulum/Pendulum.urdf`, the @p resource_path would be
89 /// `drake/examples/pendulum/Pendulum.urdf`. Paths that do not start with
90 /// `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 /// resource, 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 ///
111 /// When the environment variable is set, resources are sought in relation to
112 /// it by appending the FindResource() `resource_path` to the environment
113 /// variable (with an intermediate `/` as appropriate). For example, if the
114 /// `resource_path` is `drake/examples/pendulum/Pendulum.urdf` and the
115 /// `DRAKE_RESOURCE_ROOT` is set to `/home/someuser/foo` then the resource will
116 /// be sought at `/home/someuser/foo/drake/examples/pendulum/Pendulum.urdf`.
117 ///
118 /// The intended use of this variable is to seek resources from an installed
119 /// copy of Drake, in case other methods have failed.
120 extern const char* const kDrakeResourceRootEnvironmentVariableName;
121 
122 } // 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:198
static FindResourceResult make_empty()
Returns an empty error result (no requested resource).
Definition: find_resource.cc:80
Definition: automotive_demo.cc:89
std::string FindResourceOrThrow(std::string resource_path)
Convenient wrapper for querying FindResource(resource_path) followed by FindResourceResult::get_absol...
Definition: find_resource.cc:279
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:220
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:14
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
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:212
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
void AddResourceSearchPath(string search_path)
Adds a path in which resources are searched in a persistent variable.
Definition: find_resource.cc:216