primer::error is a simple error type used by the library to represent run-time error signals.

It is not an exception, and it is not thrown.

Primer generally translates lua errors into primer::error when it performs an operation which fails, and will translate primer::error into a lua error when adapting callbacks.

The constructor can be used to easily format error messages. For instance,

primer::error("Bad doggie, '", dog_name_str, "'! You get ", biscuit_num, "biscuits!")

produces a primer::error object with error string equal to

"Bad doggie, '" + dog_name_str + "'! You get " + std::to_string(biscuit_num) + " biscuits!"

Synopsis:

class error {
public:
  // Defaulted special member functions
  error() = default;
  error(const error &) = default;
  error(error &&) = default;
  error & operator=(const error &) = default;
  error & operator=(error &&) = default;
  ~error() = default;

  // General constructor
  // Takes a sequence of strings, string literals, or numbers
  // and concatenates them to form the message.
  // (Implementation note: The t parameter is only here to help out msvc 2015)
  template <typename T, typename... Args>
  explicit error(T && t, Args &&... args) noexcept : msg_() {
    PRIMER_TRY_BAD_ALLOC {
      msg_ = impl{primer::detail::str_cat(std::forward<T>(t),
                                          std::forward<Args>(args)...)};
    }
    PRIMER_CATCH_BAD_ALLOC { msg_ = impl{impl::bad_alloc_tag{}}; }
  }

  // Help to give context to errors
  template <typename... Args>
  error & prepend_error_line(Args &&... args) noexcept;

  //
  // Preformatted errors
  //

  // Used to indicate an out-of-memory error like `std::bad_alloc`
  static error bad_alloc() noexcept;

  // "Integer overflow occured: X"
  template <typename T>
  static error integer_overflow(const T & t) noexcept;

  // "Insufficient stack space: needed n"
  static error insufficient_stack_space(int n) noexcept;

  // "Expected foo, found 'bar'"
  template <typename T>
  static error unexpected_value(const char * expected, T && found) noexcept;

  // "Can't lock VM".
  static error cant_lock_vm() noexcept;

  // "Expired coroutine"
  static error expired_coroutine() noexcept;

  // "Module 'foo' not found"
  static error module_not_found(const std::string & path) noexcept;

  // Accessor
  const char * what() const noexcept { return msg_.c_str(); }
  const char * c_str() const noexcept { return this->what(); }
  std::string str() const { return this->what(); }
};

The prepend_error_line method can be used to add context to an error message as it comes up the callstack. For instance,

err.prepend_error_line("In index [", idx, "] of table:");