1//===-- SourceLocationSpec.h ------------------------------------*- C++ -*-===//
2//
3// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4// See https://llvm.org/LICENSE.txt for license information.
5// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
6//
7//===----------------------------------------------------------------------===//
8
9#ifndef LLDB_UTILITY_SOURCELOCATIONSPEC_H
10#define LLDB_UTILITY_SOURCELOCATIONSPEC_H
11
12#include "lldb/Core/Declaration.h"
13#include "lldb/lldb-defines.h"
14
15#include <optional>
16#include <string>
17
18namespace lldb_private {
19
20/// \class SourceLocationSpec SourceLocationSpec.h
21/// "lldb/Core/SourceLocationSpec.h" A source location specifier class.
22///
23/// A source location specifier class that holds a Declaration object containing
24/// a FileSpec with line and column information. The column line is optional.
25/// It also holds search flags that can be fetched by resolvers to look inlined
26/// declarations and/or exact matches.
27class SourceLocationSpec {
28public:
29 /// Constructor.
30 ///
31 /// Takes a \a file_spec with a \a line number and a \a column number. If
32 /// \a column is null or not provided, it is set to std::nullopt.
33 ///
34 /// \param[in] file_spec
35 /// The full or partial path to a file.
36 ///
37 /// \param[in] line
38 /// The line number in the source file.
39 ///
40 /// \param[in] column
41 /// The column number in the line of the source file.
42 ///
43 /// \param[in] check_inlines
44 /// Whether to look for a match in inlined declaration.
45 ///
46 /// \param[in] exact_match
47 /// Whether to look for an exact match.
48 ///
49 explicit SourceLocationSpec(FileSpec file_spec, uint32_t line,
50 std::optional<uint16_t> column = std::nullopt,
51 bool check_inlines = false,
52 bool exact_match = false);
53
54 SourceLocationSpec() = delete;
55
56 /// Convert to boolean operator.
57 ///
58 /// This allows code to check a SourceLocationSpec object to see if it
59 /// contains anything valid using code such as:
60 ///
61 /// \code
62 /// SourceLocationSpec location_spec(...);
63 /// if (location_spec)
64 /// { ...
65 /// \endcode
66 ///
67 /// \return
68 /// A pointer to this object if both the file_spec and the line are valid,
69 /// nullptr otherwise.
70 explicit operator bool() const;
71
72 /// Logical NOT operator.
73 ///
74 /// This allows code to check a SourceLocationSpec object to see if it is
75 /// invalid using code such as:
76 ///
77 /// \code
78 /// SourceLocationSpec location_spec(...);
79 /// if (!location_spec)
80 /// { ...
81 /// \endcode
82 ///
83 /// \return
84 /// Returns \b true if the object has an invalid file_spec or line number,
85 /// \b false otherwise.
86 bool operator!() const;
87
88 /// Equal to operator
89 ///
90 /// Tests if this object is equal to \a rhs.
91 ///
92 /// \param[in] rhs
93 /// A const SourceLocationSpec object reference to compare this object
94 /// to.
95 ///
96 /// \return
97 /// \b true if this object is equal to \a rhs, \b false
98 /// otherwise.
99 bool operator==(const SourceLocationSpec &rhs) const;
100
101 /// Not equal to operator
102 ///
103 /// Tests if this object is not equal to \a rhs.
104 ///
105 /// \param[in] rhs
106 /// A const SourceLocationSpec object reference to compare this object
107 /// to.
108 ///
109 /// \return
110 /// \b true if this object is equal to \a rhs, \b false
111 /// otherwise.
112 bool operator!=(const SourceLocationSpec &rhs) const;
113
114 /// Less than to operator
115 ///
116 /// Tests if this object is less than \a rhs.
117 ///
118 /// \param[in] rhs
119 /// A const SourceLocationSpec object reference to compare this object
120 /// to.
121 ///
122 /// \return
123 /// \b true if this object is less than \a rhs, \b false
124 /// otherwise.
125 bool operator<(const SourceLocationSpec &rhs) const;
126
127 /// Compare two SourceLocationSpec objects.
128 ///
129 /// If \a full is true, then the file_spec, the line and column must match.
130 /// If \a full is false, then only the file_spec and line number for \a lhs
131 /// and \a rhs are compared. This allows a SourceLocationSpec object that have
132 /// no column information to match a SourceLocationSpec objects that have
133 /// column information with matching file_spec and line component.
134 ///
135 /// \param[in] lhs
136 /// A const reference to the Left Hand Side object to compare.
137 ///
138 /// \param[in] rhs
139 /// A const reference to the Right Hand Side object to compare.
140 ///
141 /// \param[in] full
142 /// If true, then the file_spec, the line and column must match for a
143 /// compare to return zero (equal to). If false, then only the file_spec
144 /// and line number for \a lhs and \a rhs are compared, else a full
145 /// comparison is done.
146 ///
147 /// \return -1 if \a lhs is less than \a rhs, 0 if \a lhs is equal to \a rhs,
148 /// 1 if \a lhs is greater than \a rhs
149 static int Compare(const SourceLocationSpec &lhs,
150 const SourceLocationSpec &rhs);
151
152 static bool Equal(const SourceLocationSpec &lhs,
153 const SourceLocationSpec &rhs, bool full);
154
155 /// Dump this object to a Stream.
156 ///
157 /// Dump the object to the supplied stream \a s, starting with the file name,
158 /// then the line number and if available the column number.
159 ///
160 /// \param[in] s
161 /// The stream to which to dump the object description.
162 void Dump(Stream &s) const;
163
164 std::string GetString() const;
165
166 FileSpec GetFileSpec() const { return m_declaration.GetFile(); }
167
168 std::optional<uint32_t> GetLine() const;
169
170 std::optional<uint16_t> GetColumn() const;
171
172 bool GetCheckInlines() const { return m_check_inlines; }
173
174 bool GetExactMatch() const { return m_exact_match; }
175
176protected:
177 Declaration m_declaration;
178 /// Tells if the resolver should look in inlined declaration.
179 bool m_check_inlines;
180 /// Tells if the resolver should look for an exact match.
181 bool m_exact_match;
182};
183
184/// Dump a SourceLocationSpec object to a stream
185Stream &operator<<(Stream &s, const SourceLocationSpec &loc);
186} // namespace lldb_private
187
188#endif // LLDB_UTILITY_SOURCELOCATIONSPEC_H
189

source code of lldb/include/lldb/Core/SourceLocationSpec.h