/+junk/gjs-vapi

/*

 * SPDX-License-Identifier: MIT OR LGPL-2.0-or-later

 *

 * SPDX-FileContributor: Authored By: Gustav Hartvigsson

 */

/*

 * All comments are copid from the GJS source code, but changed to work with

 * valadoc.

 */

/**

 * JavaScript bindings for GNOME

 *

 * Use the GNOME platform libraries in your JavaScript programs.

 * GJS powers GNOME Shell, Polari, GNOME Documents, and many other apps.

 * Under the hood it uses SpiderMonkey, Mozilla's JavaScript engine

 * originally developed for Firefox.

 */

[CCode (cheader_filename = "gjs/gjs.h",

        cprefix = "Gjs",

        lower_case_cprefix = "gjs_")]

namespace Gjs {

  [CCode (cname = "GjsError", 

          cprefix = "GJS_ERROR_",

          lower_case_cprefix = "gjs_error_")]

  public errordomain Error {

    FAILED,

    EXIT,

  }

  [CCode (cname = "GjsJSError",

          cprefix = "GJS_JS_ERROR_",

          lower_case_cprefix = "gjs_js_error_")]

  public errordomain JSError {

    ERROR,

    EVAL_ERROR,

    INTERNAL_ERROR,

    RANGE_ERROR,

    REFERENCE_ERROR,

    STOP_ITERATION,

    SYNTAX_ERROR,

    TYPE_ERROR,

    URI_ERROR,

  }

  [CCode (cname = "GjsContext",

          type_id = "GJS_TYPE_CONTEXT")]

  public class Context : GLib.Object {

    /*

     * The properties here are based on what I can read from the C++ source

     * code.

     */

    /**

     * Path where modules to import should reside.

     */

    public string[] search_path {construct;}

    /**

     * The filename of the launched JS program

     */

    public string program_name {get {

      unowned string ret_val = null;

      this.@get ("program-name", ref ret_val);

      return ret_val;

    } construct;}

    /**

     * The full path of the launched file or NULL if GJS was launched from

     * the C API or interactive console.

     */

    public string program_path {get {

      unowned string ret_val = null;

      this.@get ("program-path", ref ret_val);

      return ret_val;

    } construct;}

    /**

     * Set this property to profile any JS code run by this context. By

     * default, the profiler is started and stopped when you call

     * {@link Gjs.Context.eval}.

     *

     * The value of this property is superseded by the GJS_ENABLE_PROFILER

     * environment variable.

     *

     * You may only have one context with the profiler enabled at a time.

     */

    [NoAccessorMethod]

    public bool profiler_enabled {construct;}

    /**

     * Set this property to install a SIGUSR2 signal handler that starts and

     * stops the profiler. This property also implies that

     * {@link Gjs.Context.profiler_enabled} is set.

     */

    [NoAccessorMethod]

    public bool profiler_sigusr2 {construct;}

    /**

     * Whether to execute the file as a module

     */

    [NoAccessorMethod]

    public bool exec_as_module {construct;}

    [CCode (cname = "gjs_context_new")]

    public Context ();

    [CCode (cname = "gjs_context_new_with_search_path")]

    public Context.with_search_path ([CCode (array_length = false)]

                                     string[] search_path);

    [CCode (cname = "gjs_context_eval_file")]

    public bool eval_file (string filename,

                      out int exit_status_p)

                      throws GLib.Error;

    [CCode (cname = "gjs_context_eval_module_file")]

    public bool eval_module_file (string filename,

                                  out uint8 exit_status_p)

                                  throws GLib.Error;

    [CCode (cname = "gjs_context_eval")]

    public bool eval (string script,

                      string filename,

                      out int exit_status_p)

                      throws GLib.Error;

    [CCode (cname = "gjs_context_register_module")]

    public bool register_module (string identifier,

                                 string uri)

                                 throws GLib.Error;

    [CCode (cname = "gjs_context_eval_module")]

    public bool eval_module (string identifier,

                             out uint8 exit_code)

                             throws GLib.Error;

    [CCode (cname = "gjs_context_define_string_array")]

    public bool define_string_array (string array_name,

                                     [CCode (array_length_pos = 1.1)]

                                     string[] array_values)

                                     throws GLib.Error;

    [CCode (cname = "gjs_context_set_argv")]

    public void set_argv ([CCode (array_length_pos = 0.1,

                                  type = "const char**")]

                          string[] array_values);

    /**

     * Returns a newly-allocated list containing all known instances of 

     * {@link Gjs.Context}. This is useful for operating on the contexts from a

     * process-global situation such as a debugger.

     *

     * @return Known {@link Gjs.Context} instances

     */

    [CCode (cname = "gjs_context_get_all")]

    public GLib.List<Context> get_all ();

    [CCode (cname = "gjs_context_get_current")]

    public static Context get_current ();

    [CCode (cname = "gjs_context_make_current")]

    public void make_current ();

    /**

     * Returns a pointer to the underlying native context. For SpiderMonkey,

     * this is a JSContext *

     */

    [CCode (cname = "gjs_context_get_native_context")]

    public GLib.pointer get_native_context ();

    [CCode (cname = "gjs_context_print_stack_stderr")]

    public void print_stack_stderr ();

    /**

     * Similar to the Spidermonkey JS_MaybeGC() call which

     * heuristically looks at JS runtime memory usage and

     * may initiate a garbage collection.

     *

     * This function always unconditionally invokes JS_MaybeGC(), but

     * additionally looks at memory usage from the system malloc()

     * when available, and if the delta has grown since the last run

     * significantly, also initiates a full JavaScript garbage

     * collection.  The idea is that since GJS is a bridge between

     * JavaScript and system libraries, and JS objects act as proxies

     * for these system memory objects, GJS consumers need a way to

     * hint to the runtime that it may be a good idea to try a

     * collection.

     *

     * A good time to call this function is when your application

     * transitions to an idle state.

     */

    [CCode (cname = "gjs_context_maybe_gc")]

    public void maybe_gc ();

    /**

     * Initiate a full GC; may or may not block until complete. This

     * function just calls Spidermonkey JS_GC().

     */

    [CCode (cname = "gjs_context_gc")]

    public void gc ();

    /*

     * Returns the profiler's internal instance of {@link Gjs.Profiler}

     * for you to customize, or %NULL if profiling is not enabled on this

     * {@link Gjs.Context}.

     *

     * @returns {@link Gjs.Profiler}

     */

    [CCode (cname = "gjs_context_get_profiler")]

    public Profiler get_profiler ();

    [CCode (cname = "gjs_context_setup_debugger_console")]

    public void setup_debugger_console ();

  }

  [CCode (cheader_filename = "gjs/context.h",

          cname = "gjs_dumpstack")]

  public void dump_stack ();

  /**

   * Returns the underlying version of the JS engine.

   *

   * Returns: a string

   */

  [CCode (cheader_filename = "gjs/context.h",

          cname = "gjs_get_js_version")]

  public string get_js_version ();

  /*

   * This class has no visible _new function, can only be created from

   * context.

   */

  [CCode (cheader_filename = "gjs/profiler.h",

          cname = "GjsProfiler",

          type_id = "GJS_TYPE_PROFILER")]

  public class Profiler : GLib.Object {

    /**

     * Set the capture writer to which profiling data is written when the

     * ''this'' is stopped.

     * 

     * @param capture A {SysprofCaptureWriter}

     */

    [CCode (cname = "gjs_profiler_set_capture_writer")]

    public void set_capture_writer (GLib.pointer capture);

    /**

     * Set the file to which profiling data is written when the ''this'' is

     * stopped. By default, this is `gjs-$PID.syscap` in the current directory.

     */

    [CCode (cname = "gjs_profiler_set_filename")]

    public void set_filename (string filename);

    [CCode (cname = "gjs_profiler_set_fd")]

    public void set_fd (int fd);

    /**

     * As expected, this starts the {@link Gjs.Profiler}.

     *

     * This will enable the underlying JS profiler and register a POSIX timer to

     * deliver SIGPROF on the configured sampling frequency.

     *

     * To reduce sampling overhead, Gjs.Profiler stashes information

     * about the profile to be calculated once the profiler has been disabled.

     * Calling Gjs.Profiler.stop() will result in that delayed work to be

     * completed.

     *

     * You should call Gjs.Profiler.stop() when the profiler is no longer

     * needed.

     */

    [CCode (cname = "gjs_profiler_start")]

    public void start ();

    /**

     * Stops a currently running {@link Gjs.Profiler}. If the profiler is not 

     * running, this function will do nothing.

     *

     * Some work may be delayed until the end of the capture. Such delayed work

     * includes flushing the resulting samples and file location information to

     * disk.

     *

     * This may block while writing to disk. Generally, the writes are delivered

     * to a tmpfs device, and are therefore negligible.

     */

    [CCode (cname = "gjs_profiler_stop")]

    public void stop ();

    /**

     * Use this to pass a signal info caught by another signal handler to a

     * {@link Gjs.Profiler}. This might be needed if you have your own complex

     * signal handling system for which Gjs.Profiler cannot simply add a SIGUSR2

     * handler.

     *

     * This function should only be called from the JS thread.

     *

     * @return true if the signal was handled.

     */

    [CCode (cname = "gjs_profiler_chain_signal")]

    public static bool chain_signal (Context ctx,

                                     Posix.siginfo_t info);

  }

  [CCode (cheader_filename = "gjs/mem.h",

          cname = "gjs_memory_report")]

  public void memory_report (string where,

                 bool die_if_fail);

  [CCode (cheader_filename = "gjs/coverage.h",

          cname = "GjsProfiler",

          type_id = "GJS_TYPE_COVERAGE")]

  public class Coverage : GLib.Object {

    /**

     * Prefixes of files on which to perform coverage analysis

     */

    public string prefixes {construct;}

    /**

     * A context to gather coverage stats for

     */

    public Context context {construct;}

    /**

     * Directory handle at which to output coverage statistics

     */

    public GLib.File output_directory {construct;}

    /**

     * Creates a new {@link Gjs.Coverage} object that collects coverage

     * information for any scripts run in context.

     *

     * Scripts which were provided as part of {@link prefixes} will be written

     * out to {@link output_dir}, in the same directory structure relative to

     * the source dir where the tests were run.

     *

     * @param coverage_prefixes A null-terminated strv of prefixes of files on

     * which to record code coverage

     *

     * @param coverage_context A {@link Gjs.Context} object

     *

     * @param output_dir A {@link GLib.File} handle to a directory in which to

     * write coverage information

     */

    [CCode (cname = "gjs_coverage_new")]

    public Coverage (string coverage_prefixes,

                     Context coverage_context,

                     GLib.File output_dir);

    /**

     * Scripts which were provided as part of the {@link Gjs.Coverage.prefixes}

     * construction property will be written out to {output_directory}, in the

     * same directory structure relative to the source dir where the tests were

     * run.

     *

     * This function takes all available statistics and writes them out to

     * either the file provided or to files of the pattern (filename).info in

     * the same directory as the scanned files. It will provide coverage data

     * for all files ending with ".js" in the coverage directories.

     */

    [CCode (cname = "gjs_coverage_write_statistics")]

    public void write_statistics ();

    /**

     * This function must be called before creating any {@link Gjs.Context}, 

     * if you intend to use any {@link Gjs.Coverage} APIs.

     */

    [CCode (cname = "gjs_coverage_enable")]

    public static void enable ();

  }

}