objc2-javascript-core 0.3.2

//! This file has been automatically generated by `objc2`'s `header-translator`.
//! DO NOT EDIT
use core::ffi::*;
use core::ptr::NonNull;
#[cfg(feature = "objc2")]
use objc2::__framework_prelude::*;
#[cfg(feature = "objc2-foundation")]
use objc2_foundation::*;

use crate::*;

#[cfg(feature = "objc2")]
extern_class!(
    /// A JSContext is a JavaScript execution environment. All
    /// JavaScript execution takes place within a context, and all JavaScript values
    /// are tied to a context.
    ///
    /// See also [Apple's documentation](https://developer.apple.com/documentation/javascriptcore/jscontext?language=objc)
    #[unsafe(super(NSObject))]
    #[derive(Debug, PartialEq, Eq, Hash)]
    #[cfg(feature = "objc2")]
    pub struct JSContext;
);

#[cfg(feature = "objc2")]
extern_conformance!(
    unsafe impl NSObjectProtocol for JSContext {}
);

#[cfg(feature = "objc2")]
impl JSContext {
    extern_methods!(
        /// Create a JSContext.
        ///
        /// Returns: The new context.
        #[unsafe(method(init))]
        #[unsafe(method_family = init)]
        pub unsafe fn init(this: Allocated<Self>) -> Retained<Self>;

        #[cfg(feature = "JSVirtualMachine")]
        /// Create a JSContext in the specified virtual machine.
        ///
        /// Parameter `virtualMachine`: The JSVirtualMachine in which the context will be created.
        ///
        /// Returns: The new context.
        ///
        /// # Safety
        ///
        /// `virtual_machine` might not allow `None`.
        #[unsafe(method(initWithVirtualMachine:))]
        #[unsafe(method_family = init)]
        pub unsafe fn initWithVirtualMachine(
            this: Allocated<Self>,
            virtual_machine: Option<&JSVirtualMachine>,
        ) -> Option<Retained<Self>>;

        #[cfg(all(feature = "JSValue", feature = "objc2-foundation"))]
        /// Evaluate a string of JavaScript code.
        ///
        /// Parameter `script`: A string containing the JavaScript code to evaluate.
        ///
        /// Returns: The last value generated by the script.
        ///
        /// # Safety
        ///
        /// `script` might not allow `None`.
        #[unsafe(method(evaluateScript:))]
        #[unsafe(method_family = none)]
        pub unsafe fn evaluateScript(&self, script: Option<&NSString>)
            -> Option<Retained<JSValue>>;

        #[cfg(all(feature = "JSValue", feature = "objc2-foundation"))]
        /// Evaluate a string of JavaScript code, with a URL for the script's source file.
        ///
        /// Parameter `script`: A string containing the JavaScript code to evaluate.
        ///
        /// Parameter `sourceURL`: A URL for the script's source file. Used by debuggers and when reporting exceptions. This parameter is informative only: it does not change the behavior of the script.
        ///
        /// Returns: The last value generated by the script.
        ///
        /// # Safety
        ///
        /// - `script` might not allow `None`.
        /// - `source_url` might not allow `None`.
        #[unsafe(method(evaluateScript:withSourceURL:))]
        #[unsafe(method_family = none)]
        pub unsafe fn evaluateScript_withSourceURL(
            &self,
            script: Option<&NSString>,
            source_url: Option<&NSURL>,
        ) -> Option<Retained<JSValue>>;

        /// Get the JSContext that is currently executing.
        ///
        /// This method may be called from within an Objective-C block or method invoked
        /// as a callback from JavaScript to retrieve the callback's context. Outside of
        /// a callback from JavaScript this method will return nil.
        ///
        /// Returns: The currently executing JSContext or nil if there isn't one.
        #[unsafe(method(currentContext))]
        #[unsafe(method_family = none)]
        pub unsafe fn currentContext() -> Option<Retained<JSContext>>;

        #[cfg(feature = "JSValue")]
        /// Get the JavaScript function that is currently executing.
        ///
        /// This method may be called from within an Objective-C block or method invoked
        /// as a callback from JavaScript to retrieve the callback's context. Outside of
        /// a callback from JavaScript this method will return nil.
        ///
        /// Returns: The currently executing JavaScript function or nil if there isn't one.
        #[unsafe(method(currentCallee))]
        #[unsafe(method_family = none)]
        pub unsafe fn currentCallee() -> Option<Retained<JSValue>>;

        #[cfg(feature = "JSValue")]
        /// Get the
        /// <code>
        /// this
        /// </code>
        /// value of the currently executing method.
        ///
        /// This method may be called from within an Objective-C block or method invoked
        /// as a callback from JavaScript to retrieve the callback's this value. Outside
        /// of a callback from JavaScript this method will return nil.
        ///
        /// Returns: The current
        /// <code>
        /// this
        /// </code>
        /// value or nil if there isn't one.
        #[unsafe(method(currentThis))]
        #[unsafe(method_family = none)]
        pub unsafe fn currentThis() -> Option<Retained<JSValue>>;

        #[cfg(feature = "objc2-foundation")]
        /// Get the arguments to the current callback.
        ///
        /// This method may be called from within an Objective-C block or method invoked
        /// as a callback from JavaScript to retrieve the callback's arguments, objects
        /// in the returned array are instances of JSValue. Outside of a callback from
        /// JavaScript this method will return nil.
        ///
        /// Returns: An NSArray of the arguments nil if there is no current callback.
        #[unsafe(method(currentArguments))]
        #[unsafe(method_family = none)]
        pub unsafe fn currentArguments() -> Option<Retained<NSArray>>;

        #[cfg(feature = "JSValue")]
        /// Get the global object of the context.
        ///
        /// This method retrieves the global object of the JavaScript execution context.
        /// Instances of JSContext originating from WebKit will return a reference to the
        /// WindowProxy object.
        ///
        /// Returns: The global object.
        #[unsafe(method(globalObject))]
        #[unsafe(method_family = none)]
        pub unsafe fn globalObject(&self) -> Option<Retained<JSValue>>;

        #[cfg(feature = "JSValue")]
        /// The
        /// <code>
        /// exception
        /// </code>
        /// property may be used to throw an exception to JavaScript.
        ///
        /// Before a callback is made from JavaScript to an Objective-C block or method,
        /// the prior value of the exception property will be preserved and the property
        /// will be set to nil. After the callback has completed the new value of the
        /// exception property will be read, and prior value restored. If the new value
        /// of exception is not nil, the callback will result in that value being thrown.
        ///
        /// This property may also be used to check for uncaught exceptions arising from
        /// API function calls (since the default behaviour of
        /// <code>
        /// exceptionHandler
        /// </code>
        /// is to
        /// assign an uncaught exception to this property).
        #[unsafe(method(exception))]
        #[unsafe(method_family = none)]
        pub unsafe fn exception(&self) -> Option<Retained<JSValue>>;

        #[cfg(feature = "JSValue")]
        /// Setter for [`exception`][Self::exception].
        ///
        /// # Safety
        ///
        /// `exception` might not allow `None`.
        #[unsafe(method(setException:))]
        #[unsafe(method_family = none)]
        pub unsafe fn setException(&self, exception: Option<&JSValue>);

        #[cfg(all(feature = "JSValue", feature = "block2"))]
        /// If a call to an API function results in an uncaught JavaScript exception, the
        /// <code>
        /// exceptionHandler
        /// </code>
        /// block will be invoked. The default implementation for the
        /// exception handler will store the exception to the exception property on
        /// context. As a consequence the default behaviour is for uncaught exceptions
        /// occurring within a callback from JavaScript to be rethrown upon return.
        /// Setting this value to nil will cause all exceptions occurring
        /// within a callback from JavaScript to be silently caught.
        ///
        /// # Safety
        ///
        /// - The returned block's argument 1 must be a valid pointer.
        /// - The returned block's argument 2 must be a valid pointer.
        #[unsafe(method(exceptionHandler))]
        #[unsafe(method_family = none)]
        pub unsafe fn exceptionHandler(
            &self,
        ) -> NonNull<block2::DynBlock<dyn Fn(*mut JSContext, *mut JSValue)>>;

        #[cfg(all(feature = "JSValue", feature = "block2"))]
        /// Setter for [`exceptionHandler`][Self::exceptionHandler].
        ///
        /// This is [copied][objc2_foundation::NSCopying::copy] when set.
        #[unsafe(method(setExceptionHandler:))]
        #[unsafe(method_family = none)]
        pub unsafe fn setExceptionHandler(
            &self,
            exception_handler: Option<&block2::DynBlock<dyn Fn(*mut JSContext, *mut JSValue)>>,
        );

        #[cfg(feature = "JSVirtualMachine")]
        /// All instances of JSContext are associated with a JSVirtualMachine.
        #[unsafe(method(virtualMachine))]
        #[unsafe(method_family = none)]
        pub unsafe fn virtualMachine(&self) -> Option<Retained<JSVirtualMachine>>;

        #[cfg(feature = "objc2-foundation")]
        /// Name of the JSContext. Exposed when inspecting the context.
        #[unsafe(method(name))]
        #[unsafe(method_family = none)]
        pub unsafe fn name(&self) -> Retained<NSString>;

        #[cfg(feature = "objc2-foundation")]
        /// Setter for [`name`][Self::name].
        ///
        /// This is [copied][objc2_foundation::NSCopying::copy] when set.
        #[unsafe(method(setName:))]
        #[unsafe(method_family = none)]
        pub unsafe fn setName(&self, name: Option<&NSString>);

        /// Controls whether this
        ///
        /// ```text
        ///  JSContext
        /// ```
        ///
        /// is inspectable in Web Inspector. The default value is NO.
        #[unsafe(method(isInspectable))]
        #[unsafe(method_family = none)]
        pub unsafe fn isInspectable(&self) -> bool;

        /// Setter for [`isInspectable`][Self::isInspectable].
        #[unsafe(method(setInspectable:))]
        #[unsafe(method_family = none)]
        pub unsafe fn setInspectable(&self, inspectable: bool);
    );
}

/// Methods declared on superclass `NSObject`.
#[cfg(feature = "objc2")]
impl JSContext {
    extern_methods!(
        #[unsafe(method(new))]
        #[unsafe(method_family = new)]
        pub unsafe fn new() -> Retained<Self>;
    );
}

/// SubscriptSupport.
///
/// Instances of JSContext implement the following methods in order to enable
/// support for subscript access by key and index, for example:
///
/// ```text
///     JSContext *context;
///     JSValue *v = context[@"X"]; // Get value for "X" from the global object.
///     context[@"Y"] = v;          // Assign 'v' to "Y" on the global object.
/// ```
///
/// An object key passed as a subscript will be converted to a JavaScript value,
/// and then the value converted to a string used to resolve a property of the
/// global object.
#[cfg(feature = "objc2")]
impl JSContext {
    extern_methods!(
        #[cfg(feature = "JSValue")]
        /// Get a particular property on the global object.
        ///
        /// Returns: The JSValue for the global object's property.
        ///
        /// # Safety
        ///
        /// - `key` should be of the correct type.
        /// - `key` might not allow `None`.
        #[unsafe(method(objectForKeyedSubscript:))]
        #[unsafe(method_family = none)]
        pub unsafe fn objectForKeyedSubscript(
            &self,
            key: Option<&AnyObject>,
        ) -> Option<Retained<JSValue>>;

        #[cfg(feature = "objc2-foundation")]
        /// Set a particular property on the global object.
        ///
        /// # Safety
        ///
        /// - `object` should be of the correct type.
        /// - `object` might not allow `None`.
        /// - `key` must implement NSCopying.
        /// - `key` might not allow `None`.
        #[unsafe(method(setObject:forKeyedSubscript:))]
        #[unsafe(method_family = none)]
        pub unsafe fn setObject_forKeyedSubscript(
            &self,
            object: Option<&AnyObject>,
            key: Option<&NSObject>,
        );
    );
}

/// JSContextRefSupport.
///
/// These functions are for bridging between the C API and the Objective-C API.
#[cfg(feature = "objc2")]
impl JSContext {
    extern_methods!(
        #[cfg(feature = "JSBase")]
        /// Create a JSContext, wrapping its C API counterpart.
        ///
        /// Returns: The JSContext equivalent of the provided JSGlobalContextRef.
        ///
        /// # Safety
        ///
        /// `js_global_context_ref` must be a valid pointer.
        #[unsafe(method(contextWithJSGlobalContextRef:))]
        #[unsafe(method_family = none)]
        pub unsafe fn contextWithJSGlobalContextRef(
            js_global_context_ref: JSGlobalContextRef,
        ) -> Option<Retained<JSContext>>;

        #[cfg(feature = "JSBase")]
        /// Get the C API counterpart wrapped by a JSContext.
        ///
        /// Returns: The C API equivalent of this JSContext.
        #[unsafe(method(JSGlobalContextRef))]
        #[unsafe(method_family = none)]
        pub unsafe fn JSGlobalContextRef(&self) -> JSGlobalContextRef;
    );
}