Evaluating JavaScript

## Evaluating JavaScript Evaluating JavaScript — Creating and interpreting scripts |

## Synopsis

    #include <seed/seed.h>

                        SeedScript;
    SeedScript *        seed_make_script                    (SeedContext ctx,
                                                             const gchar *js,
                                                             const gchar *source_url,
                                                             gint line_number);
    SeedValue           seed_evaluate                       (SeedContext ctx,
                                                             SeedScript *s,
                                                             SeedObject this_object);
    SeedValue           seed_simple_evaluate                (SeedContext ctx,
                                                             gchar *source,
                                                             SeedException *exception);
    SeedScript *        seed_script_new_from_file           (SeedContext ctx,
                                                             gchar *file);
    SeedException       seed_script_exception               (SeedScript *s);
    void                seed_script_destroy                 (SeedScript *s);

## Description

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.

Example 7. Create and evaluate a string of JavaScript with `seed_make_script()`

    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);

    ...

Example 8. Create and evaluate a string of JavaScript with `seed_simple_evaluate()`

    SeedEngine * eng;

    ...

    /* Evaluate a simple JavaScript snippet in the default context */
    seed_simple_evaluate(eng->context, "print('Hello, world!')", NULL);

    ...

## Details

### SeedScript

    typedef struct {
      JSStringRef script;
      JSValueRef exception;

      JSStringRef source_url;
      gint line_number;
    } SeedScript;

### seed_make_script ()

    SeedScript *        seed_make_script                    (SeedContext ctx,
                                                             const gchar *js,
                                                             const gchar *source_url,
                                                             gint line_number);

Creates a new SeedScript instance with `js` as the contents, then checks for proper syntax.

Note: `seed_make_script()` does not handle the shebang line, and will return a parse error if one is included in `js`.

`ctx` : | A SeedContext.
`js` : | A string representing the contents of the script.
`source_url` : | The filename of the script, for reference in errors, or `NULL`.
`line_number` : | The line number of the beginning of the script, for reference in error messages, or `NULL`.
Returns : | The newly created SeedScript.

### seed_evaluate ()

    SeedValue           seed_evaluate                       (SeedContext ctx,
                                                             SeedScript *s,
                                                             SeedObject this_object);

Evaluates a SeedScript with `this` as the global "this" object.

`ctx` : | A SeedContext.
`s` : | A SeedScript to evaluate.
Returns : | The SeedValue returned by evaluating the script.

### seed_simple_evaluate ()

    SeedValue           seed_simple_evaluate                (SeedContext ctx,
                                                             gchar *source,
                                                             SeedException *exception);

Evaluates a string of JavaScript in `ctx`; if an exception is raised in the context of the script, it will be placed in `exception`.

`ctx` : | A SeedContext.
`source` : | A string representing the JavaScript to evaluate.
`exception` : | A SeedException pointer to store an exception in.
Returns : | The SeedValue returned by evaluating the script.

### seed_script_new_from_file ()

    SeedScript *        seed_script_new_from_file           (SeedContext ctx,
                                                             gchar *file);

Uses `seed_make_script()` to create a SeedScript from the contents of `file`.

`ctx` : | A SeedContext.
`file` : | The filename of the script to load.
Returns : | The newly created SeedScript.

### seed_script_exception ()

    SeedException       seed_script_exception               (SeedScript *s);

Retrieves the exception (if any) raised during the evaluation of `s`.

`s` : | A SeedScript.
Returns : | A SeedException representing the exception of `s`.

### seed_script_destroy ()

    void                seed_script_destroy                 (SeedScript *s);