Completion.h 5.8 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171
  1. /*
  2. * Copyright (c) 2021, Andreas Kling <kling@serenityos.org>
  3. * Copyright (c) 2021, Linus Groh <linusg@serenityos.org>
  4. *
  5. * SPDX-License-Identifier: BSD-2-Clause
  6. */
  7. #pragma once
  8. #include <AK/FlyString.h>
  9. #include <AK/Optional.h>
  10. #include <AK/Try.h>
  11. #include <AK/Variant.h>
  12. #include <LibJS/Runtime/Value.h>
  13. namespace JS {
  14. // Temporary helper akin to TRY(), but returning a default-constructed type (e.g. empty JS::Value)
  15. // instead of the throw completion record. Use this as the bridge between functions that have
  16. // already been updated to use completions and functions that haven't.
  17. #define TRY_OR_DISCARD(expression) \
  18. ({ \
  19. auto _temporary_result = (expression); \
  20. if (_temporary_result.is_error()) \
  21. return {}; \
  22. _temporary_result.release_value(); \
  23. })
  24. // 6.2.3 The Completion Record Specification Type, https://tc39.es/ecma262/#sec-completion-record-specification-type
  25. class [[nodiscard]] Completion {
  26. public:
  27. enum class Type {
  28. Normal,
  29. Break,
  30. Continue,
  31. Return,
  32. Throw,
  33. };
  34. Completion(Type type, Optional<Value> value, Optional<FlyString> target)
  35. : m_type(type)
  36. , m_value(move(value))
  37. , m_target(move(target))
  38. {
  39. if (m_value.has_value())
  40. VERIFY(!m_value->is_empty());
  41. }
  42. Completion(ThrowCompletionOr<Value> const&);
  43. // 5.2.3.1 Implicit Completion Values, https://tc39.es/ecma262/#sec-implicit-completion-values
  44. // Not `explicit` on purpose.
  45. Completion(Value value)
  46. : Completion(Type::Normal, value, {})
  47. {
  48. }
  49. Completion()
  50. : Completion(js_undefined())
  51. {
  52. }
  53. [[nodiscard]] Type type() const { return m_type; }
  54. [[nodiscard]] bool has_value() const { return m_value.has_value(); }
  55. [[nodiscard]] Value value() const { return *m_value; }
  56. [[nodiscard]] bool has_target() const { return m_target.has_value(); }
  57. [[nodiscard]] FlyString const& target() const { return *m_target; }
  58. // "abrupt completion refers to any completion with a [[Type]] value other than normal"
  59. [[nodiscard]] bool is_abrupt() const { return m_type != Type::Normal; }
  60. // These are for compatibility with the TRY() macro in AK.
  61. [[nodiscard]] bool is_error() const { return m_type == Type::Throw; }
  62. [[nodiscard]] Value release_value() { return m_value.release_value(); }
  63. Completion release_error()
  64. {
  65. VERIFY(is_error());
  66. return { m_type, release_value(), move(m_target) };
  67. }
  68. // 6.2.3.4 UpdateEmpty ( completionRecord, value ), https://tc39.es/ecma262/#sec-updateempty
  69. Completion update_empty(Value value) const
  70. {
  71. // 1. Assert: If completionRecord.[[Type]] is either return or throw, then completionRecord.[[Value]] is not empty.
  72. if (m_type == Type::Return || m_type == Type::Throw)
  73. VERIFY(m_value.has_value());
  74. // 2. If completionRecord.[[Value]] is not empty, return Completion(completionRecord).
  75. if (m_value.has_value())
  76. return *this;
  77. // 3. Return Completion { [[Type]]: completionRecord.[[Type]], [[Value]]: value, [[Target]]: completionRecord.[[Target]] }.
  78. return { m_type, value, m_target };
  79. }
  80. private:
  81. Type m_type { Type::Normal }; // [[Type]]
  82. Optional<Value> m_value; // [[Value]]
  83. Optional<FlyString> m_target; // [[Target]]
  84. };
  85. template<typename ValueType>
  86. class [[nodiscard]] ThrowCompletionOr {
  87. public:
  88. ThrowCompletionOr() requires(IsSame<ValueType, Empty>)
  89. : m_value(Empty {})
  90. {
  91. }
  92. // Not `explicit` on purpose so that `return vm.throw_completion<Error>(...);` is possible.
  93. ThrowCompletionOr(Completion throw_completion)
  94. : m_throw_completion(move(throw_completion))
  95. {
  96. VERIFY(throw_completion.is_error());
  97. }
  98. // Not `explicit` on purpose so that `return value;` is possible.
  99. ThrowCompletionOr(ValueType value)
  100. : m_value(move(value))
  101. {
  102. if constexpr (IsSame<ValueType, Value>)
  103. VERIFY(!value.is_empty());
  104. }
  105. // Allows implicit construction of ThrowCompletionOr<T> from a type U if T(U) is a supported constructor.
  106. // Most commonly: Value from Object* or similar, so we can omit the curly braces from "return { TRY(...) };".
  107. // Disabled for POD types to avoid weird conversion shenanigans.
  108. template<typename WrappedValueType>
  109. ThrowCompletionOr(WrappedValueType value) requires(!IsPOD<ValueType>)
  110. : m_value(move(value))
  111. {
  112. }
  113. [[nodiscard]] bool is_throw_completion() const { return m_throw_completion.has_value(); }
  114. Completion const& throw_completion() const { return *m_throw_completion; }
  115. [[nodiscard]] bool has_value() const requires(!IsSame<ValueType, Empty>) { return m_value.has_value(); }
  116. [[nodiscard]] ValueType const& value() const requires(!IsSame<ValueType, Empty>) { return *m_value; }
  117. // These are for compatibility with the TRY() macro in AK.
  118. [[nodiscard]] bool is_error() const { return m_throw_completion.has_value(); }
  119. [[nodiscard]] ValueType release_value() { return m_value.release_value(); }
  120. Completion release_error() { return m_throw_completion.release_value(); }
  121. private:
  122. Optional<Completion> m_throw_completion;
  123. Optional<ValueType> m_value;
  124. };
  125. template<>
  126. class ThrowCompletionOr<void> : public ThrowCompletionOr<Empty> {
  127. public:
  128. using ThrowCompletionOr<Empty>::ThrowCompletionOr;
  129. };
  130. ThrowCompletionOr<Value> await(GlobalObject&, Value);
  131. // 6.2.3.2 NormalCompletion ( value ), https://tc39.es/ecma262/#sec-normalcompletion
  132. inline Completion normal_completion(Optional<Value> value)
  133. {
  134. return { Completion::Type::Normal, value, {} };
  135. }
  136. // 6.2.3.3 ThrowCompletion ( value ), https://tc39.es/ecma262/#sec-throwcompletion
  137. inline Completion throw_completion(Value value)
  138. {
  139. return { Completion::Type::Throw, value, {} };
  140. }
  141. }