YourWishes/jerryscript
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add support for doctests (#1909)

Browse Source 
Markdown files in the docs/ directory can now be annotated to turn
fenced C code blocks into unit tests. The recognized syntax is:

    [doctest]: # (name="test.c", test="run")

    ```c
    // unit test code
    ```

The commit also fixes the issues revealed during the initial
annotation.

JerryScript-DCO-1.0-Signed-off-by: Akos Kiss akiss@inf.u-szeged.hu
This commit is contained in:
Akos Kiss
2017-07-14 16:18:20 +02:00
committed by GitHub
parent 3d744c958f
commit 00f93bc287
11 changed files with 468 additions and 50 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/02.API-REFERENCE.md
+110 -16
View File
@@ -303,7 +303,13 @@ jerry_init (jerry_init_flag_t flags)
**Example**
[doctest]: # ()
```c
#include "jerryscript.h"
int
main (void)
{
jerry_init (JERRY_INIT_SHOW_OPCODES | JERRY_INIT_SHOW_REGEXP_OPCODES);
@@ -363,7 +369,11 @@ jerry_get_context_data (const jerry_context_data_manager *manager_p);
**Example**
[doctest]: # (test="compile")
```c
#include "jerryscript.h"
typedef struct
{
int my_data1;
@@ -404,7 +414,8 @@ static const jerry_context_data_manager_t my_manager =
* Then, in some function in your code, you can retrieve an item of type my_context_data_t from the currently active
* context such that JerryScript will create and store such an item if one was not previously created
*/
void someplace_in_the_code (void)
static void
someplace_in_the_code (void)
{
my_context_data_t *my_data = (my_context_data_t *) jerry_get_context_data (&my_manager);
/* Perform useful things using the data found in my_data */
@@ -435,7 +446,13 @@ jerry_register_magic_strings (const jerry_char_ptr_t *ex_str_items_p,
**Example**
[doctest]: # ()
```c
#include "jerryscript.h"
int
main (void)
{
jerry_init (JERRY_INIT_EMPTY);
@@ -450,9 +467,9 @@ jerry_register_magic_strings (const jerry_char_ptr_t *ex_str_items_p,
// must be static, because 'jerry_register_magic_strings' does not copy
static const jerry_length_t magic_string_lengths[] = {
(jerry_length_t)strlen (magic_string_items[0]),
(jerry_length_t)strlen (magic_string_items[1]),
(jerry_length_t)strlen (magic_string_items[2])
12,
12,
12
};
jerry_register_magic_strings (magic_string_items, num_magic_string_items, magic_string_lengths);
}
@@ -484,7 +501,13 @@ jerry_get_memory_limits (size_t *out_data_bss_brk_limit_p,
**Example**
[doctest]: # ()
```c
#include "jerryscript.h"
int
main (void)
{
jerry_init (JERRY_INIT_EMPTY);
@@ -552,9 +575,16 @@ jerry_run_simple (const jerry_char_t *script_source_p,
**Example**
[doctest]: # ()
```c
#include <string.h>
#include "jerryscript.h"
int
main (void)
{
const jerry_char_t *script = "print ('Hello, World!');";
const jerry_char_t *script = (const jerry_char_t *) "print ('Hello, World!');";
jerry_run_simple (script, strlen ((const char *) script), JERRY_INIT_EMPTY);
}
@@ -596,7 +626,14 @@ jerry_parse (const jerry_char_t *source_p,
**Example**
[doctest]: # ()
```c
#include <string.h>
#include "jerryscript.h"
int
main (void)
{
jerry_init (JERRY_INIT_EMPTY);
@@ -671,7 +708,14 @@ jerry_run (const jerry_value_t func_val);
**Example**
[doctest]: # ()
```c
#include <string.h>
#include "jerryscript.h"
int
main (void)
{
const jerry_char_t script[] = "print ('Hello, World!');";
size_t script_size = strlen ((const char *) script);
@@ -756,7 +800,14 @@ jerry_run_all_enqueued_jobs (void)
**Example**
[doctest]: # ()
```c
#include <string.h>
#include "jerryscript.h"
int
main (void)
{
jerry_init (JERRY_INIT_EMPTY);
@@ -3829,7 +3880,14 @@ jerry_is_valid_utf8_string (const jerry_char_t *utf8_buf_p, /**< UTF-8 string */
**Example**
[doctest]: # ()
```c
#include <string.h>
#include "jerryscript.h"
int
main (void)
{
const jerry_char_t script[] = "print ('Hello, World!');";
size_t script_size = strlen ((const char *) script);
@@ -3870,7 +3928,14 @@ jerry_is_valid_cesu8_string (const jerry_char_t *cesu8_buf_p, /**< CESU-8 string
**Example**
[doctest]: # ()
```c
#include <string.h>
#include "jerryscript.h"
int
main (void)
{
jerry_init (JERRY_INIT_EMPTY);
@@ -3880,9 +3945,9 @@ jerry_is_valid_cesu8_string (const jerry_char_t *cesu8_buf_p, /**< CESU-8 string
if (jerry_is_valid_cesu8_string (script, (jerry_size_t) script_size))
{
jerry_value_t string_value = jerry_create_string_sz (script,
(jerry_size_t) script_size));
(jerry_size_t) script_size);
... // usage of string_value
// usage of string_value
jerry_release_value (string_value);
}
@@ -3935,12 +4000,19 @@ jerry_parse_and_save_snapshot (const jerry_char_t *source_p,
**Example**
[doctest]: # ()
```c
#include <string.h>
#include "jerryscript.h"
int
main (void)
{
jerry_init (JERRY_INIT_EMPTY);
static uint32_t global_mode_snapshot_buffer[256];
const jerry_char_t *code_to_snapshot_p = "(function () { return 'string from snapshot'; }) ();";
const jerry_char_t *code_to_snapshot_p = (const jerry_char_t *) "(function () { return 'string from snapshot'; }) ();";
size_t global_mode_snapshot_size = jerry_parse_and_save_snapshot (code_to_snapshot_p,
strlen ((const char *) code_to_snapshot_p),
@@ -3990,11 +4062,17 @@ jerry_exec_snapshot (const uint32_t *snapshot_p,
**Example**
[doctest]: # ()
```c
#include <string.h>
#include "jerryscript.h"
int
main (void)
{
jerry_value_t res;
static uint32_t global_mode_snapshot_buffer[256];
const jerry_char_t *code_to_snapshot_p = "(function () { return 'string from snapshot'; }) ();";
const jerry_char_t *code_to_snapshot_p = (const jerry_char_t *) "(function () { return 'string from snapshot'; }) ();";
jerry_init (JERRY_INIT_EMPTY);
size_t global_mode_snapshot_size = jerry_parse_and_save_snapshot (code_to_snapshot_p,
@@ -4007,9 +4085,10 @@ jerry_exec_snapshot (const uint32_t *snapshot_p,
jerry_init (JERRY_INIT_EMPTY);
res = (jerry_exec_snapshot (global_mode_snapshot_buffer,
global_mode_snapshot_size,
false);
jerry_value_t res = jerry_exec_snapshot (global_mode_snapshot_buffer,
global_mode_snapshot_size,
false);
jerry_release_value (res);
jerry_cleanup ();
}
@@ -4054,12 +4133,20 @@ jerry_parse_and_save_literals (const jerry_char_t *source_p,
**Example**
[doctest]: # (test="link")
```c
#include <stdio.h>
#include <string.h>
#include "jerryscript.h"
int
main (void)
{
jerry_init (JERRY_INIT_EMPTY);
static uint32_t save_literal_buffer[256];
const jerry_char_t *code_for_literal_save_p = "var obj = { a:'aa', bb:'Bb' }";
const jerry_char_t *code_for_literal_save_p = (const jerry_char_t *) "var obj = { a:'aa', bb:'Bb' }";
size_t literal_sizes = jerry_parse_and_save_literals (code_for_literal_save_p,
strlen ((const char *) code_for_literal_save_p),
@@ -4124,12 +4211,17 @@ jerry_set_vm_exec_stop_callback (jerry_vm_exec_stop_callback_t stop_cb,
**Example**
[doctest]: # (test="link")
```c
#include <string.h>
#include "jerryscript.h"
static int countdown = 10;
static jerry_value_t
vm_exec_stop_callback (void *user_p)
{
static int countdown = 10;
while (countdown > 0)
{
countdown--;
@@ -4140,6 +4232,8 @@ vm_exec_stop_callback (void *user_p)
return jerry_create_string ((const jerry_char_t *) "Abort script");
}
int
main (void)
{
jerry_init (JERRY_INIT_EMPTY);
docs/03.API-EXAMPLE.md
+28 -11
View File
@@ -4,12 +4,14 @@ This guide is intended to introduce you to JerryScript embedding API through cre
## Step 1. Execute JavaScript from your application
[doctest]: # ()
```c
#include <string.h>
#include "jerryscript.h"
int
main (int argc, char *argv[])
main (void)
{
const jerry_char_t script[] = "var str = 'Hello, World!';";
size_t script_size = strlen ((const char *) script);
@@ -32,13 +34,15 @@ Here we perform the same actions, as `jerry_run_simple`, while splitting into se
- engine cleanup
[doctest]: # ()
```c
#include <string.h>
#include "jerryscript.h"
#include "jerryscript-ext/handler.h"
int
main (int argc, char *argv[])
main (void)
{
const jerry_char_t script[] = "print ('Hello, World!');";
size_t script_size = strlen ((const char *) script);
@@ -76,13 +80,15 @@ Our code is more complex now, but it introduces possibilities to interact with J
## Step 3. Execution in 'eval'-mode
[doctest]: # ()
```c
#include <string.h>
#include "jerryscript.h"
#include "jerryscript-ext/handler.h"
int
main (int argc, char *argv[])
main (void)
{
const jerry_char_t script_1[] = "var s = 'Hello, World!';";
const jerry_char_t script_2[] = "print (s);";
@@ -123,13 +129,16 @@ This way, we execute two independent script parts in one execution environment.
## Step 4. Interaction with JavaScript environment
[doctest]: # ()
```c
#include <string.h>
#include "jerryscript.h"
#include "jerryscript-ext/handler.h"
int
main (int argc, char *argv[]) {
main (void)
{
const jerry_char_t str[] = "Hello, World!";
const jerry_char_t script[] = "print (s);";
@@ -183,6 +192,8 @@ created by API functions has the error flag set.
The following example function will output a JavaScript value:
[doctest]: # (test="compile")
```c
#include <stdio.h>
#include <stdlib.h>
@@ -252,6 +263,8 @@ Shell operation can be described with the following loop:
- print result of eval;
- loop.
[doctest]: # (test="compile")
```c
#include <stdio.h>
#include <stdlib.h>
@@ -259,10 +272,10 @@ Shell operation can be described with the following loop:
#include "jerryscript.h"
#include "jerryscript-ext/handler.h"
static void print_value (const jerry_value_t);
void print_value (const jerry_value_t);
int
main (int argc, char *argv[])
main (void)
{
bool is_done = false;
@@ -275,7 +288,7 @@ main (int argc, char *argv[])
while (!is_done)
{
char cmd[256] = {};
char cmd[256];
char *cmd_tail = cmd;
size_t len = 0;
@@ -316,7 +329,7 @@ main (int argc, char *argv[])
{
/* Evaluated JS code thrown an exception
* and didn't handle it with try-catch-finally */
printf ("Unhandled JS exception occured: ");
printf ("Unhandled JS exception occurred: ");
}
print_value (ret_val);
@@ -336,6 +349,8 @@ The application inputs commands and evaluates them, one after another.
In this example we demonstrate how to use native function and structures in JavaScript.
[doctest]: # ()
```c
#include <string.h>
#include "jerryscript.h"
@@ -359,7 +374,7 @@ get_msg_handler (const jerry_value_t func_value, /**< function object */
} /* get_msg_handler */
int
main (int argc, char *argv[])
main (void)
{
/* Initialize engine */
jerry_init (JERRY_INIT_EMPTY);
@@ -369,7 +384,7 @@ main (int argc, char *argv[])
jerryx_handler_print);
/* Do something with the native object */
my_struct.msg = "Hello World";
my_struct.msg = "Hello, World!";
/* Create an empty JS object */
jerry_value_t object = jerry_create_object ();
@@ -427,6 +442,8 @@ Hello World
Here we create a JS Object with `jerry_eval`, then extend it with a native function. This function shows how to get a property value from the object and how to manipulate it.
[doctest]: # ()
```c
#include <string.h>
#include "jerryscript.h"
@@ -466,7 +483,7 @@ add_handler (const jerry_value_t func_value, /**< function object */
} /* add_handler */
int
main (int argc, char *argv[])
main (void)
{
/* Initialize engine */
jerry_init (JERRY_INIT_EMPTY);
docs/09.EXT-REFERENCE-ARG.md
+26 -11
View File
@@ -187,12 +187,18 @@ jerryx_arg_transform_this_and_args (const jerry_value_t this_val,
**Example**
[doctest]: # (test="compile")
```c
#include "jerryscript.h"
#include "jerryscript-ext/arg.h"
/* JS signature: function (requiredBool, requiredString, optionalNumber) */
static jerry_value_t my_external_handler (const jerry_value_t function_obj,
const jerry_value_t this_val,
const jerry_value_t args_p[],
const jerry_length_t args_count)
static jerry_value_t
my_external_handler (const jerry_value_t function_obj,
const jerry_value_t this_val,
const jerry_value_t args_p[],
const jerry_length_t args_count)
{
bool required_bool;
char required_str[16];
@@ -205,7 +211,7 @@ static jerry_value_t my_external_handler (const jerry_value_t function_obj,
jerryx_arg_ignore (),
jerryx_arg_boolean (&required_bool, JERRYX_ARG_NO_COERCE, JERRYX_ARG_REQUIRED),
jerryx_arg_string (&required_str, sizeof (required_str), JERRYX_ARG_NO_COERCE, JERRYX_ARG_REQUIRED),
jerryx_arg_string (required_str, sizeof (required_str), JERRYX_ARG_NO_COERCE, JERRYX_ARG_REQUIRED),
jerryx_arg_number (&optional_num, JERRYX_ARG_NO_COERCE, JERRYX_ARG_OPTIONAL),
};
@@ -226,7 +232,8 @@ static jerry_value_t my_external_handler (const jerry_value_t function_obj,
* Validated and transformed successfully!
* required_bool, required_str and optional_num can now be used.
*/
...
return jerry_create_undefined (); /* Or return something more meaningful. */
}
```
@@ -498,17 +505,23 @@ jerryx_arg_object_properties (const jerryx_arg_object_props_t *object_props_p,
**Example**
[doctest]: # (test="compile")
```c
#include "jerryscript.h"
#include "jerryscript-ext/arg.h"
/**
* The binding function expects args_p[0] is an object, which has 3 properties:
* "enable": boolean
* "data": number
* "extra_data": number, optional
*/
static jerry_value_t my_external_handler (const jerry_value_t function_obj,
const jerry_value_t this_val,
const jerry_value_t args_p[],
const jerry_length_t args_count)
static jerry_value_t
my_external_handler (const jerry_value_t function_obj,
const jerry_value_t this_val,
const jerry_value_t args_p[],
const jerry_length_t args_count)
{
bool required_bool;
double required_num;
@@ -519,6 +532,7 @@ static jerry_value_t my_external_handler (const jerry_value_t function_obj,
/* "prop_mapping" defines the steps to transform properties to C variables. */
const jerryx_arg_t prop_mapping[] =
{
jerryx_arg_boolean (&required_bool, JERRYX_ARG_COERCE, JERRYX_ARG_REQUIRED),
jerryx_arg_number (&required_num, JERRYX_ARG_COERCE, JERRYX_ARG_REQUIRED),
jerryx_arg_number (&optional_num, JERRYX_ARG_COERCE, JERRYX_ARG_OPTIONAL)
@@ -555,7 +569,8 @@ static jerry_value_t my_external_handler (const jerry_value_t function_obj,
* Validated and transformed successfully!
* required_bool, required_num and optional_num can now be used.
*/
...
return jerry_create_undefined (); /* Or return something more meaningful. */
}
```
docs/10.EXT-REFERENCE-HANDLER.md
+5 -2
View File
@@ -114,6 +114,8 @@ jerryx_handler_register_global (const jerry_char_t *name_p,
**Example**
[doctest]: # (test="compile")
```c
#include "jerryscript.h"
#include "jerryscript-ext/handler.h"
@@ -129,7 +131,8 @@ static const struct {
{ NULL, NULL }
};
static void register_common_functions ()
static void
register_common_functions (void)
{
jerry_value_t ret = jerry_create_undefined ();
@@ -139,7 +142,7 @@ static void register_common_functions ()
common_functions[i].handler_p);
}
return ret;
jerry_release_value (ret);
}
```
docs/11.EXT-REFERENCE-AUTORELEASE.md
+6 -3
View File
@@ -12,19 +12,22 @@ using the `__cleanup__` variable attribute. For other compilers, no support has
**Example**
[doctest]: # (test="compile")
```c
#include "jerryscript.h"
#include "jerryscript-ext/autorelease.h"
static void foo (bool enable)
static void
foo (bool enable)
{
JERRYX_AR_VALUE_T bar = jerry_create_string (...);
JERRYX_AR_VALUE_T bar = jerry_create_string ((const jerry_char_t *) "...");
if (enable)
{
JERRYX_AR_VALUE_T baz = jerry_get_global_object ();
...
/* bar and baz can now be used. */
/*
* jerry_release_value (baz) and jerry_release_value (bar) is called automatically before