Usage

Following its design, sjs can be used in 2 ways: the CLI and the C API.

CLI

This is the typical way to run JavaScript applications with sjs, by using the sjs binary.

sjs -h
Usage: sjs [options] [ <code> | <file> | - ]

-h         show help text
-i         enter interactive mode after executing argument file(s) / eval code
-e CODE    evaluate code

If <file> is omitted, interactive mode is started automatically.

With the sjs CLI you can execute a file, eval some code directly from the command line, or enter the interactive mode.

Note

When using the CLI sjs will try to pretify the output of every command by serializing it using a JSON variant called JX which Duktape includes.

Embedding sjs in your application

The sjs VM API allows applications to execute JavaScript code using the sjs engine. The prime example is the sjs CLI, see src/cli/main.c.

With this C API applications willing to run JavaScript code can embed the sjs engine or link with libsjs.

Data types

sjs_vm_t

Opaque type encapsulating the sjs VM.

duk_context

Opaque type encapsulating the Duktape engine.

API

Main VM API

sjs_vm_t* sjs_vm_create(void)

Create a sjs VM.

Returns:The initialized VM.
void sjs_vm_destroy(sjs_vm_t* vm)

Destroy the given VM. It can no longer be used after calling this function.

Parameters:
  • vm – The VM which will be destroyed.
void sjs_vm_setup_args(sjs_vm_t* vm, int argc, char* argv[])

Setup the VM’s arguments. This is required for initializing some internals in the system module.

Parameters:
  • vm – The VM reference.
  • argc – Number of arguments in the array.
  • argv – Array with arguments, in comman-line form.
duk_context* sjs_vm_get_duk_ctx(sjs_vm_t* vm)

Get the reference to the Duktape engine associated with the VM.

Parameters:
  • vm – The VM reference.
Returns:

The Duktape context.
sjs_vm_t* sjs_vm_get_vm(duk_context* ctx)

Get the reference to the sjs VM associated with the given Duktape context.

Parameters:
  • ctx – The Duktape context.
Returns:

The sjs VM instance.
int sjs_vm_eval_code(const sjs_vm_t* vm, const char* filename, const char* code, size_t len, FILE* foutput, FILE* ferror)

Evaluate the given JavaScript code. The code is wrapped in a CommonJS module function and executed.

Parameters:
  • vm – The VM reference.
  • filename – Indicates the filename that is being executed. It will be printed in tracebacks and such.
  • code – What is going to be executed.
  • len – Length of the code.
  • foutput – Stream where to print the result of the evaulated code (can be NULL).
  • ferror – Stream where to print errors, if any (can be NULL).
Returns:

0 if the code was evaluated without errors, != 0 otherwise.
int sjs_vm_eval_code_global(const sjs_vm_t* vm, const char* filename, const char* code, size_t len, FILE* foutput, FILE* ferror)

Similar to sjs_vm_eval_code() but it evaluates the code in the global scope instead of creating a new CommonJS style context.

int sjs_vm_eval_file(const sjs_vm_t* vm, const char* filename, FILE* foutput, FILE* ferror)

Evaluate the given file as JavaScript code. The code is wrapped in a CommonJS module function and executed.

Parameters:
  • vm – The VM reference.
  • filename – The file to be evaluated.
  • foutput – Stream where to print the result of the evaulated code (can be NULL).
  • ferror – Stream where to print errors, if any (can be NULL).
Returns:

0 if the code was evaluated without errors, != 0 otherwise.

Utility functions

int sjs_path_normalize(const char* path, char* normalized_path, size_t normalized_path_len)

Normalize the given path into the given buffer. Mormalizing a path includes tilde expansions and realpath(3).

Parameters:
  • path – The path which needs to be normalized.
  • normalized_path – Buffer to store the normalized path.
  • normalized_path_len – Size of normalized_path.
Returns:

0 on success, or < 0 on failure. The returned code is the negated errno.
int sjs_path_expanduser(const char* path, char* normalized_path, size_t normalized_path_len)

Similar to sjs_path_normalize() but in only performs tilde expansion.