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
-
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.