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