embed.c

/*
 * embed.c -- a minimal host program that runs picoposh scripts.
 *
 * It shows what an embedder typically wants:
 *   1. a streaming output callback (pico_set_output),
 *   2. capturing output into a string (pico_run_capture),
 *   3. passing values in and reading a result out (sessions / pico_run_ex),
 *   4. bounding a script that might not terminate (pico_set_step_limit), and
 *   5. exposing a native function to scripts (pico_register_cmdlet).
 *
 * Build it as part of the picoposh tree (it links picoposh::picoposh), or
 * standalone against an installed picoposh -- see docs/embedding.md.
 */
#include "picoposh.h"
#include "picoposh_cmdlet.h"   /* only needed to write cmdlets, as in (5) */
#include <stdio.h>
#include <string.h>

/* An output sink: prefix each chunk so you can see it came through the host.
 * A real app might append to a text widget, a log, or a network buffer. */
static void on_output(void *userdata, int stream, const char *bytes,
                      unsigned long len)
{
    const char *tag = (stream == 0) ? "[out] " : "[err] ";
    FILE *dst = (stream == 0) ? stdout : stderr;
    (void)userdata;
    fputs(tag, dst);
    fwrite(bytes, 1, (size_t)len, dst);
}

/* A cmdlet the host provides. This is where an application's own domain logic
 * goes -- the whole point being that it lives in the application, not in a fork
 * of picoposh. Note the `static const` definition: pico_register_cmdlet borrows
 * it rather than copying, so it has to outlive every run. */
static pico_status host_sum_begin(PicoStage *ctx)
{
    pico_value a, b;
    long total = 0;
    pico_value out;

    if (pico_bp_arg(&ctx->bp, "A", 0, &a)) {
        total += pico_val_to_long(a);
        pico_val_release(a);
    }

    if (pico_bp_arg(&ctx->bp, "B", 1, &b)) {
        total += pico_val_to_long(b);
        pico_val_release(b);
    }

    out = pico_val_int(total);
    pico_emit(ctx, out);
    pico_val_release(out);

    return PICO_OK;
}

static const PicoParamDef host_sum_params[] = { { "A", 0, 0 }, { "B", 0, 1 } };
static const PicoCmdletDef host_sum = {
    "Get-HostSum", host_sum_params, 2, host_sum_begin, NULL, NULL,
    "Adds two numbers, provided by the host program."
};

int main(void)
{
    static const char *ok_script =
        "$n = 0\n"
        "foreach ($i in 1..5) { $n = $n + $i }\n"
        "Write-Output (\"sum 1..5 = \" + $n)\n"
        "Write-Output (\"upper: \" + \"mixed\".ToUpper())\n";
    char *out = NULL;
    char *err = NULL;
    int code;

    printf("picoposh %s embedded.\n\n", pico_version());

    /* (1) streaming: output flows through on_output as the script runs. */
    printf("--- streaming via pico_set_output ---\n");
    pico_set_output(on_output, NULL);
    pico_run_string(ok_script, "streamed");
    pico_set_output(NULL, NULL); /* restore normal stdout/stderr */

    /* (2) capture: collect stdout/stderr into strings. */
    printf("\n--- capture via pico_run_capture ---\n");
    code = pico_run_capture(ok_script, "captured", &out, &err);
    printf("exit code: %d\n", code);
    printf("captured stdout:\n%s", (out != NULL) ? out : "");
    pico_string_free(out);
    pico_string_free(err);

    /* (3) an error is reported on the stderr stream and via the exit code. */
    printf("\n--- an unsupported feature yields a clean error ---\n");
    out = NULL; err = NULL;
    code = pico_run_capture("trap { }\n", "bad", &out, &err);
    printf("exit code: %d (PICO_EXIT_UNSUPPORTED=%d)\n", code, PICO_EXIT_UNSUPPORTED);

    if (err != NULL)
        printf("captured stderr: %s", err);
    pico_string_free(out);
    pico_string_free(err);

    /* (4) values in, result out -- the script runs verbatim, with no preamble
     * of assignments and no printed epilogue to parse back. */
    printf("\n--- passing values in and out ---\n");
    {
        pico_var vars[2];
        char *ret = NULL;

        vars[0].name = "ScriptType";       vars[0].value = "Install";
        vars[1].name = "InstallDirectory"; vars[1].value = "C:\\Games\\Quake3";

        code = pico_run_ex(
            "$Return = \"$ScriptType into $InstallDirectory\"\n",
            "job", vars, 2, &ret);
        printf("exit code: %d\n", code);
        printf("$Return  : %s\n", (ret != NULL) ? ret : "(not set)");
        pico_string_free(ret);
    }

    /* A session does the same but keeps state, so variables and functions
     * defined in one run are available to the next. */
    printf("\n--- a session across several runs ---\n");
    {
        PicoSession *s = pico_session_new();
        char *v = NULL;

        if (s != NULL) {
            pico_session_set_variable(s, "Some Custom Field", "a value $ with \" quotes");
            pico_session_run(s, "function Double($n) { return $n * 2 }\n", "setup");
            pico_session_run(s, "$Answer = Double 21\n", "work");

            if (pico_session_get_variable(s, "Answer", &v) == 0) {
                printf("$Answer  : %s\n", v);
                pico_string_free(v);
            }

            /* the name and value never went through the parser, so neither
             * needed escaping */
            if (pico_session_get_variable(s, "Some Custom Field", &v) == 0) {
                printf("custom   : %s\n", v);
                pico_string_free(v);
            }
            pico_session_free(s);
        }
    }

    /* (5) a script that would never finish stops on the step budget instead of
     * hanging this program. */
    printf("\n--- a runaway loop is bounded ---\n");
    pico_set_step_limit(10000);
    out = NULL; err = NULL;
    code = pico_run_capture("while ($true) { }\n", "runaway", &out, &err);
    printf("exit code: %d (PICO_EXIT_RUNTIME=%d)\n", code, PICO_EXIT_RUNTIME);

    if (err != NULL)
        printf("%s", err);
    pico_string_free(out);
    pico_string_free(err);
    pico_set_step_limit(0);

    /* (6) a cmdlet the host supplies, callable from script like any built-in. */
    printf("\n--- a host-provided cmdlet ---\n");

    if (pico_register_cmdlet(&host_sum) == 0) {
        out = NULL; err = NULL;
        pico_run_capture("Write-Output (Get-HostSum 20 22)\n", "job", &out, &err);
        printf("Get-HostSum 20 22 -> %s", (out != NULL) ? out : "(nothing)");
        pico_string_free(out);
        pico_string_free(err);
        pico_unregister_cmdlets();
    }

    return 0;
}