#include <Ultralight/js/Error.h>

Overview

An error from a JavaScript operation.

The library never throws C++ exceptions. Operations that can fail return a js::Result, and its Error is one of four kinds:

A JavaScript exception (is_exception() is true): script threw, or the call was invalid in JavaScript (eg, calling something that isn't a function). exception() holds the thrown value, and type(), stack(), source_url(), line(), and column() describe it.
Empty handle (is_empty() is true): the Value or Context you called it on holds nothing (see js::Value). This usually means a bug in your code.
Page gone (is_page_gone() is true): the handle's page is gone (see js::Value).
A native error (all three are false): an error created in C++, by you (TypeError(), RangeError(), Make()) or by the library (eg, when To() gets the wrong type).

A page can go away at any time, so a page-gone error usually needs no report. Report the rest with message():

js::Result<std::string> title = value.ToString();
if (!title) {
  if (title.error().is_page_gone())
    return;                              // the page went away; nothing to report
  Log(title.error().message());          // script threw or the Value was empty: report it
}

A bound function throws an Error into the page by returning it in a js::Result. Use WithCode() to give it a code property, so page script can check the kind of error without parsing the message.

Error Codes

The TypeErrors the library creates have a code property (read it with code() in native code, or error.code in page script). Check the code rather than the message, since message text is written for people and can change in any release. The codes below stay the same (new ones may be added).

Code	Meaning
ULJS_BAD_ARG	A value doesn't have the expected type, or its text doesn't parse
ULJS_LOSSY	A number doesn't fit the parameter's type (Strict diagnostics only)
ULJS_EXTRA_ARGS	A call passed more arguments than the binding takes (Strict only)
ULJS_DETACHED	The native object or API behind a binding or instance is gone
ULJS_NOT_INSTANCE	A class method was called on an object that isn't an instance
ULJS_NO_CTOR	Page script used new on a class that has no constructor
ULJS_CROSS_CONTEXT	A value was used on a page it can't be shared with (see js::Value)

Note: When JavaScript diagnostics are on (see js::Diagnostics; they're on by default in developer mode), an Error that holds a JavaScript exception logs it if it's destroyed before anything reads it (any accessor, such as message(), counts). So a dropped Result never hides a script error during development.

Static Public Member Functions
static Error	PageGone ()
	Create a page-gone error (is_page_gone() returns true).
static Error	AdoptException (ULJSValue exception)
	Create an error from a JavaScript exception, taking ownership of the handle.
static Error	TypeError (std::string message)
	Create a native TypeError.
static Error	RangeError (std::string message)
	Create a native RangeError.
static Error	Make (ErrorType type, std::string message)
	Create a native error of any type.

Public Member Functions
	Error (Error &&other) noexcept
	Move constructor (other no longer holds the exception).
Error &	operator= (Error &&other) noexcept
	Move assignment (other no longer holds the exception).
	Error (const Error &other)
	Copy constructor (takes its own reference to the exception, if any).
Error &	operator= (const Error &other)
	Copy assignment (takes its own reference to the exception, if any).
	~Error ()
	Destructor (logs the exception first if nothing read it; see the class notes).
Error	WithCode (std::string code) &&
	Add a code that page script gets as the error's code property when it's thrown.
bool	is_exception () const
	Whether or not this error holds a JavaScript exception.
bool	is_page_gone () const
	Whether or not this error means the handle's page is gone.
bool	is_empty () const
	Whether or not this error means the handle holds nothing (see the class notes).
ULJSValue	exception () const
	Get the JavaScript exception (NULL if is_exception() is false).
ErrorType	type () const
	Get the error's type.
std::string	stack () const
	Get the stack trace of a JavaScript exception.
std::string	source_url () const
	Get the URL of the script that created a JavaScript exception.
unsigned	line () const
	Get the 1-based line where a JavaScript exception was created.
unsigned	column () const
	Get the 1-based column where a JavaScript exception was created.
std::string	code () const
	Get the error's code (an empty string if it has none).
ULJSValue	ToJS (ULJSContext ctx) const
	Convert this error to a JavaScript value.
std::string	message () const
	Get a readable description of the error.

Constructor & Destructor Documentation

◆ Error() [1/2]

Error ( Error && other )

inlinenoexcept

Move constructor (other no longer holds the exception).

◆ Error() [2/2]

Error ( const Error & other )

inline

Copy constructor (takes its own reference to the exception, if any).

◆ ~Error()

~Error ( )

inline

Destructor (logs the exception first if nothing read it; see the class notes).

Member Function Documentation

◆ AdoptException()

Error AdoptException ( ULJSValue exception )

inlinestatic

Create an error from a JavaScript exception, taking ownership of the handle.

Parameters

exception The thrown value. The Error destroys the handle when it's done with it.

Returns: Returns the new Error.

◆ code()

std::string code ( ) const

inline

Get the error's code (an empty string if it has none).

For a native error, this is the code from WithCode(). For a JavaScript exception, it's the thrown value's code property, if that's a string of up to 64 bytes. The errors the library creates use the codes listed in the class notes.

Note: Reading a JavaScript exception's property can run a getter.

◆ column()

unsigned column ( ) const

inline

Get the 1-based column where a JavaScript exception was created.

Returns: Returns the column (0 if it's unknown, for a native error, or once the exception's page is gone).

Note: For a thrown value that isn't an error object, this converts it to a string, which can run script.

◆ exception()

ULJSValue exception ( ) const

inline

Get the JavaScript exception (NULL if is_exception() is false).

Note: The Error owns the handle. Call ulCreateJSValueRef() to keep it longer.

◆ is_empty()

bool is_empty ( ) const

inline

Whether or not this error means the handle holds nothing (see the class notes).

◆ is_exception()

bool is_exception ( ) const

inline

Whether or not this error holds a JavaScript exception.

◆ is_page_gone()

bool is_page_gone ( ) const

inline

Whether or not this error means the handle's page is gone.

◆ line()

unsigned line ( ) const

inline

Get the 1-based line where a JavaScript exception was created.

Returns: Returns the line (0 if it's unknown, for a native error, or once the exception's page is gone).

Note: For a thrown value that isn't an error object, this converts it to a string, which can run script.

◆ Make()

Error Make	(	ErrorType	type,
		std::string	message )

inlinestatic

Create a native error of any type.

Parameters

type	The error type, returned by type().
message	The description, returned by message().

Returns: Returns the new Error.

◆ message()

std::string message ( ) const

inline

Get a readable description of the error.

For a JavaScript exception, this converts the thrown value to a string (which can run script) and falls back to "JavaScript exception" if that fails.

◆ operator=() [1/2]

Error & operator= ( const Error & other )

inline

Copy assignment (takes its own reference to the exception, if any).

◆ operator=() [2/2]

Error & operator= ( Error && other )

inlinenoexcept

Move assignment (other no longer holds the exception).

◆ PageGone()

Error PageGone ( )

inlinestatic

Create a page-gone error (is_page_gone() returns true).

Returns: Returns the new Error.

◆ RangeError()

Error RangeError ( std::string message )

inlinestatic

Create a native RangeError.

Parameters

message The description, returned by message().

Returns: Returns the new Error.

◆ source_url()

std::string source_url ( ) const

inline

Get the URL of the script that created a JavaScript exception.

Returns: Returns the URL (an empty string if it's unknown, for a native error, or once the exception's page is gone).

Note: For a thrown value that isn't an error object, this converts it to a string, which can run script.

◆ stack()

std::string stack ( ) const

inline

Get the stack trace of a JavaScript exception.

Returns: Returns the stack trace (an empty string for a native error, a thrown value that isn't an error object, or once the exception's page is gone).

Note: For a thrown value that isn't an error object, this converts it to a string, which can run script.

◆ ToJS()

ULJSValue ToJS ( ULJSContext ctx ) const

inline

Convert this error to a JavaScript value.

For a JavaScript exception whose page is alive, you get the thrown value. Otherwise you get a new error object with type(), message(), and the code from WithCode().

Parameters

ctx	The context to create the value in.

Returns: Returns a new handle you must destroy with ulDestroyJSValue() (NULL if ctx is gone).

Precondition: Must be called on the Renderer's thread.

◆ type()

ErrorType type ( ) const

inline

Get the error's type.

For a JavaScript exception, this is the class of the thrown error. It reads as ErrorType::Error for any other class, for a thrown value that isn't an error object, and once the exception's page is gone.

Note: For a thrown value that isn't an error object, this converts it to a string, which can run script.

◆ TypeError()

Error TypeError ( std::string message )

inlinestatic

Create a native TypeError.

Parameters

message The description, returned by message().

Returns: Returns the new Error.

◆ WithCode()

Error WithCode ( std::string code ) &&

inline

Add a code that page script gets as the error's code property when it's thrown.

return js::Unexpected(js::Error::TypeError("bad slot").WithCode("BAD_SLOT"));

ultralight::js::Error::TypeError

static Error TypeError(std::string message)

Create a native TypeError.

Definition Error.h:144

ultralight::js::Error::WithCode

Error WithCode(std::string code) &&

Add a code that page script gets as the error's code property when it's thrown.

Definition Error.h:234

Parameters

code	The code, returned by code().

Returns: Returns the Error with the code added.

The documentation for this class was generated from the following file:

Ultralight/js/Error.h

Overview

Error Codes

Static Public Member Functions

Public Member Functions

Constructor & Destructor Documentation

◆ Error() [1/2]

◆ Error() [2/2]

◆ ~Error()

Member Function Documentation

◆ AdoptException()

◆ code()

◆ column()

◆ exception()

◆ is_empty()

◆ is_exception()

◆ is_page_gone()

◆ line()

◆ Make()

◆ message()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ PageGone()

◆ RangeError()

◆ source_url()

◆ stack()

◆ ToJS()

◆ type()

◆ TypeError()

◆ WithCode()