kythe.io@v0.0.68-0.20240422202219-7225dbc01741/kythe/cxx/common/kythe_uri.h (about)

     1  /*
     2   * Copyright 2015 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_COMMON_KYTHE_URI_H_
    18  #define KYTHE_CXX_COMMON_KYTHE_URI_H_
    19  
    20  #include <string>
    21  
    22  #include "absl/strings/string_view.h"
    23  #include "kythe/cxx/common/vname_ordering.h"
    24  #include "kythe/proto/storage.pb.h"
    25  
    26  namespace kythe {
    27  
    28  /// \brief Determines the behavior of URI escaping.
    29  enum class UriEscapeMode {
    30    kEscapeAll,   ///< Escape all reserved characters.
    31    kEscapePaths  ///< Escape all reserved characters except '/'.
    32  };
    33  
    34  /// \brief URI-escapes a string.
    35  /// \param mode The escaping mode to use.
    36  /// \param string The string to escape.
    37  std::string UriEscape(UriEscapeMode mode, absl::string_view uri);
    38  
    39  /// \brief URI-unescapes a string.
    40  /// \param string The string to unescape.
    41  /// \return A pair of (success, error-or-unescaped-string).
    42  std::pair<bool, std::string> UriUnescape(absl::string_view string);
    43  
    44  /// \brief A Kythe URI.
    45  ///
    46  /// URIs are not in 1:1 correspondence with VNames--particularly because
    47  /// the `corpus` component is considered to be a path that can be lexically
    48  /// canonicalized. For example, the corpus "a/b/../c" is equivalent to the
    49  /// corpus "a/c".
    50  class URI {
    51   public:
    52    URI() = default;
    53  
    54    /// \brief Builds a URI from a `VName`, canonicalizing its `corpus`.
    55    explicit URI(const kythe::proto::VName& from_vname);
    56  
    57    bool operator==(const URI& o) const { return VNameEquals(vname_, o.vname_); }
    58    bool operator!=(const URI& o) const { return !VNameEquals(vname_, o.vname_); }
    59  
    60    /// \brief Constructs a URI from an encoded string.
    61    /// \param uri The string to construct from.
    62    /// \return (true, URI) on success; (false, empty URI) on failure.
    63    static std::pair<bool, URI> FromString(absl::string_view uri) {
    64      URI result;
    65      bool is_ok = result.ParseString(uri);
    66      return std::make_pair(is_ok, result);
    67    }
    68  
    69    /// \brief Encodes this URI as a string.
    70    ///
    71    /// \return This URI, appropriately escaped.
    72    std::string ToString() const;
    73  
    74    /// \return This URI as a VName.
    75    const kythe::proto::VName& v_name() const { return vname_; }
    76  
    77   private:
    78    /// \brief Attempts to overwrite vname_ using the provided URI string.
    79    /// \param uri The URI to parse.
    80    /// \return true on success
    81    bool ParseString(absl::string_view uri);
    82  
    83    /// The VName this URI represents.
    84    kythe::proto::VName vname_;
    85  };
    86  }  // namespace kythe
    87  
    88  #endif