kythe.io@v0.0.68-0.20240422202219-7225dbc01741/kythe/cxx/indexer/textproto/plugin.h (about)

     1  /*
     2   * Copyright 2020 The Kythe Authors. All rights reserved.
     3   *
     4   * Licensed under the Apache License, Version 2.0 (the "License");
     5   * you may not use this file except in compliance with the License.
     6   * You may obtain a copy of the License at
     7   *
     8   *   http://www.apache.org/licenses/LICENSE-2.0
     9   *
    10   * Unless required by applicable law or agreed to in writing, software
    11   * distributed under the License is distributed on an "AS IS" BASIS,
    12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    13   * See the License for the specific language governing permissions and
    14   * limitations under the License.
    15   */
    16  
    17  #ifndef KYTHE_CXX_INDEXER_TEXTPROTO_PLUGIN_H_
    18  #define KYTHE_CXX_INDEXER_TEXTPROTO_PLUGIN_H_
    19  
    20  #include <cstdio>
    21  #include <string>
    22  
    23  #include "absl/status/status.h"
    24  #include "kythe/cxx/common/indexing/KytheGraphRecorder.h"
    25  #include "kythe/proto/analysis.pb.h"
    26  
    27  namespace kythe {
    28  namespace lang_textproto {
    29  
    30  // The plugin's interface to the indexer.
    31  class PluginApi {
    32   public:
    33    PluginApi() = default;
    34    PluginApi(const PluginApi&) = delete;
    35    PluginApi& operator=(const PluginApi&) = delete;
    36    virtual ~PluginApi() = default;
    37  
    38    // Adds an anchor for the text span [begin, end) and returns its VName.
    39    virtual proto::VName CreateAndAddAnchorNode(const proto::VName& file,
    40                                                int begin, int end) = 0;
    41  
    42    // Adds an anchor for the text span and returns its VName.
    43    virtual proto::VName CreateAndAddAnchorNode(const proto::VName& file_vname,
    44                                                absl::string_view sp) = 0;
    45  
    46    virtual KytheGraphRecorder* recorder() = 0;
    47  
    48    virtual void EmitDiagnostic(const proto::VName& file_vname,
    49                                absl::string_view signature,
    50                                absl::string_view msg) = 0;
    51  
    52    // Returns a VName for the given relative path by resolving it to its full
    53    // path and matching it against a file in the CompilationUnit's
    54    // required_inputs.
    55    virtual proto::VName VNameForRelPath(
    56        absl::string_view simplified_path) const = 0;
    57  
    58    // Returns a pointer to the descriptor pool built from the .proto files
    59    // included as dependencies in the textproto's compilation unit.
    60    virtual const google::protobuf::DescriptorPool* ProtoDescriptorPool()
    61        const = 0;
    62  };
    63  
    64  struct StringToken {
    65    // Parsed string value with escape codes resolved.
    66    std::string parsed_value;
    67    // The span of source text in the input. The underlying string that the view
    68    // references is owned by the `PluginApi`.
    69    absl::string_view source_text;
    70  };
    71  
    72  // Superclass for all plugins. A new plugin is instantiated for each textproto
    73  // handled by the indexer.
    74  class Plugin {
    75   public:
    76    Plugin() = default;
    77    virtual ~Plugin() = default;
    78  
    79    // Main entrypoint for plugins. In the common case, `tokens` will contain a
    80    // single entry with the `parsed_value` and `source_text` fields equal in
    81    // string value. If string concatenation syntax is used, for example:
    82    //
    83    //   my_field: "abc" "def"
    84    //
    85    // There will be one StringToken per string "piece" ("abc" and "def" here). If
    86    // the string value contains escape codes, the parsed_value may be shorter
    87    // than the source_text as the multi-character escape code is replaced by a
    88    // single character.
    89    //
    90    // VNames for semantic nodes emitted by the plugin should set the language to
    91    // something like "textproto_plugin_$PLUGIN_NAME".
    92    virtual absl::Status AnalyzeStringField(
    93        PluginApi* api, const proto::VName& file_vname,
    94        const google::protobuf::FieldDescriptor& field,
    95        const std::vector<StringToken>& tokens) = 0;
    96  
    97    // Optional entrypoint for integer fields. Plugin may override it to add
    98    // additional nodes for integer fields.
    99    virtual absl::Status AnalyzeIntegerField(
   100        PluginApi* api, const proto::VName& file_vname,
   101        const google::protobuf::FieldDescriptor& field,
   102        absl::string_view field_value) {
   103      return absl::OkStatus();
   104    }
   105  
   106   protected:
   107    Plugin(const Plugin&) = delete;
   108    Plugin& operator=(const Plugin&) = delete;
   109  };
   110  
   111  }  // namespace lang_textproto
   112  }  // namespace kythe
   113  
   114  #endif  // KYTHE_CXX_INDEXER_TEXTPROTO_PLUGIN_H_