src/lib/intl/lookup/cpp/lookup.h

// Copyright 2020 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

// Provides an API for looking up localized message strings.
//
// Localized message strings are strings which have a different value based on
// the locale that is supplied as the context of the lookup.  So, if your locale
// is, say "en", your `lookup.string(42)` may return `Hello world`, but if your
// locale is "nl", your `lookup.string(42)` may return `Groetjes, wereld`.
//
// Example use:
//
// ```
// std::vector<std::string> locale_ids = {"nl-NL"};
// auto result = Lookup::New(locale_ids);
// if (result.is_error()) {
//   // handle error
//   return;
// }
// auto lookup = result.value();
// auto lookup_result = lookup.string(42);
// if (lookup_result.is_error()) {
//   // handle error
//   return;
// }
// std::string_view message = lookup_result.value();
// // Use `message`.
// ```
//
// Note, almost all of the implementation of this class is
// in fact in rust code behind a FFI-able C ABI.  One should
// normally not need to look under the hood if all you want is to test
// the interaction with your code with this library.  This means, if it does
// not support something you need, filing a bug at https://fxbug.dev may be
// the fastest way to get what you need.

#ifndef SRC_LIB_INTL_LOOKUP_CPP_LOOKUP_H_
#define SRC_LIB_INTL_LOOKUP_CPP_LOOKUP_H_

#include <lib/fpromise/result.h>

#include <memory>
#include <string>

#include "gtest/gtest_prod.h"
#include "src/lib/intl/lookup/rust/lookup.h"

namespace intl {

// The C++ API used to look up localized messages by their unique message ID.
// See the top of this header file for use examples.
class Lookup {
 public:
  ~Lookup();

  // Error codes reported by New() and Lookup() methods.
  enum class Status : int8_t {
    // No error.
    OK = 0,
    // The value requested is not available.
    UNAVAILABLE = 1,
    // The argument passed in by the user is not valid.
    ARGUMENT_ERROR = 2,
    // Some internal error happened.  Consult logs for details.
    INTERNAL = 111,
  };

  // Makes a new lookup object, which contains information about the passed-in
  // locales.  At present, if any one of the locales is not present verbatim,
  // an error is returned.
  //
  // Errors:
  //   - UNAVAILABLE: one of the requested locale IDs is not avalable for use.
  //   - ARGUMENT_ERROR: the locales ids are malfomed, e.g. nonexistent, or
  //     not a valid UTF8 encoding of the locale ID.
  static fpromise::result<std::unique_ptr<Lookup>, Lookup::Status> New(
      const std::vector<std::string>& locale_ids);

  // Looks up the message by its unique `message_id`.
  //
  // Errors:
  //   - UNAVAILABLE: the requested message ID is not present in the loaded
  //     resource bundle.
  fpromise::result<std::string_view, Lookup::Status> String(uint64_t message_id);

  // Instantiates a fake Lookup instance, which is useful for tests that don't
  // want to make a full end-to-end localization setup.
  //
  // The fake is simplistic and it is the intention that it provides you with
  // some default fake behaviors.  The behaviors are as follows at the moment,
  // and more could be added if needed.
  //
  // - If `locale_ids` contains the string `en-US`, the constructor will
  //   return  UNAVAILABLE.
  // - If the message ID pased to `Lookup::String()` is exactly 1, the fake
  //   returns `Hello, {person}!`, so that you can test 1-parameter formatting.
  // - Otherwise, for an even mesage ID it returns "Hello world!", or for
  //   an odd message ID returns UNAVAILABLE.
  //
  // The implementation of the fake itself is done in rust behind a FFI ABI,
  // see the package //src/lib/intl/lookup/rust for details.
  static fpromise::result<std::unique_ptr<Lookup>, Lookup::Status> NewForTest(
      const std::vector<std::string>& locale_ids);

  // Same as above, except allows you to pass in custom behavior operations
  // for the fake and affect its behavior.  As a user of this library you should
  // normally never need to use this particular constructor.  If you need
  // special behavior, consider filing a feature request instead to component
  // "I18N>Localization" at https://fxbug.dev.
  static fpromise::result<std::unique_ptr<Lookup>, Lookup::Status> NewForTest(
      const std::vector<std::string>& locale_ids, const intl_lookup_ops_t ops);

 private:
  FRIEND_TEST(Intl, CreateError);
  FRIEND_TEST(Intl, LookupReturnValues);

  // Injects fake operations for testing. Takes ownership of impl.
  Lookup(intl_lookup_t* impl, intl_lookup_ops_t ops_for_test);

  // Operations used to access the implementation type from the C ABI,
  // int_lookup_t*.  The ops need to vary only for tests.
  const intl_lookup_ops_t ops_;

  // Owned by this class. Never null for a properly initialized class.
  intl_lookup_t* impl_ = nullptr;

  Lookup(const Lookup&) = delete;
  Lookup(const Lookup&&) = delete;
  Lookup() = delete;
};

}  // namespace intl

#endif  // SRC_LIB_INTL_LOOKUP_CPP_LOOKUP_H_