diff options
Diffstat (limited to 'doc/reference/tmpl')
| -rw-r--r-- | doc/reference/tmpl/seed-closure.sgml | 89 | ||||
| -rw-r--r-- | doc/reference/tmpl/seed-context.sgml | 124 | ||||
| -rw-r--r-- | doc/reference/tmpl/seed-eval.sgml | 125 | ||||
| -rw-r--r-- | doc/reference/tmpl/seed-exception.sgml | 145 | ||||
| -rw-r--r-- | doc/reference/tmpl/seed-jsclass.sgml | 83 | ||||
| -rw-r--r-- | doc/reference/tmpl/seed-main.sgml | 94 | ||||
| -rw-r--r-- | doc/reference/tmpl/seed-main.sgml.sgml | 226 | ||||
| -rw-r--r-- | doc/reference/tmpl/seed-modules.sgml | 146 | ||||
| -rw-r--r-- | doc/reference/tmpl/seed-nativefuncs.sgml | 100 | ||||
| -rw-r--r-- | doc/reference/tmpl/seed-nativetypes.sgml | 121 | ||||
| -rw-r--r-- | doc/reference/tmpl/seed-object.sgml | 285 | ||||
| -rw-r--r-- | doc/reference/tmpl/seed-signals.sgml | 45 | ||||
| -rw-r--r-- | doc/reference/tmpl/seed-string.sgml | 10 | ||||
| -rw-r--r-- | doc/reference/tmpl/seed-typeconversion.sgml | 474 | ||||
| -rw-r--r-- | doc/reference/tmpl/seed.sgml | 160 |
15 files changed, 2227 insertions, 0 deletions
diff --git a/doc/reference/tmpl/seed-closure.sgml b/doc/reference/tmpl/seed-closure.sgml new file mode 100644 index 0000000..fad2dbd --- /dev/null +++ b/doc/reference/tmpl/seed-closure.sgml @@ -0,0 +1,89 @@ +<!-- ##### SECTION Title ##### --> +Using JavaScript closures + +<!-- ##### SECTION Short_Description ##### --> +Creating and invoking closures over JavaScript functions using GClosure + +<!-- ##### SECTION Long_Description ##### --> +<para> +Long description +</para> + +<!-- ##### SECTION See_Also ##### --> +<para> + +</para> + +<!-- ##### SECTION Stability_Level ##### --> + + +<!-- ##### SECTION Image ##### --> + + +<!-- ##### STRUCT SeedClosure ##### --> +<para> + +</para> + +@closure: +@function: +@user_data: +@return_type: +@description: + +<!-- ##### FUNCTION seed_closure_new ##### --> +<para> + +</para> + +@ctx: +@function: +@user_data: +@description: +@Returns: + + +<!-- ##### FUNCTION seed_closure_get_callable ##### --> +<para> + +</para> + +@c: +@Returns: + + +<!-- ##### FUNCTION seed_closure_invoke ##### --> +<para> + +</para> + +@closure: +@args: +@argc: +@exception: +@Returns: + + +<!-- ##### FUNCTION seed_closure_invoke_with_context ##### --> +<para> + +</para> + +@ctx: +@closure: +@args: +@argc: +@exception: +@Returns: + + +<!-- ##### FUNCTION seed_closure_warn_exception ##### --> +<para> + +</para> + +@c: +@ctx: +@exception: + + diff --git a/doc/reference/tmpl/seed-context.sgml b/doc/reference/tmpl/seed-context.sgml new file mode 100644 index 0000000..edf9908 --- /dev/null +++ b/doc/reference/tmpl/seed-context.sgml @@ -0,0 +1,124 @@ +<!-- ##### SECTION Title ##### --> +Working with Contexts + +<!-- ##### SECTION Short_Description ##### --> +Self-contained JavaScript execution environments + +<!-- ##### SECTION Long_Description ##### --> +<para> +A #SeedContext provides a complete "universe" for the execution of JavaScript. You can use seed_context_create() to create a sandboxed context that lacks the import system, so it can be used to execute somewhat untrusted JavaScript (as it has no way to access the rest of your system). You can also expose the default set of globals (including "print", "imports", and "Seed") to create more powerful but still self-contained environments within which to execute code. +</para> + +<example> +<title>Using a Seed context as a form of sandboxing</title> +<programlisting> +... +ctx = seed_context_create(NULL, NULL); +script = seed_make_script(ctx, "print(imports)", NULL, 0); +// nothing is printed, because imports is undefined, because we're in a sandbox +... +</programlisting> +</example> + +<para>The <link linkend="Sandbox-module">sandbox</link> module provides access to this system from the JavaScript side of Seed. +</para> + +<!-- ##### SECTION See_Also ##### --> +<para> + +</para> + +<!-- ##### SECTION Stability_Level ##### --> + + +<!-- ##### SECTION Image ##### --> + + +<!-- ##### TYPEDEF SeedContext ##### --> +<para> + +</para> + + +<!-- ##### TYPEDEF SeedGlobalContext ##### --> +<para> + +</para> + + +<!-- ##### TYPEDEF SeedContextGroup ##### --> +<para> + +</para> + + +<!-- ##### FUNCTION seed_context_create ##### --> +<para> + +</para> + +@group: +@global_class: +@Returns: + + +<!-- ##### FUNCTION seed_context_ref ##### --> +<para> + +</para> + +@ctx: +@Returns: + + +<!-- ##### FUNCTION seed_context_unref ##### --> +<para> + +</para> + +@ctx: + + +<!-- ##### FUNCTION seed_context_collect ##### --> +<para> + +</para> + +@ctx: + + +<!-- ##### FUNCTION seed_context_get_global_object ##### --> +<para> + +</para> + +@ctx: +@Returns: + + +<!-- ##### FUNCTION seed_prepare_global_context ##### --> +<para> + +</para> + +@ctx: + + +<!-- ##### FUNCTION seed_importer_add_global ##### --> +<para> + +</para> + +@ctx: +@name: + + +<!-- ##### FUNCTION seed_importer_set_search_path ##### --> +<para> + +</para> + +@ctx: +@search_path: + + diff --git a/doc/reference/tmpl/seed-eval.sgml b/doc/reference/tmpl/seed-eval.sgml new file mode 100644 index 0000000..f3fbecd --- /dev/null +++ b/doc/reference/tmpl/seed-eval.sgml @@ -0,0 +1,125 @@ +<!-- ##### SECTION Title ##### --> +Evaluating JavaScript + +<!-- ##### SECTION Short_Description ##### --> +Creating and interpreting scripts + +<!-- ##### SECTION Long_Description ##### --> +<para> +Seed relies on WebKit's JavaScriptCore interpreter to actually evaluate snippets of JavaScript; however, it provides a handful of useful wrapper functions to quickly create and evaluate scripts. seed_make_script() and seed_evaluate() are the workhorse functions; these allow you to control every detail of the created script and its evaluation environment (including customizing the "this" object during evaluation, and setting a starting line number and filename from which the script originates). seed_simple_evaluate() provides an interface to execute a string of JavaScript without previously creating a #SeedScript, and, while requiring less supporting code, is less flexible. +</para> + +<example> +<title>Create and evaluate a string of JavaScript with seed_make_script()</title> +<programlisting> +SeedEngine * eng; + +... + +SeedScript * script; +/* Create a simple #SeedScript */ +script = seed_make_script(eng->context, "print('Hello, world!')", NULL, 0); + +/* Evaluate the #SeedScript in the default context */ +seed_evaluate(eng->context, script, 0); + +... +</programlisting> +</example> + +<example> +<title>Create and evaluate a string of JavaScript with seed_simple_evaluate()</title> +<programlisting> +SeedEngine * eng; + +... + +/* Evaluate a simple JavaScript snippet in the default context */ +seed_simple_evaluate(eng->context, "print('Hello, world!')", NULL); + +... +</programlisting> +</example> + +<!-- ##### SECTION See_Also ##### --> +<para> + +</para> + +<!-- ##### SECTION Stability_Level ##### --> + + +<!-- ##### SECTION Image ##### --> + + +<!-- ##### STRUCT SeedScript ##### --> +<para> + +</para> + +@script: +@exception: +@source_url: +@line_number: + +<!-- ##### FUNCTION seed_make_script ##### --> +<para> + +</para> + +@ctx: +@js: +@source_url: +@line_number: +@Returns: + + +<!-- ##### FUNCTION seed_evaluate ##### --> +<para> + +</para> + +@ctx: +@s: +@this_object: +@Returns: + + +<!-- ##### FUNCTION seed_simple_evaluate ##### --> +<para> + +</para> + +@ctx: +@source: +@exception: +@Returns: + + +<!-- ##### FUNCTION seed_script_new_from_file ##### --> +<para> + +</para> + +@ctx: +@file: +@Returns: + + +<!-- ##### FUNCTION seed_script_exception ##### --> +<para> + +</para> + +@s: +@Returns: + + +<!-- ##### FUNCTION seed_script_destroy ##### --> +<para> + +</para> + +@s: + + diff --git a/doc/reference/tmpl/seed-exception.sgml b/doc/reference/tmpl/seed-exception.sgml new file mode 100644 index 0000000..943eb5b --- /dev/null +++ b/doc/reference/tmpl/seed-exception.sgml @@ -0,0 +1,145 @@ +<!-- ##### SECTION Title ##### --> +Exception Handling + +<!-- ##### SECTION Short_Description ##### --> +Throwing and catching exceptions + +<!-- ##### SECTION Long_Description ##### --> +<para> +Seed uses exceptions as a method of handling runtime errors within scripts. An exception consists of a name (a list of commonly-used exception names is below), a message, detailing the error, and the line number and filename from which the exception was raised. If Seed cannot determine from where the exception was raised, the line number and filename will be undefined. seed_exception_to_string() provides a simple way to convert all of these into a consistent representation to display to users. +</para> + +<para> +All Seed callbacks take an exception argument; calling +seed_make_exception() with this argument and the details you wish to +fill it with will propogate that exception up the chain. Exceptions +can be <emphasis>caught</emphasis> either by a try/catch block in the +calling JavaScript, or by observing the exception property, dealing +with it, and then clearing the exception. + +It is important to note that calling seed_make_exception() does not +in fact <emphasis>throw</emphasis> the exception, but just creates an +object which, when stored in the exception pointer passed to a callback, +causes JSC to throw an exception once flow is returned. +</para> + +<example> +<title>Throw an exception, because <function>random_callback</function> was called with the wrong number of arguments</title> +<programlisting> +SeedValue random_callback(SeedContext ctx, + SeedObject function, + SeedObject this_object, + gsize argument_count, + const SeedValue arguments[], + SeedException *exception) +{ + ... + + if(argument_count != 1) + { + seed_make_exception(ctx, exception, "ArgumentError", + "wrong number of arguments; expected 1, got %zd", + argument_count); + return seed_make_undefined(ctx); + } + + ... +} +</programlisting> +</example> + +<note> +<title>Predefined Exception Names</title> +<para> +<itemizedlist> + <listitem><emphasis>InvalidPropertyValue</emphasis> - a property was set to a value out of range</listitem> + <listitem><emphasis>PropertyError</emphasis> - a warning occurred in GLib while trying to set a property</listitem> + <listitem><emphasis>ArgumentError</emphasis> - a function was called with the wrong number of arguments</listitem> + <listitem><emphasis>ConversionError</emphasis> - one of the type conversion functions threw an exception</listitem> + <listitem><emphasis>TypeError</emphasis> - a required argument was of the wrong type</listitem> + <listitem><emphasis>SyntaxError</emphasis> - a syntax error was thrown from JavaScriptCore</listitem> + <listitem><emphasis>ParseError</emphasis> - a parsing error was thrown from JavaScriptCore (make sure you close all of your brackets!)</listitem> + <listitem><emphasis>ReferenceError</emphasis> - a reference error was thrown from JavaScriptCore (most likely, you tried to access a variable which was undefined)</listitem> +</itemizedlist> +</para> +</note> + +<!-- ##### SECTION See_Also ##### --> +<para> + +</para> + +<!-- ##### SECTION Stability_Level ##### --> + + +<!-- ##### SECTION Image ##### --> + + +<!-- ##### TYPEDEF SeedException ##### --> +<para> + +</para> + + +<!-- ##### FUNCTION seed_make_exception ##### --> +<para> + +</para> + +@ctx: +@exception: +@name: +@message: +@...: + + +<!-- ##### FUNCTION seed_exception_get_name ##### --> +<para> + +</para> + +@ctx: +@exception: +@Returns: + + +<!-- ##### FUNCTION seed_exception_get_message ##### --> +<para> + +</para> + +@ctx: +@exception: +@Returns: + + +<!-- ##### FUNCTION seed_exception_get_line ##### --> +<para> + +</para> + +@ctx: +@exception: +@Returns: + + +<!-- ##### FUNCTION seed_exception_get_file ##### --> +<para> + +</para> + +@ctx: +@exception: +@Returns: + + +<!-- ##### FUNCTION seed_exception_to_string ##### --> +<para> + +</para> + +@ctx: +@exception: +@Returns: + + diff --git a/doc/reference/tmpl/seed-jsclass.sgml b/doc/reference/tmpl/seed-jsclass.sgml new file mode 100644 index 0000000..c0ea39b --- /dev/null +++ b/doc/reference/tmpl/seed-jsclass.sgml @@ -0,0 +1,83 @@ +<!-- ##### SECTION Title ##### --> +Creating JavaScript classes + +<!-- ##### SECTION Short_Description ##### --> +Dealing with Seed class definitions and constructors + +<!-- ##### SECTION Long_Description ##### --> +<para> +Defining new Seed classes allows for implementing more complex +behavior than possible with the traditional JavaScript object system +and default class. + +When writing Seed modules, it is often the best pattern to define many +of your types through classes and static functions/value. + +Please note that inside the finalize callback of a class, it is not +legal to call any method requiring a #SeedContext (with the exception +of protect/unprotect, though it is not guaranteed this will continue +to work with future versions of JSCore). +</para> + +<!-- ##### SECTION See_Also ##### --> +<para> + +</para> + +<!-- ##### SECTION Stability_Level ##### --> + + +<!-- ##### SECTION Image ##### --> + + +<!-- ##### ENUM SeedPropertyAttributes ##### --> +<para> + +</para> + +@SEED_PROPERTY_ATTRIBUTE_NONE: +@SEED_PROPERTY_ATTRIBUTE_READ_ONLY: +@SEED_PROPERTY_ATTRIBUTE_DONT_ENUM: +@SEED_PROPERTY_ATTRIBUTE_DONT_DELETE: + +<!-- ##### ENUM SeedClassAttributes ##### --> +<para> + +</para> + +@SEED_CLASS_ATTRIBUTE_NONE: +@SEED_CLASS_ATTRIBUTE_NO_SHARED_PROTOTYPE: + +<!-- ##### TYPEDEF SeedClass ##### --> +<para> + +</para> + + +<!-- ##### MACRO seed_empty_class ##### --> +<para> + +</para> + + + +<!-- ##### FUNCTION seed_create_class ##### --> +<para> + +</para> + +@def: +@Returns: + + +<!-- ##### FUNCTION seed_make_constructor ##### --> +<para> + +</para> + +@ctx: +@klass: +@constructor: +@Returns: + + diff --git a/doc/reference/tmpl/seed-main.sgml b/doc/reference/tmpl/seed-main.sgml new file mode 100644 index 0000000..26fd9c7 --- /dev/null +++ b/doc/reference/tmpl/seed-main.sgml @@ -0,0 +1,94 @@ +<!-- ##### SECTION Title ##### --> +Initialization + +<!-- ##### SECTION Short_Description ##### --> +Overall setup of the Seed engine + +<!-- ##### SECTION Long_Description ##### --> +<para> +Before any other Seed functions can be used, you must initialize the engine, which creates an initial JavaScript context and sets up JavaScriptCore and GLib. To do this in most cases, you will use seed_init(), which will provide you with a #SeedEngine. Only one #SeedEngine is permitted per application; use a #SeedContext to sandbox code execution. +</para> + +<example> +<title>Very simple <function>main</function> function for a Seed program</title> +<programlisting> +int main (int argc, char **argv) +{ + SeedEngine * eng; + SeedScript * script; + + /* Initialize the Seed engine */ + eng = seed_init(&argc, &argv); + + /* Create a simple #SeedScript */ + script = seed_make_script(eng->context, "print('Hello, world!')", NULL, 0); + + /* Evaluate the #SeedScript in the default context */ + seed_evaluate(eng->context, script, 0); + + g_free(script); + return 0; +} +</programlisting> +</example> + +<!-- ##### SECTION See_Also ##### --> +<para> + +</para> + +<!-- ##### SECTION Stability_Level ##### --> + + +<!-- ##### SECTION Image ##### --> + + +<!-- ##### STRUCT SeedEngine ##### --> +<para> + +</para> + +@context: +@global: +@search_path: +@group: + +<!-- ##### FUNCTION seed_init ##### --> +<para> + +</para> + +@argc: +@argv: +@Returns: + + +<!-- ##### FUNCTION seed_init_with_context_group ##### --> +<para> + +</para> + +@argc: +@argv: +@group: +@Returns: + + +<!-- ##### FUNCTION seed_engine_set_search_path ##### --> +<para> + +</para> + +@eng: +@path: + + +<!-- ##### FUNCTION seed_engine_get_search_path ##### --> +<para> + +</para> + +@eng: +@Returns: + + diff --git a/doc/reference/tmpl/seed-main.sgml.sgml b/doc/reference/tmpl/seed-main.sgml.sgml new file mode 100644 index 0000000..463c7a4 --- /dev/null +++ b/doc/reference/tmpl/seed-main.sgml.sgml @@ -0,0 +1,226 @@ +<!-- ##### SECTION Title ##### --> +seed-main.sgml + +<!-- ##### SECTION Short_Description ##### --> + + +<!-- ##### SECTION Long_Description ##### --> +<para> + +</para> + + +<!-- ##### SECTION See_Also ##### --> +<para> + +</para> + + +<!-- ##### SECTION Stability_Level ##### --> + + +<!-- ##### FUNCTION seed_init ##### --> +<para> + +</para> + +@argc: +@argv: +@Returns: + + +<!-- ##### FUNCTION seed_init_with_context_group ##### --> +<para> + +</para> + +@argc: +@argv: +@group: +@Returns: + + +<!-- ##### FUNCTION seed_importer_add_global ##### --> +<para> + +</para> + +@ctx: +@name: + + +<!-- ##### FUNCTION seed_importer_set_search_path ##### --> +<para> + +</para> + +@ctx: +@search_path: + + +<!-- ##### FUNCTION seed_engine_set_search_path ##### --> +<para> + +</para> + +@eng: +@path: + + +<!-- ##### FUNCTION seed_engine_get_search_path ##### --> +<para> + +</para> + +@eng: +@Returns: + + +<!-- ##### STRUCT SeedScript ##### --> +<para> + +</para> + + +<!-- ##### FUNCTION seed_make_script ##### --> +<para> + +</para> + +@ctx: +@js: +@source_url: +@line_number: +@Returns: + + +<!-- ##### FUNCTION seed_evaluate ##### --> +<para> + +</para> + +@ctx: +@s: +@this: +@Returns: + + +<!-- ##### FUNCTION seed_simple_evaluate ##### --> +<para> + +</para> + +@ctx: +@source: +@exception: +@Returns: + + +<!-- ##### FUNCTION seed_script_new_from_file ##### --> +<para> + +</para> + +@ctx: +@file: +@Returns: + + +<!-- ##### FUNCTION seed_script_exception ##### --> +<para> + +</para> + +@s: +@Returns: + + +<!-- ##### FUNCTION seed_make_function ##### --> +<para> + +</para> + +@ctx: +@callback: +@name: +@Returns: + + +<!-- ##### FUNCTION seed_create_function ##### --> +<para> + +</para> + +@ctx: +@name: +@callback: +@object: + + +<!-- ##### FUNCTION seed_make_constructor ##### --> +<para> + +</para> + +@ctx: +@class: +@Param3: +@Returns: + + +<!-- ##### FUNCTION seed_pointer_get_pointer ##### --> +<para> + +</para> + +@ctx: +@pointer: +@Returns: + + +<!-- ##### USER_FUNCTION SeedFunctionCallback ##### --> +<para> + +</para> + +@ctx: +@function: +@this_object: +@argument_count: +@arguments: +@excecption: +@Returns: + + +<!-- ##### USER_FUNCTION SeedModuleInitCallback ##### --> +<para> + +</para> + +@eng: +@Returns: + + +<!-- ##### FUNCTION seed_signal_connect ##### --> +<para> + +</para> + +@ctx: +@object: +@signal: +@script: + + +<!-- ##### FUNCTION seed_signal_connect_value ##### --> +<para> + +</para> + +@ctx: +@object: +@signal: +@function: +@user_data: + + diff --git a/doc/reference/tmpl/seed-modules.sgml b/doc/reference/tmpl/seed-modules.sgml new file mode 100644 index 0000000..6528873 --- /dev/null +++ b/doc/reference/tmpl/seed-modules.sgml @@ -0,0 +1,146 @@ +<!-- ##### SECTION Title ##### --> +Seed Modules + +<!-- ##### SECTION Short_Description ##### --> +Native C modules for Seed + +<!-- ##### SECTION Long_Description ##### --> +<para> +Seed includes a simple system for creating C modules which can be loaded and manipulated from JavaScript. This is used for implementing performance-critical code closer to the silicon, as well as binding non-introspectable libraries in an attractive way. +</para> + +<para>Numerous binding modules are included in the Seed repository; when writing a new native module, it would be wise to look over these before beginning, as they have many tidbits of useful knowledge for writing modules.</para> + +<example> +<title>Very simple example C module</title> +<programlisting> +#include <glib.h> +#include <seed-module.h> + +SeedObject seed_module_init(SeedEngine * eng) +{ + /* Say hello! */ + g_print("Hello, Seed Module World!\n"); + + /* Return an empty object as the module's namespace */ + return seed_make_object (eng->context, NULL, NULL); +} +</programlisting> +</example> + +<para>Above is a C module which does absolutely nothing useful. When a module is loaded, seed_module_init() is called, which should have the signature of SeedModuleInitCallback(). You're passed the global #SeedEngine, and the value you return is the namespace for your module. Say, for example, you place a static function on that object:</para> + +<example> +<title>C module with a function</title> +<programlisting> +#include <glib.h> +#include <seed-module.h> + +/* Our function, with the signature of SeedFunctionCallback(); say hello! */ +SeedValue say_hello_to(SeedContext ctx, + SeedObject function, + SeedObject this_object, + gsize argument_count, + const SeedValue arguments[], + SeedException *exception) +{ + guchar * name; + + /* Check that only one argument was passed into the function. + CHECK_ARG_COUNT() is from seed-module.h, which you might find useful. */ + CHECK_ARG_COUNT("hello.say_hello_to", 1); + + /* Convert the first argument, a #SeedValue, to a C string */ + name = seed_value_to_string(ctx, arguments[0], exception); + + g_print("Hello, %s!\n", name); + + g_free(name); + + return seed_make_null(ctx); +} + +/* Define an array of #seed_static_function */ +seed_static_function gettext_funcs[] = { + {"say_hello_to", say_hello_to, 0} +}; + +SeedObject seed_module_init(SeedEngine * eng) +{ + SeedGlobalContext ctx = eng->context; + + /* Create a new class definition with our array of static functions */ + seed_class_definition ns_class_def = seed_empty_class; + ns_class_def.static_functions = example_funcs; + + /* Create a class from the class definition we just created */ + SeedClass ns_class = seed_create_class(&ns_class_def); + + /* Instantiate the class; this instance will be the namespace we return */ + ns_ref = seed_make_object (ctx, ns_class, NULL); + seed_value_protect (ctx, ns_ref); + + return ns_ref; +} +</programlisting> +</example> + +<para>After building and installing this module (look in the Seed build system for examples of how to get this to work, as well as a copy of seed-module.h, which will be very useful), it will be loadable with the normal Seed import system. Assuming it's installed as libseed_hello.so:</para> + +<example> +<title>Utilize our second example C module from JavaScript</title> +<programlisting> +hello = imports.hello; + +hello.say_hello_to("Tim"); +</programlisting> +</example> + +<!-- ##### SECTION See_Also ##### --> +<para> + +</para> + +<!-- ##### SECTION Stability_Level ##### --> + + +<!-- ##### SECTION Image ##### --> + + +<!-- ##### MACRO CHECK_ARG_COUNT ##### --> +<para> + +</para> + +@name: +@argnum: + + +<!-- ##### MACRO DEFINE_ENUM_MEMBER ##### --> +<para> + +</para> + +@holder: +@member: + + +<!-- ##### MACRO DEFINE_ENUM_MEMBER_EXT ##### --> +<para> + +</para> + +@holder: +@name: +@val: + + +<!-- ##### USER_FUNCTION SeedModuleInitCallback ##### --> +<para> + +</para> + +@eng: +@Returns: + + diff --git a/doc/reference/tmpl/seed-nativefuncs.sgml b/doc/reference/tmpl/seed-nativefuncs.sgml new file mode 100644 index 0000000..e09b611 --- /dev/null +++ b/doc/reference/tmpl/seed-nativefuncs.sgml @@ -0,0 +1,100 @@ +<!-- ##### SECTION Title ##### --> +Creating native functions + +<!-- ##### SECTION Short_Description ##### --> +C functions as first-class JavaScript objects + +<!-- ##### SECTION Long_Description ##### --> +<para> +Exposing native C functions to JavaScript is one of the fundamental use cases for libseed when used in an embedding environment; if your application cannot be introspected, or you only have a small number of functions to expose, this is the simplest way to do that. +</para> + +<para> +All native C callbacks should have the prototype of SeedFunctionCallback(). +</para> + +<example> +<title>Simple C program which embeds Seed with one exposed function</title> +<programlisting> +#include <glib.h> +#include <seed.h> + +/* Our function, with the signature of SeedFunctionCallback(); say hello! */ +SeedValue hello_world(SeedContext ctx, + SeedObject function, + SeedObject this_object, + gsize argument_count, + const SeedValue arguments[], + SeedException *exception) +{ + g_print("Hello, World!\n"); + return seed_make_null(ctx); +} + +int main(gint argc, gchar ** argv) +{ + SeedEngine * eng; + + /* Initialize the Seed engine */ + eng = seed_init(&argc, &argv); + + /* Expose a C function to JavaScript */ + seed_create_function(eng->context, "hello_world", + (SeedFunctionCallback)hello_world, + eng->global); + + /* Call the newly created JavaScript function */ + seed_simple_evaluate(eng->context, "hello_world()", NULL); + + return 0; +} +</programlisting> +</example> + +<!-- ##### SECTION See_Also ##### --> +<para> + +</para> + +<!-- ##### SECTION Stability_Level ##### --> + + +<!-- ##### SECTION Image ##### --> + + +<!-- ##### USER_FUNCTION SeedFunctionCallback ##### --> +<para> + +</para> + +@ctx: +@function: +@this_object: +@argument_count: +@arguments: +@exception: +@Returns: + + +<!-- ##### FUNCTION seed_make_function ##### --> +<para> + +</para> + +@ctx: +@func: +@name: +@Returns: + + +<!-- ##### FUNCTION seed_create_function ##### --> +<para> + +</para> + +@ctx: +@name: +@func: +@obj: + + diff --git a/doc/reference/tmpl/seed-nativetypes.sgml b/doc/reference/tmpl/seed-nativetypes.sgml new file mode 100644 index 0000000..e28fc1a --- /dev/null +++ b/doc/reference/tmpl/seed-nativetypes.sgml @@ -0,0 +1,121 @@ +<!-- ##### SECTION Title ##### --> +Operating on JavaScript types + +<!-- ##### SECTION Short_Description ##### --> +Determining the type of a SeedValue + +<!-- ##### SECTION Long_Description ##### --> +<para> +Long description +</para> + +<!-- ##### SECTION See_Also ##### --> +<para> + +</para> + +<!-- ##### SECTION Stability_Level ##### --> + + +<!-- ##### SECTION Image ##### --> + + +<!-- ##### FUNCTION seed_value_unprotect ##### --> +<para> + +</para> + +@ctx: +@value: + + +<!-- ##### FUNCTION seed_value_protect ##### --> +<para> + +</para> + +@ctx: +@value: + + +<!-- ##### FUNCTION seed_value_is_undefined ##### --> +<para> + +</para> + +@ctx: +@value: +@Returns: + + +<!-- ##### FUNCTION seed_value_is_null ##### --> +<para> + +</para> + +@ctx: +@value: +@Returns: + + +<!-- ##### FUNCTION seed_value_is_function ##### --> +<para> + +</para> + +@ctx: +@value: +@Returns: + + +<!-- ##### FUNCTION seed_value_is_number ##### --> +<para> + +</para> + +@ctx: +@value: +@Returns: + + +<!-- ##### FUNCTION seed_value_is_string ##### --> +<para> + +</para> + +@ctx: +@value: +@Returns: + + +<!-- ##### FUNCTION seed_value_is_object_of_class ##### --> +<para> + +</para> + +@ctx: +@value: +@klass: +@Returns: + + +<!-- ##### FUNCTION seed_value_is_object ##### --> +<para> + +</para> + +@ctx: +@value: +@Returns: + + +<!-- ##### FUNCTION seed_value_get_type ##### --> +<para> + +</para> + +@ctx: +@value: +@Returns: + + diff --git a/doc/reference/tmpl/seed-object.sgml b/doc/reference/tmpl/seed-object.sgml new file mode 100644 index 0000000..ba8635a --- /dev/null +++ b/doc/reference/tmpl/seed-object.sgml @@ -0,0 +1,285 @@ +<!-- ##### SECTION Title ##### --> +Working with JavaScript objects + +<!-- ##### SECTION Short_Description ##### --> +Using properties, constructing objects, etc. + +<!-- ##### SECTION Long_Description ##### --> +<para> +Long description +</para> + +<!-- ##### SECTION See_Also ##### --> +<para> + +</para> + +<!-- ##### SECTION Stability_Level ##### --> + + +<!-- ##### SECTION Image ##### --> + + +<!-- ##### TYPEDEF SeedObject ##### --> +<para> + +</para> + + +<!-- ##### FUNCTION seed_make_object ##### --> +<para> + +</para> + +@ctx: +@klass: +@private_object: +@Returns: + + +<!-- ##### FUNCTION seed_make_array ##### --> +<para> + +</para> + +@ctx: +@elements: +@num_elements: +@exception: +@Returns: + + +<!-- ##### FUNCTION seed_object_call ##### --> +<para> + +</para> + +@ctx: +@object: +@this_object: +@argument_count: +@arguments: +@exception: +@Returns: + + +<!-- ##### FUNCTION seed_object_set_property_at_index ##### --> +<para> + +</para> + +@ctx: +@object: +@index: +@value: +@exception: + + +<!-- ##### FUNCTION seed_object_get_property_at_index ##### --> +<para> + +</para> + +@ctx: +@object: +@index: +@exception: +@Returns: + + +<!-- ##### FUNCTION seed_object_is_of_class ##### --> +<para> + +</para> + +@ctx: +@obj: +@klass: +@Returns: + + +<!-- ##### FUNCTION seed_object_get_private ##### --> +<para> + +</para> + +@object: +@Returns: + + +<!-- ##### FUNCTION seed_object_set_private ##### --> +<para> + +</para> + +@object: +@value: + + +<!-- ##### FUNCTION seed_object_get_property ##### --> +<para> + +</para> + +@ctx: +@object: +@name: +@Returns: + + +<!-- ##### FUNCTION seed_object_set_property ##### --> +<para> + +</para> + +@ctx: +@object: +@name: +@value: +@Returns: + + +<!-- ##### FUNCTION seed_object_get_prototype ##### --> +<para> + +</para> + +@ctx: +@obj: +@Returns: + + +<!-- ##### FUNCTION seed_object_copy_property_names ##### --> +<para> + +</para> + +@ctx: +@object: +@Returns: + + +<!-- ##### USER_FUNCTION SeedObjectInitializeCallback ##### --> +<para> + +</para> + +@ctx: +@object: + + +<!-- ##### USER_FUNCTION SeedObjectFinalizeCallback ##### --> +<para> + +</para> + +@object: + + +<!-- ##### USER_FUNCTION SeedObjectHasPropertyCallback ##### --> +<para> + +</para> + +@ctx: +@object: +@string: +@Returns: + + +<!-- ##### USER_FUNCTION SeedObjectGetPropertyCallback ##### --> +<para> + +</para> + +@ctx: +@object: +@property_name: +@e: +@Returns: + + +<!-- ##### USER_FUNCTION SeedObjectSetPropertyCallback ##### --> +<para> + +</para> + +@ctx: +@object: +@property_name: +@value: +@e: +@Returns: + + +<!-- ##### USER_FUNCTION SeedObjectDeletePropertyCallback ##### --> +<para> + +</para> + +@ctx: +@object: +@property_name: +@e: +@Returns: + + +<!-- ##### USER_FUNCTION SeedObjectGetPropertyNamesCallback ##### --> +<para> + +</para> + +@void: + + +<!-- ##### USER_FUNCTION SeedObjectCallAsFunctionCallback ##### --> +<para> + +</para> + +@ctx: +@function: +@this_object: +@argument_count: +@arguments: +@exception: +@Returns: + + +<!-- ##### USER_FUNCTION SeedObjectHasInstanceCallback ##### --> +<para> + +</para> + +@ctx: +@constructor: +@instance_p: +@exception: +@Returns: + + +<!-- ##### USER_FUNCTION SeedObjectConvertToTypeCallback ##### --> +<para> + +</para> + +@ctx: +@object: +@type: +@exception: +@Returns: + + +<!-- ##### USER_FUNCTION SeedObjectCallAsConstructorCallback ##### --> +<para> + +</para> + +@ctx: +@constructor: +@argument_count: +@arguments: +@exception: +@Returns: + + diff --git a/doc/reference/tmpl/seed-signals.sgml b/doc/reference/tmpl/seed-signals.sgml new file mode 100644 index 0000000..17eba9f --- /dev/null +++ b/doc/reference/tmpl/seed-signals.sgml @@ -0,0 +1,45 @@ +<!-- ##### SECTION Title ##### --> +GObject Signals + +<!-- ##### SECTION Short_Description ##### --> +Connecting JavaScript functions to signals + +<!-- ##### SECTION Long_Description ##### --> +<para> +Long description +</para> + +<!-- ##### SECTION See_Also ##### --> +<para> + +</para> + +<!-- ##### SECTION Stability_Level ##### --> + + +<!-- ##### SECTION Image ##### --> + + +<!-- ##### FUNCTION seed_signal_connect ##### --> +<para> + +</para> + +@ctx: +@object: +@signal: +@script: + + +<!-- ##### FUNCTION seed_signal_connect_value ##### --> +<para> + +</para> + +@ctx: +@object: +@signal: +@function: +@user_data: + + diff --git a/doc/reference/tmpl/seed-string.sgml b/doc/reference/tmpl/seed-string.sgml new file mode 100644 index 0000000..c3e4d06 --- /dev/null +++ b/doc/reference/tmpl/seed-string.sgml @@ -0,0 +1,10 @@ +<!-- ##### SECTION Title ##### --> +SeedString + +<!-- ##### SECTION Short_Description ##### --> +This one should go away eventually + +<!-- ##### SECTION Long_Description ##### --> +<para> +Long description +</para> diff --git a/doc/reference/tmpl/seed-typeconversion.sgml b/doc/reference/tmpl/seed-typeconversion.sgml new file mode 100644 index 0000000..084a8d3 --- /dev/null +++ b/doc/reference/tmpl/seed-typeconversion.sgml @@ -0,0 +1,474 @@ +<!-- ##### SECTION Title ##### --> +Type Conversion + +<!-- ##### SECTION Short_Description ##### --> +Moving between JavaScript and C intrinsic types + +<!-- ##### SECTION Long_Description ##### --> +<para> +Long description +</para> + +<!-- ##### SECTION See_Also ##### --> +<para> + +</para> + +<!-- ##### SECTION Stability_Level ##### --> + + +<!-- ##### SECTION Image ##### --> + + +<!-- ##### TYPEDEF SeedValue ##### --> +<para> + +</para> + + +<!-- ##### ENUM SeedType ##### --> +<para> + +</para> + +@SEED_TYPE_UNDEFINED: +@SEED_TYPE_NULL: +@SEED_TYPE_BOOLEAN: +@SEED_TYPE_NUMBER: +@SEED_TYPE_STRING: +@SEED_TYPE_OBJECT: + +<!-- ##### FUNCTION seed_make_undefined ##### --> +<para> + +</para> + +@ctx: +@Returns: + + +<!-- ##### FUNCTION seed_make_null ##### --> +<para> + +</para> + +@ctx: +@Returns: + + +<!-- ##### FUNCTION seed_value_to_boolean ##### --> +<para> + +</para> + +@ctx: +@val: +@exception: +@Returns: + + +<!-- ##### FUNCTION seed_value_from_boolean ##### --> +<para> + +</para> + +@ctx: +@val: +@exception: +@Returns: + + +<!-- ##### FUNCTION seed_value_to_uint ##### --> +<para> + +</para> + +@ctx: +@val: +@exception: +@Returns: + + +<!-- ##### FUNCTION seed_value_from_uint ##### --> +<para> + +</para> + +@ctx: +@val: +@exception: +@Returns: + + +<!-- ##### FUNCTION seed_value_to_int ##### --> +<para> + +</para> + +@ctx: +@val: +@exception: +@Returns: + + +<!-- ##### FUNCTION seed_value_from_int ##### --> +<para> + +</para> + +@ctx: +@val: +@exception: +@Returns: + + +<!-- ##### FUNCTION seed_value_to_char ##### --> +<para> + +</para> + +@ctx: +@val: +@exception: +@Returns: + + +<!-- ##### FUNCTION seed_value_from_char ##### --> +<para> + +</para> + +@ctx: +@val: +@exception: +@Returns: + + +<!-- ##### FUNCTION seed_value_to_uchar ##### --> +<para> + +</para> + +@ctx: +@val: +@exception: +@Returns: + + +<!-- ##### FUNCTION seed_value_from_uchar ##### --> +<para> + +</para> + +@ctx: +@val: +@exception: +@Returns: + + +<!-- ##### FUNCTION seed_value_to_long ##### --> +<para> + +</para> + +@ctx: +@val: +@exception: +@Returns: + + +<!-- ##### FUNCTION seed_value_from_long ##### --> +<para> + +</para> + +@ctx: +@val: +@exception: +@Returns: + + +<!-- ##### FUNCTION seed_value_to_ulong ##### --> +<para> + +</para> + +@ctx: +@val: +@exception: +@Returns: + + +<!-- ##### FUNCTION seed_value_from_ulong ##### --> +<para> + +</para> + +@ctx: +@val: +@exception: +@Returns: + + +<!-- ##### FUNCTION seed_value_to_int64 ##### --> +<para> + +</para> + +@ctx: +@val: +@exception: +@Returns: + + +<!-- ##### FUNCTION seed_value_from_int64 ##### --> +<para> + +</para> + +@ctx: +@val: +@exception: +@Returns: + + +<!-- ##### FUNCTION seed_value_to_uint64 ##### --> +<para> + +</para> + +@ctx: +@val: +@exception: +@Returns: + + +<!-- ##### FUNCTION seed_value_from_uint64 ##### --> +<para> + +</para> + +@ctx: +@val: +@exception: +@Returns: + + +<!-- ##### FUNCTION seed_value_to_float ##### --> +<para> + +</para> + +@ctx: +@val: +@exception: +@Returns: + + +<!-- ##### FUNCTION seed_value_from_float ##### --> +<para> + +</para> + +@ctx: +@val: +@exception: +@Returns: + + +<!-- ##### FUNCTION seed_value_to_double ##### --> +<para> + +</para> + +@ctx: +@val: +@exception: +@Returns: + + +<!-- ##### FUNCTION seed_value_from_double ##### --> +<para> + +</para> + +@ctx: +@val: +@exception: +@Returns: + + +<!-- ##### FUNCTION seed_value_to_string ##### --> +<para> + +</para> + +@ctx: +@val: +@exception: +@Returns: + + +<!-- ##### FUNCTION seed_value_from_string ##### --> +<para> + +</para> + +@ctx: +@val: +@exception: +@Returns: + + +<!-- ##### FUNCTION seed_value_from_binary_string ##### --> +<para> + +</para> + +@ctx: +@bytes: +@n_bytes: +@exception: +@Returns: + + +<!-- ##### FUNCTION seed_value_to_object ##### --> +<para> + +</para> + +@ctx: +@val: +@exception: +@Returns: + + +<!-- ##### FUNCTION seed_value_from_object ##### --> +<para> + +</para> + +@ctx: +@val: +@exception: +@Returns: + + +<!-- ##### FUNCTION seed_value_to_filename ##### --> +<para> + +</para> + +@ctx: +@val: +@exception: +@Returns: + + +<!-- ##### FUNCTION seed_value_from_filename ##### --> +<para> + +</para> + +@ctx: +@val: +@exception: +@Returns: + + +<!-- ##### FUNCTION seed_value_to_format ##### --> +<para> + +</para> + +@ctx: +@format: +@values: +@exception: +@...: +@Returns: + + +<!-- ##### FUNCTION seed_pointer_get_pointer ##### --> +<para> + +</para> + +@ctx: +@pointer: +@Returns: + + +<!-- ##### FUNCTION seed_make_pointer ##### --> +<para> + +</para> + +@ctx: +@pointer: +@Returns: + + +<!-- ##### TYPEDEF SeedString ##### --> +<para> + +</para> + + +<!-- ##### FUNCTION seed_string_ref ##### --> +<para> + +</para> + +@string: +@Returns: + + +<!-- ##### FUNCTION seed_string_unref ##### --> +<para> + +</para> + +@string: + + +<!-- ##### FUNCTION seed_string_get_maximum_size ##### --> +<para> + +</para> + +@string: +@Returns: + + +<!-- ##### FUNCTION seed_string_to_utf8_buffer ##### --> +<para> + +</para> + +@string: +@buffer: +@buffer_size: +@Returns: + + +<!-- ##### FUNCTION seed_string_is_equal ##### --> +<para> + +</para> + +@a: +@b: +@Returns: + + +<!-- ##### FUNCTION seed_string_is_equal_utf8 ##### --> +<para> + +</para> + +@a: +@b: +@Returns: + + diff --git a/doc/reference/tmpl/seed.sgml b/doc/reference/tmpl/seed.sgml new file mode 100644 index 0000000..28a745c --- /dev/null +++ b/doc/reference/tmpl/seed.sgml @@ -0,0 +1,160 @@ +<!-- ##### SECTION Title ##### --> +seed + +<!-- ##### SECTION Short_Description ##### --> + + +<!-- ##### SECTION Long_Description ##### --> +<para> + +</para> + +<!-- ##### SECTION See_Also ##### --> +<para> + +</para> + +<!-- ##### SECTION Stability_Level ##### --> + + +<!-- ##### FUNCTION seed_init ##### --> +<para> + +</para> + +@argc: +@argv: +@Returns: + + +<!-- ##### FUNCTION seed_engine_set_search_path ##### --> +<para> + +</para> + +@eng: +@path: + + +<!-- ##### FUNCTION seed_engine_get_search_path ##### --> +<para> + +</para> + +@eng: +@Returns: + + +<!-- ##### STRUCT SeedScript ##### --> +<para> + +</para> + + +<!-- ##### FUNCTION seed_make_script ##### --> +<para> + +</para> + +@ctx: +@js: +@source_url: +@line_number: +@Returns: + + +<!-- ##### FUNCTION seed_evaluate ##### --> +<para> + +</para> + +@ctx: +@s: +@this: +@Returns: + + +<!-- ##### FUNCTION seed_simple_evaluate ##### --> +<para> + +</para> + +@ctx: +@source: +@exception: +@Returns: + + +<!-- ##### FUNCTION seed_script_new_from_file ##### --> +<para> + +</para> + +@ctx: +@file: +@Returns: + + +<!-- ##### FUNCTION seed_script_exception ##### --> +<para> + +</para> + +@s: +@Returns: + + +<!-- ##### FUNCTION seed_create_function ##### --> +<para> + +</para> + +@ctx: +@name: +@callback: +@object: + + +<!-- ##### FUNCTION seed_make_constructor ##### --> +<para> + +</para> + +@ctx: +@class: +@Param3: +@Returns: + + +<!-- ##### FUNCTION seed_pointer_get_pointer ##### --> +<para> + +</para> + +@ctx: +@pointer: +@Returns: + + +<!-- ##### USER_FUNCTION SeedFunctionCallback ##### --> +<para> + +</para> + +@ctx: +@function: +@this_object: +@argument_count: +@arguments: +@exception: + + +<!-- ##### USER_FUNCTION SeedModuleInitCallback ##### --> +<para> + +</para> + +@eng: +@Returns: + + |