Data Manipulation
Classes
json_array
Methods
add
Add a value to the end of a JSON array.
void json_array::add(var@ value);
Arguments:
- var@ value: a handle to the value to be set.
Example:
void main() {
json_array@ arr = parse_json("[]");
for (uint i = 0; i < 5; i++)
arr.add(random(1, 100));
alert("Filled array", arr.stringify());
}
clear
Clears the JSON array completely.
void json_array::clear();
Example:
void main() {
string data = "[1, 2, 3, 4, 5]";
json_array@ arr = parse_json(data);
alert("Before being cleared", arr.stringify());
arr.clear();
alert("After being cleared", arr.stringify());
}
is_array
Determine if the value at the given index is a JSON array or not.
bool json_array::is_array(uint index);
Arguments:
- uint index: the position of the item.
Returns:
bool: true if the value at the specified index is a JSON array, false otherwise.
Example:
void main() {
json_array@ arr = parse_json("[[1, 2], [3, 4]]");
alert("Info", arr.is_array(1) ? "It is an array": "It is not an array");
}
is_null
Determine if the value at the given index is null.
bool json_array::is_null(uint index);
Arguments:
- uint index: the position of the item.
Returns:
bool: true if the value at the specified index is null, false otherwise.
Example:
void main() {
json_array@ arr = parse_json("[1, 2, null, 4]");
alert("Info", "Index 1 " + (arr.is_null(1) ? " is null": " is not null"));
alert("Info", "Index 2 " + (arr.is_null(2) ? " is null": " is not null"));
}
is_object
Determine if the value at the given index is a JSON object.
bool json_array::is_object(uint index);
Arguments:
- uint index: the position of the item.
Returns:
bool: true if the value at the specified index is a JSON object, false otherwise.
Example:
void main() {
json_array@ arr = parse_json("""[{}, {}, "test", {}]""");
alert("Info", "Position 0 " + (arr.is_object(0) ? "is an object" : "is not an object"));
alert("Info", "Position 2 " + (arr.is_object(2) ? "is an object": "is not an object"));
}
remove
Remove a value from the JSON array given an index.
void json_array::remove(uint index);
Arguments:
- uint index: the index of the value to remove.
Example:
void main() {
string data = """[47, 4, 584, 43, 8483]""";
json_array@ arr = parse_json(data);
alert("Initial", arr.stringify());
arr.remove(2);
alert("After removal", arr.stringify());
}
size
Return the size of the JSON array.
uint json_array::size();
Example:
void main() {
string data = "[";
for (int i = 0; i < random(10, 20); i++)
data += i + ", ";
// Strip off the trailing comma and space character, as they'll make the JSON throw a syntax error.
data.erase(data.length() - 1);
data.erase(data.length() - 1);
data += "]";
clipboard_set_text(data);
json_array@ arr = parse_json(data);
alert("Info", "The JSON array contains " + arr.size() + " items");
}
stringify
Return the JSON array as a string.
string json_array::stringify(int indent = 0, int step = -1);
Arguments:
int indent = 0: specifies how many spaces to use to indent the JSON. If 0, no indentation or formatting is performed.
int step = -1: the outwards indentation step, for example setting it to two would cause your outdents to only be two spaces. -1 (the default) keeps it how it is, normally you don't need to use this parameter.
Returns:
string: the JSON array as a string.
Example:
void main() {
string data = """["Apple", "Banana", "Orange", "Lemon"]""";
json_array@ arr = parse_json(data);
alert("JSON array", arr.stringify(4));
}
Operators
get_opIndex
Get a value out of the JSON array with literal syntax, for example arr[2]
.
var@ json_array::get_opIndex(uint index) property;
Arguments:
- uint index: the index of the value to get.
Returns:
var@: a handle to the object, or null if not found.
Example:
void main() {
json_array@ cats = parse_json("""["Athena", "Willow", "Punk", "Franky", "Yoda", "Waffles"]""");
alert("The third cat is", cats[2]);
for (uint i = 0; i < cats.size(); i++)
alert("Awww", "Hi " + cats[i]);
}
opCall
Get a value out of a JSON array using a query.
var@ json_array::opCall(string query);
Arguments:
- string query: the JSON query (see the remarks section for details).
Returns:
var@: a handle to the object, or null if it couldn't be found.
Remarks:
Queries are formatted like so, using key names and indexes separated with ".":
world.player.0
It can be as nested as you like.
Example:
void main() {
string data = """[[["Colorado", "Kansas", "Minnesota"]]]""";
json_array@ arr = parse_json(data);
string location = arr("0.0.0");
alert("My favorite state is", location);
}
set_opIndex
Set a value in the JSON array at a particular position.
void json_array::set_opIndex(uint index, var@ value) property;
Arguments:
uint index: the index to insert the item at.
var@ value: the value to set.
Example:
void main() {
json_array@ arr = parse_json("[]");
arr[0] = "meow";
alert("Info", "Cats say " + arr[0]);
}
Properties
empty
Determine if the JSON array is empty.
const bool json_array::empty;
Example:
void main() {
json_array@ arr = parse_json("[]");
json_array@ arr2 = parse_json("[1, 2, 3]");
alert("First is empty", arr.empty ? "true" : "false");
alert("Second is empty", arr2.empty ? "true" : "false");
}
escape_unicode
Determines the amount of escaping that occurs in JSON parsing.
bool json_array::escape_unicode;
Remarks:
If this property is true, escaping will behave like normal. If it's false, only the characters absolutely vital to JSON parsing are escaped.
json_object
Methods
clear
Clears the JSON object completely.
void json_object::clear();
Example:
void main() {
string data = """{"numbers": [1, 2, 3, 4, 5]}""";
json_object@ o = parse_json(data);
alert("Before being cleared", o.stringify());
o.clear();
alert("After being cleared", o.stringify());
}
exists
Determine if a key exists in the JSON object.
bool json_object::exists(string key);
Arguments:
- string: the key to search for.
Returns:
bool: true if the key exists, false if not.
Example:
void main() {
string data = """{"engine": "NVGT"}""";
json_object@ o = parse_json(data);
alert("Info", (o.exists("engine") ? "The key exists" : "The key does not exist"));
}
get_keys
Get a list of all the keys in the JSON object.
string[]@ json_object::get_keys();
Returns:
string[]@: a handle to an array of strings containing all the keys of the JSON object.
Remarks:
Note that this function isn't recursive, you only get the keys for the object you're running this function on, not any child objects.
Example:
void main() {
string data = """{"thing": 1, "other_thing": "test", "another": true}""";
json_object@ o = parse_json(data);
string[]@ keys = o.get_keys();
alert("The keys are", join(keys, ", "));
}
is_array
Determine if the value with the given key is a JSON array or not.
bool json_object::is_array(string key);
Arguments:
- string key: the key to query.
Returns:
bool: true if the value with the specified key is a JSON array, false otherwise.
Example:
void main() {
string data = """{"classes": ["json_object", "json_array"]}""";
json_object@ o = parse_json(data);
alert("Info", o.is_array("classes") ? "array": "nonarray");
}
is_null
Determine if the value with the given key is null.
bool json_object::is_null(string key);
Arguments:
- string key: the key to query.
Returns:
bool: true if the value with the specified key is null.
Example:
void main() {
string data = """{"brain": null}""";
json_object@ o = parse_json(data);
alert("Info", o.is_null("brain") ? "null" : "not null");
}
is_object
Determine if the value with the given key is a JSON object or not.
bool json_object::is_object(string key);
Arguments:
- string key: the key to query.
Returns:
bool: true if the value with the specified key is a JSON object, false otherwise.
Example:
void main() {
string data = """{"json_object": {\}\}""";
json_object@ o = parse_json(data);
alert("Info", o.is_object("json_object") ? "Object" : "Non-object");
}
remove
Remove a value from the JSON object given a key.
void json_object::remove(string key);
Arguments:
- string key: the key of the value to remove.
Example:
void main() {
string data = """{"name": "Quin"}""";
json_object@ o = parse_json(data);
alert("Initial", o.stringify());
o.remove("name");
alert("After removal", o.stringify());
}
set
Set a value in a JSON object.
void json_object::set(string key, var@ value);
Arguments:
string key: the key to give the value.
var@ value: a handle to the value to be set.
Example:
void main() {
json_object@ o = parse_json("{}");;
o.set("nvgt_user", true);
alert("Info", (bool(o["nvgt_user"]) ? "You are an NVGT user" : "You are not a regular NVGT user"));
}
size
Return the size of the JSON object.
uint json_object::size();
Remarks:
Note that this function returns the number of top-level keys; it's not recursive.
Example:
void main() {
string data = """{"numbers": [1, 2, 3, 4, 5]}""";
json_object@ o = parse_json(data);
alert("Info", "The json object's size is " + o.size());
}
stringify
Return the JSON object as a string.
string json_object::stringify(int indent = 0, int step = -1);
Arguments:
int indent = 0: specifies how many spaces to use to indent the JSON. If 0, no indentation or formatting is performed.
int step = -1: the outwards indentation step, for example setting it to two would cause your outdents to only be two spaces. -1 (the default) keeps it how it is, normally you don't need to use this parameter.
Returns:
string: the JSON object as a string.
Example:
void main() {
string data = """{"name": "Quin", "age": 18}""";
json_object@ o = parse_json(data);
alert("JSON object", o.stringify(4));
}
Operators
get_opIndex
Get a value out of the JSON object with literal syntax, for example json["key"]
.
var@ json_object::get_opIndex(string key) property;
Arguments:
- string key: the key of the object to get.
Returns:
var@: a handle to the object, or null if not found.
Example:
void main() {
string data = """{"name": "Quin", "age": 18}""";
json_object@ o = parse_json(data);
alert("Info", o["name"] + " is " + o["age"]);
}
opCall
Get a value out of a JSON object using a query.
var@ json_object::opCall(string query);
Arguments:
- string query: the JSON query (see the remarks section for details).
Returns:
var@: a handle to the object, null if not found.
Remarks:
Queries are formatted like so:
first_field.subfield.subfield
It can be as nested as you like.
This method also works on json_array's, and you access array indexes just with their raw numbers, like so:
world.players.0
Example:
void main() {
string data = """{"countries":{"us":["Colorado", "Kansas", "Minnesota"]\}\}""";
json_object@ o = parse_json(data);
string locations = o("countries.us");
alert("My favorite states are", locations);
}
set_opIndex
Set a value in the JSON object with a particular key.
void json_object::set_opIndex(string key, var@ value) property;
Arguments:
string key: the key of the object.
var@ value: the value to set.
Example:
void main() {
json_object@ o = parse_json("{}");
o["name"] = "Quin";
alert("Hi", "I am " + o["name"]);
}
Properties
escape_unicode
Determines the amount of escaping that occurs in JSON parsing.
bool json_object::escape_unicode;
Remarks:
If this property is true, escaping will behave like normal. If it's false, only the characters absolutely vital to JSON parsing are escaped.
pack
methods
add_file
Add a file on disk to a pack.
bool pack::add_file(string disk_filename, string pack_filename, bool allow_replace = false);
Arguments:
- string disk_filename: the filename of the file to add to the pack.
- string pack_filename: the name the file should have in your pack.
- bool allow_replace = false: if a file already exists in the pack with that name, should it be overwritten?
Returns:
bool: true if the file was successfully added, false otherwise.
close
Closes a pack, freeing all its resources.
bool pack::close();
Returns:
bool: true if the pack was successfully closed, false otherwise.
open
Open a pack to perform operations on it.
bool pack::open(string filename, uint mode, bool memload = false);
Arguments:
- string filename: the name of the pack file to open.
- uint mode: the mode to open the pack in (see
pack_open_modes
for more information). - bool memload = false: whether or not the pack should be loaded from memory as opposed to on disk.
Returns:
bool: true if the pack was successfully opened with the given mode, false otherwise.
set_pack_identifier
Set the identifier of this pack object (e.g. the first 8-bytes that determine if you have a valid pack or not).
bool pack::set_pack_identifier(string ident);
Arguments:
- string ident: the new identifier (see remarks).
Returns:
bool: true if the pack's identifier was properly set, false otherwise.
Remarks:
- The default pack identifier is "NVPK" followed by 4 NULL bytes.
- Your pack identifier should be 8 characters or less. If it's less than 8 characters, 0s will be added as padding on the end. If it's larger than 8, the first 8 characters will be used.
regexp
The regexp object allows for the easy usage of regular expressions in NVGT.
regexp(string pattern, int options = RE_UTF8);
Arguments:
string pattern: the regular expression's pattern (see remarks).
int options = RE_UTF8: a combination of any of the values from the
regexp_options
enum.
Remarks:
Regular expressions are a language used for matching, substituting, and otherwise manipulating text. To learn about the regular expression syntax that nVGT uses (called PCRE), see this link: https://en.wikipedia.org/wiki/Perl_Compatible_Regular_Expressions
Example:
void main() {
regexp re("^[a-z]{2,4}$"); // Will match any lowercase alphabetical string between 2 and 4 characters in length.
string compare = input_box("Text", "Enter the text to check against the regular expression.");
if (compare.empty()) {
alert("Regular expression tester", "You didn't type a string to test.");
exit(1);
}
bool matches = re.match(compare);
alert("The regular expression", matches ? "matches" : "does not match");
}
methods
match
Determine if the regular expression matches against a particular string or not.
bool regexp::match(string subject, uint64 offset = 0);
bool regexp::match(string subject, uint64 offset, int options);
Arguments (1):
- string subject: the string to compare against.
- uint64 offset = 0: the offset to start the comparison at.
Arguments (2):
- string subject: the string to compare against.
- uint64 offset: the offset to start the comparison at.
- int options: any combination of the values found in the
regexp_options
enum.
Returns:
bool: true if the regular expression matches the given string, false if not.
Enums
pack_open_modes
This is a list of all the possible open modes to be passed to the pack::open()
function.
- PACK_OPEN_MODE_NONE.
- PACK_OPEN_MODE_APPEND: open the pack and append data to it.
- PACK_OPEN_MODE_CREATE: create a new pack.
- PACK_OPEN_MODE_READ: open the pack for reading.
regexp_options
This enum holds various constants that can be passed to the regular expression classes in order to change their behavior.
Notes:
Portions of this regexp_options documentation were Copied from POCO header files.
- Options marked [ctor] can be passed to the constructor of regexp objects.
- Options marked [match] can be passed to match, extract, split and subst.
- Options marked [subst] can be passed to subst.
See the PCRE documentation for more information.
Constants:
- RE_CASELESS: case insensitive matching (/i) [ctor]
- RE_MULTILINE: enable multi-line mode; affects ^ and $ (/m) [ctor]
- RE_DOTALL: dot matches all characters, including newline (/s) [ctor]
- RE_EXTENDED: totally ignore whitespace (/x) [ctor]
- RE_ANCHORED: treat pattern as if it starts with a ^ [ctor, match]
- RE_DOLLAR_END_ONLY: dollar matches end-of-string only, not last newline in string [ctor]
- RE_EXTRA: enable optional PCRE functionality [ctor]
- RE_NOT_BOL: circumflex does not match beginning of string [match]
- RE_NOT_EOL: $ does not match end of string [match]
- RE_UNGREEDY: make quantifiers ungreedy [ctor]
- RE_NOT_EMPTY: empty string never matches [match]
- RE_UTF8: assume pattern and subject is UTF-8 encoded [ctor]
- RE_NO_AUTO_CAPTURE: disable numbered capturing parentheses [ctor, match]
- RE_NO_UTF8_CHECK: do not check validity of UTF-8 code sequences [match]
- RE_FIRSTLINE: an unanchored pattern is required to match before or at the first newline in the subject string, though the matched text may continue over the newline [ctor]
- RE_DUPNAMES: names used to identify capturing subpatterns need not be unique [ctor]
- RE_NEWLINE_CR: assume newline is CR ('\r'), the default [ctor]
- RE_NEWLINE_LF: assume newline is LF ('\n') [ctor]
- RE_NEWLINE_CRLF: assume newline is CRLF ("\r\n") [ctor]
- RE_NEWLINE_ANY: assume newline is any valid Unicode newline character [ctor]
- RE_NEWLINE_ANY_CRLF: assume newline is any of CR, LF, CRLF [ctor]
- RE_GLOBAL: replace all occurrences (/g) [subst]
- RE_NO_VARS: treat dollar in replacement string as ordinary character [subst]
Functions
ascii_to_character
Return the character that corresponds to the given ascii value.
string ascii_to_character(uint8 ascii);
Arguments:
- uint8 ascii: the ascii value to convert.
Returns:
string: the character for the given ascii value.
Example:
void main() {
uint8 ascii = parse_int(input_box("ASCII value", "Enter the ascii value to convert."));
alert("Info", ascii + " has a value of " + ascii_to_character(ascii));
}
character_to_ascii
Return the ascii value for the given character.
uint8 character_to_ascii(string character);
Arguments:
- string character: the character to convert.
Returns:
uint8: the ascii value for the given character.
Example:
void main() {
string character = input_box("Character", "Enter a character to convert");
if (character.is_empty()) {
alert("Error", "You did not type anything.");
exit();
}
if (character.length() != 1) { // The user typed more than one character.
alert("Error", "You must only type a single character.");
exit();
}
alert("Info", character + " has an ascii value of " + character_to_ascii(character));
}
join
turn an array into a string, with each element being separated by the given delimiter.
string join(string[] elements, string delimiter);
Arguments:
string[] elements: the array to join.
string delimiter: the delimiter used to separate each element in the array (can be empty).
Returns:
string: the given array as a string.
Remarks:
If an empty array is passed, a blank string is returned.
The delimiter is not appended to the end of the last item in the returned string. For example if an array contains [1, 2, 3] and you join it with a delimiter of . (period), the result would be "1.2.3" without an extra delimiter appended.
Example:
void main() {
string[] names = {"Sam", "Quin", "Patrick"};
string people = join(names, ", ");
alert("Info", people);
}
number_to_words
Convert a number into its string equivalent, for example, one thousand four hundred and fifty six.
string number_to_words(int64 the_number, bool include_and = true);
Arguments:
int64 the_number: the number to convert.
bool include_and = true: whether or not to include the word "and" in the output.
Returns:
string: the specified number, converted to a readable string.
Remarks:
At this time, this function only produces English results.
Example:
void main() {
int64 num = random(1000, 100000);
string result = number_to_words(num);
alert("Info", num + " as a string is " + result);
}
pack_set_global_identifier
Set the global identifier of all your packs (e.g. the first 8-bytes that determine if you have a valid pack or not).
bool pack_set_global_identifier(string ident);
Arguments:
- string ident: the new identifier (see remarks).
Returns:
bool: true if the identifier was properly set, false otherwise.
Remarks:
- The default pack identifier is "NVPK" followed by 4 NULL bytes.
- Your pack identifier should be 8 characters or less. If it's less than 8 characters, 0s will be added as padding on the end. If it's larger than 8, the first 8 characters will be used.
regexp_match
Test if the text matches the specified regular expression.
bool regexp_match(string text, string pattern);
Arguments:
string text: the text to compare against the regular expression.
string pattern: the regular expression to match.
Returns:
bool: true if the text matches the given regular expression, false otherwise.
Remarks:
To learn more about regular expressions, visit: https://en.wikipedia.org/wiki/Regular_expression
Example:
void main() {
bool match = regexp_match("Test", "^[a-zA-Z]+$");
alert("the regular expression", match ? "matches" : "does not match");
}
string_base32_decode
Decodes a string from base32.
string string_base32_decode(string the_data);
Arguments:
- string the_data: The data that is to be decoded.
Returns:
String: The decoded string on success or an empty string on failure.
Remarks:
You can learn more about the base32 format here.
Example:
void main() {
string text = input_box("Text", "Enter the text to decode.");
if (text.is_empty()) {
alert("Error", "You did not type any text.");
exit();
}
alert("Info", string_base32_decode(text));
}
string_base32_encode
Encodes a string as base32.
string string_base32_encode(string the_data);
Arguments:
- string the_data: The data that is to be encoded.
Returns:
String: The encoded string on success or an empty string on failure.
Remarks:
You can learn more about the base32 format here.
Example:
void main() {
string text = input_box("Text", "Enter the text to encode.");
if (text.is_empty()) {
alert("Error", "You did not type any text.");
exit();
}
alert("Info", string_base32_encode(text));
}
string_base32_normalize
Normalize a string to conform to the base32 spec.
string string_base32_normalize(string the_data);
Arguments:
- string the_data: the string to normalize.
Returns:
string: the normalized string.
Remarks:
The primary thing this function does is to skip separators, convert all letters to uppercase, and make sure the length is a multiple of 8.
To learn more about base32, click here.
Example:
void main() {
string text = input_box("Text", "Enter the text to normalize.");
if (text.is_empty()) {
alert("Error", "You didn't type anything.");
exit();
}
alert("Info", string_base32_normalize(text));
}
string_base64_decode
Decodes a string which has previously been encoded in base64.
string string_base64_decode(string the_data, string_base64_options options = STRING_BASE64_PADLESS);
Arguments:
string the_data: The data that is to be decoded.
string_base64_options options = STRING_BASE64_PADLESS: A bitwise of options that control the behavior of the decoding (see remarks).
Returns:
String: The decoded string on success or an empty string on failure.
Remarks:
The following options may be passed to the options argument of this function:
STRING_BASE64_DEFAULT: The defaults passed to the string_base64_encode function.
STRING_BASE64_URL: Use base64 URL encoding as opposed to the / and = characters.
STRING_BASE64_PADLESS: Allows decoding even if the string does not end with = padding characters.
You can learn more about base64 here.
Example:
void main() {
alert("example", string_base64_decode("aGVsbG8=")); // Should print "hello".
}
string_base64_encode
Encodes a string as base64.
string string_base64_encode(string the_data, string_base64_options options = STRING_BASE64_DEFAULT);
Arguments:
string the_data: The data that is to be encoded.
string_base64_options options = STRING_BASE64_DEFAULT: A bitwise of options that control the behavior of the encoding (see remarks).
Returns:
String: The encoded string on success or an empty string on failure.
Remarks:
The following options may be passed to the options argument of this function:
STRING_BASE64_DEFAULT: The default options (i.e. insert padding and do not use URL encoding).
STRING_BASE64_URL: Use base64 URL encoding as opposed to the / and = characters.
STRING_BASE64_PADLESS: Allows decoding even if the string does not end with = padding characters.
You can learn more about base64 here.
Example:
void main() {
alert("example", string_base64_encode("Hello")); // Should print SGVsbG8=
}