Readability nit: rename source to source_view

Summary:
Motivation: `source` is overly broad and confusing, whereas `source_view` better captures its nature.
Note that, for now, both names are still valid and aliases of each other, to allow for a migration period.

Also added some documentation.

Reviewed By: vitaut

Differential Revision: D79928195

fbshipit-source-id: f40a6da51b5fae11e912ee49aa98594e4d971043

Author: aristidisp

third-party/thrift/src/thrift/compiler/codemod/test/file_manager_test.cc

@@ -56,7 +56,7 @@ class FileManagerTest : public ::testing::Test {
   }
 
   source_manager source_manager_;
-  source source_;
+  source_view source_;
   std::unique_ptr<t_program_bundle> program_bundle_;
   std::unique_ptr<file_manager> file_manager_;
 };

third-party/thrift/src/thrift/compiler/generate/t_whisker_generator.cc

@@ -570,7 +570,7 @@ class t_whisker_generator::whisker_source_parser
       return &cached->second.value();
     }
 
-    std::optional<source> source_code = src_manager_.get_file(path);
+    std::optional<source_view> source_code = src_manager_.get_file(path);
     if (!source_code.has_value()) {
       return nullptr;
     }

third-party/thrift/src/thrift/compiler/parse/lexer.cc

@@ -175,7 +175,9 @@ const std::unordered_map<std::string_view, tok> keywords = {
 } // namespace
 
 lexer::lexer(
-    source src, diagnostics_engine& diags, doc_comment_handler on_doc_comment)
+    source_view src,
+    diagnostics_engine& diags,
+    doc_comment_handler on_doc_comment)
     : source_(src.text),
       start_(src.start),
       diags_(&diags),

third-party/thrift/src/thrift/compiler/parse/lexer.h

@@ -85,7 +85,7 @@ class lexer {
   // on_doc_comment is invoked on a documentation comment such as
   // `/** ... */` or `/// ...`.
   lexer(
-      source src,
+      source_view src,
       diagnostics_engine& diags,
       doc_comment_handler on_doc_comment = ignore_comments);
 

third-party/thrift/src/thrift/compiler/source_location.cc

@@ -133,15 +133,16 @@ class default_source_manager_backend final : public source_manager_backend {
 source_manager::source_manager()
     : backend_(std::make_unique<default_source_manager_backend>()) {}
 
-source source_manager::add_source(
+source_view source_manager::add_source(
     std::string_view file_name, std::vector<char> text) {
   assert(text.back() == '\0');
   std::string_view sv(text.data(), text.size());
   sources_.push_back(source_info{
       std::string(file_name), std::move(text), get_line_offsets(sv)});
-  return {/* .start = */
-          source_location(/* source_id= */ sources_.size(), /** offset= */ 0),
-          /* .text = */ sv};
+  return source_view{
+      /* .start = */
+      source_location(/* source_id= */ sources_.size(), /* offset= */ 0),
+      /* .text = */ sv};
 }
 
 std::string source_manager::get_file_path(std::string_view file_name) const {
@@ -151,7 +152,8 @@ std::string source_manager::get_file_path(std::string_view file_name) const {
   return std::filesystem::absolute(file_name).string();
 }
 
-std::optional<source> source_manager::get_file(std::string_view file_name) {
+std::optional<source_view> source_manager::get_file(
+    std::string_view file_name) {
   if (auto source = file_source_map_.find(file_name);
       source != file_source_map_.end()) {
     return source->second;
@@ -182,7 +184,7 @@ std::optional<source> source_manager::get_file(std::string_view file_name) {
   return source;
 }
 
-source source_manager::add_virtual_file(
+source_view source_manager::add_virtual_file(
     std::string_view file_name, std::string_view src) {
   if (file_source_map_.find(file_name) != file_source_map_.end()) {
     throw std::runtime_error(fmt::format("file already added: {}", file_name));

third-party/thrift/src/thrift/compiler/source_location.h

@@ -98,11 +98,14 @@ class resolved_location {
 };
 
 // A view of a source owned by `source_manager`.
-struct source {
+struct source_view final {
   source_location start; // The source start location.
   std::string_view text; // The source text including a terminating '\0'.
 };
 
+// DO_BEFORE(aristidis,20251001): Remove alias when all references are updated.
+using source = source_view;
+
 // A class that abstracts the reading of files from the file system. The
 // backend could read from a real file system, or be an in-memory
 // representation itself.
@@ -132,11 +135,16 @@ class source_manager {
     std::vector<char> text;
     std::vector<uint_least32_t> line_offsets;
   };
+
   // This is a deque to make sure that file_name is not reallocated when
   // sources_ grows.
   std::deque<source_info> sources_;
 
-  std::map<std::string, source, std::less<>> file_source_map_;
+  /**
+   * Maps the file_name of a source file owned by this source_manager (i.e., in
+   * `sources_`) to its `source_view`.
+   */
+  std::map<std::string, source_view, std::less<>> file_source_map_;
 
   // Maps from filepaths present in the AST to filepaths on disk.
   std::map<std::string, std::string, std::less<>> found_includes_;
@@ -149,7 +157,18 @@ class source_manager {
 
   friend class resolved_location;
 
-  source add_source(std::string_view file_name, std::vector<char> text);
+  /**
+   * Adds the given contents of a source file (with the given name) to this
+   * manager (i.e., to `sources_`).
+   *
+   * @param file_name unique name of the file whose contents are being added.
+   *        Behavior is undefined if this name is not unique.
+   *
+   * @param text file contents. Last element MUST be the NUL character.
+   *
+   * @return a view into the (newly added) content.
+   */
+  source_view add_source(std::string_view file_name, std::vector<char> text);
 
  public:
   // Creates a source_manager with the default (filesystem-based) backend.
@@ -165,18 +184,30 @@ class source_manager {
   source_manager& operator=(source_manager&&) noexcept = default;
   ~source_manager() noexcept = default;
 
-  // Loads a file and returns a source object representing its content.
-  // The file can be a real file (provided by the backend), or a virtual one
-  // previously registered with add_virtual_file.
-  //
-  // Returns an empty optional if opening or reading the file fails. Makes use
-  // of the result of previous calls to find_include_file.
-  std::optional<source> get_file(std::string_view file_name);
+  /**
+   * Returns a view into the contents of a file with the given name.
+   *
+   * The file can be a real file (provided by the backend), or a virtual one
+   * previously registered with `add_virtual_file()`.
+   *
+   * The underlying contents are owned by this manager.
+   *
+   * Returns an empty optional if opening or reading the file fails. Makes use
+   * of the result of previous calls to `find_include_file()`.
+   */
+  std::optional<source_view> get_file(std::string_view file_name);
 
   std::string get_file_path(std::string_view file_name) const;
 
-  // Adds a virtual file with the specified name and content.
-  source add_virtual_file(std::string_view file_name, std::string_view src);
+  /**
+   * Adds a virtual file with the specified name and content.
+   *
+   * @return a view into the (newly added) content.
+   *
+   * @throws if a file with the given name already exists.
+   */
+  source_view add_virtual_file(
+      std::string_view file_name, std::string_view src);
 
   // Returns the start location of a source containing the specified location.
   // It is a member function in case we add clang-like compression of locations.

third-party/thrift/src/thrift/compiler/test/diagnostic_test.cc

@@ -37,7 +37,7 @@ class DiagnosticsEngineTest : public ::testing::Test {
   source_manager source_mgr;
   diagnostic_results results;
   diagnostics_engine diags;
-  source src;
+  source_view src;
 
   DiagnosticsEngineTest()
       : diags(source_mgr, results),

third-party/thrift/src/thrift/compiler/whisker/source_location.h

@@ -23,6 +23,6 @@ namespace whisker {
 using source_location = apache::thrift::compiler::source_location;
 using source_range = apache::thrift::compiler::source_range;
 using resolved_location = apache::thrift::compiler::resolved_location;
-using source = apache::thrift::compiler::source;
+using source = apache::thrift::compiler::source_view;
 using source_manager = apache::thrift::compiler::source_manager;
 } // namespace whisker