NimaBastani/pawn-json-parser

JSON Parser for SA-MP/open.mp (Pawn)

A comprehensive, pure-Pawn JSON parser, builder, serializer, and query engine for SA-MP/open.mp servers. No plugins required.

About This Project

This library has been a quiet side project of mine for roughly 2 years. I started it because I needed a reliable JSON solution for my SA-MP server and nothing out there felt right - either too limited, or required external plugins I didn't want to depend on.

So I built my own, piece by piece, version by version. It was never meant to be public. Just a personal tool I kept improving whenever I hit a new edge case or needed a feature that wasn't there yet (or if I had an exam the day after).

But at some point I looked at it and thought... why not share it? Maybe someone else is in the same spot I was. So here it is, nothing fancy, just a solid pure-Pawn JSON parser that does what it's supposed to do.

---

Table of Contents

• Installation
• Configuration
• Quick Start
• Function Quick Refrence
• Core Concepts
  • Documents
  • Nodes
  • Data Types
• API Reference
  • Initialization
  • Document Management
  • Parsing
  • Node Information
  • Value Getters
  • Navigation
  • Object Lookup
  • Array Access
  • Path Queries (Dot Notation)
  • Path Setters
  • Node Creation
  • Object Building
  • Array Building
  • Quick Build Helpers
  • Serialization
  • Deep Copy / Clone
  • Merge
  • Comparison
  • Search
  • Iteration
  • Object Keys Extraction
  • Path Manipulation
  • Validation
  • Statistics and Debug
  • Type Conversion
  • Cleanup
• Error Handling
• Macros
• Constants
• Complete Examples
  • Example 1: Parse and Read
  • Example 2: Build from Scratch
  • Example 3: File I/O
  • Example 4: Modify Existing JSON
  • Example 5: Deep Nesting and Path Queries
  • Example 6: Array Manipulation
  • Example 7: Merge Two Objects
  • Example 8: Clone and Compare
  • Example 9: Search Functions
  • Example 10: Iteration
  • Example 11: Player Save/Load System
  • Example 12: Server Configuration Loader
  • Example 13: Validation and Error Handling
• Performance Tips
• Limitations
• Changelog

---

Installation

1. Copy json_parser.inc into your pawno/include/ directory.
2. Include it in your script:

#include <json_parser>

No plugins, no external dependencies. Pure Pawn.

---

Configuration

All limits can be overridden before including the file using #define:

Example override:

#define JSON_MAX_NODES 4096
#define JSON_MAX_STRING_LEN 8192
#include <json_parser>

---

Quick Start

Parsing JSON

new docId;
new jsonStr[] = "{\"name\":\"John\",\"age\":25,\"vip\":true}";

if (JSON_Parse(jsonStr, docId))
{
    new root = JSON_GetRootNode(docId);

    new name[32];
    JSON_GetStringByPath(root, "name", name);
    // name = "John"

    new age;
    JSON_GetIntByPath(root, "age", age);
    // age = 25

    new bool:vip;
    JSON_GetBoolByPath(root, "vip", vip);
    // vip = true

    JSON_DestroyDocument(docId);
}

Building JSON

new docId, root;
root = JSON_BuildObject(docId);

JSON_ObjectSetString(root, "server", "My SA-MP Server");
JSON_ObjectSetInt(root, "maxPlayers", 100);
JSON_ObjectSetBool(root, "active", true);

new output[512];
JSON_Prettify(root, output);
print(output);

JSON_DestroyDocument(docId);

Output:

{
  "server": "My SA-MP Server",
  "maxPlayers": 100,
  "active": true
}

Function Quick Reference

---

Core Concepts

Documents

A document is a container that owns a set of nodes. Every parsing or building operation starts with a document. Documents are identified by an integer ID.

• Maximum simultaneous documents: JSON_MAX_DOCUMENTS (default 16)
• Always destroy documents when done to free nodes

Nodes

Every JSON value (string, number, object, array, bool, null) is stored as a node. Nodes form a tree structure with parent-child and sibling relationships.

Each node has:

• A type (object, array, string, int, float, bool, null)
• A key (if it's a child of an object)
• A value (for primitive types)
• Links to parent, first child, last child, previous sibling, next sibling

Data Types

---

API Reference

Initialization

JSON_Init()

Initializes the parser state. Called automatically by most functions. Safe to call multiple times.

JSON_Init();

Returns: 1 always.

---

Document Management

JSON_CreateDocument()

Creates a new empty document.

new docId = JSON_CreateDocument();
if (docId == JSON_INVALID_DOCUMENT)
{
    print("ERROR: No free document slots!");
}

Returns: Document ID on success, JSON_INVALID_DOCUMENT (-1) on failure.

---

JSON_DestroyDocument(docId)

Destroys a document and frees all its nodes.

JSON_DestroyDocument(docId);

Returns: 1 on success, 0 on failure.

Always call this when you're done with a document to prevent node leaks.

---

JSON_GetRootNode(docId)

Gets the root node of a document.

new root = JSON_GetRootNode(docId);
if (root == JSON_INVALID_NODE)
{
    print("Document has no root node");
}

Returns: Node ID or JSON_INVALID_NODE (-1).

---

Parsing

JSON_Parse(const jsonString[], &docId)

Parses a JSON string into a new document.

new docId;
new input[] = "{\"key\":\"value\",\"num\":42}";

if (JSON_Parse(input, docId))
{
    new root = JSON_GetRootNode(docId);
    // ... use the data ...
    JSON_DestroyDocument(docId);
}
else
{
    new errMsg[128];
    JSON_GetErrorMessage(errMsg);
    printf("Parse error: %s", errMsg);
}

Returns: 1 on success, 0 on failure.

Supported JSON features:

• Objects, arrays, strings, integers, floats, booleans, null
• Nested structures to JSON_MAX_DEPTH levels
• Escape sequences in strings: \", \\, \/, \b, \f, \n, \r, \t
• Negative numbers and decimal floats

---

JSON_ParseFile(const filename[], &docId)

Reads a file and parses its contents as JSON.

new docId;
if (JSON_ParseFile("scriptfiles/config.json", docId))
{
    new root = JSON_GetRootNode(docId);
    // ...
    JSON_DestroyDocument(docId);
}

Returns: 1 on success, 0 on failure.

---

Node Information

JSON_GetNodeType(nodeId)

Returns the type constant of a node.

new type = JSON_GetNodeType(nodeId);
if (type == JSON_TYPE_STRING)
{
    // handle string
}

Returns: One of JSON_TYPE_* constants, or -1 if invalid.

---

JSON_GetNodeTypeName(nodeId, dest[], maxlen = sizeof(dest))

Gets a human-readable type name.

new typeName[16];
JSON_GetNodeTypeName(nodeId, typeName);
printf("Type: %s", typeName);
// Output: "string", "int", "float", "bool", "null", "object", "array", or "unknown"

Returns: 1 on success, 0 on failure.

---

JSON_GetNodeKey(nodeId, dest[], maxlen = sizeof(dest))

Gets the key of a node (only meaningful for children of objects).

new key[64];
JSON_GetNodeKey(childNode, key);
printf("Key: %s", key);

Returns: 1 on success, 0 on failure.

---

JSON_GetChildCount(nodeId)

Returns the number of direct children of a node.

new count = JSON_GetChildCount(objectNode);
printf("Object has %d properties", count);

Returns: Child count, or 0 if invalid/no children.

---

Type Check Functions

All return bool:

JSON_IsNull(nodeId)      // true if JSON_TYPE_NULL
JSON_IsString(nodeId)    // true if JSON_TYPE_STRING
JSON_IsInt(nodeId)       // true if JSON_TYPE_INT
JSON_IsFloat(nodeId)     // true if JSON_TYPE_FLOAT
JSON_IsBool(nodeId)      // true if JSON_TYPE_BOOL
JSON_IsObject(nodeId)    // true if JSON_TYPE_OBJECT
JSON_IsArray(nodeId)     // true if JSON_TYPE_ARRAY
JSON_IsNumber(nodeId)    // true if JSON_TYPE_INT or JSON_TYPE_FLOAT

Example:

if (JSON_IsString(node))
{
    new val[128];
    JSON_GetString(node, val);
    printf("String value: %s", val);
}
else if (JSON_IsInt(node))
{
    new val;
    JSON_GetInt(node, val);
    printf("Int value: %d", val);
}

---

Value Getters

JSON_GetString(nodeId, dest[], maxlen = sizeof(dest))

Gets the string value of a node.

new value[128];
if (JSON_GetString(node, value))
{
    printf("Value: %s", value);
}

Returns: 1 on success, 0 on failure. Works on JSON_TYPE_STRING nodes.

---

JSON_GetInt(nodeId, &value)

Gets the integer value of a node.

new value;
if (JSON_GetInt(node, value))
{
    printf("Value: %d", value);
}

Returns: 1 on success, 0 on failure. Works on JSON_TYPE_INT nodes.

---

JSON_GetFloat(nodeId, &Float:value)

Gets the float value of a node.

new Float:value;
if (JSON_GetFloat(node, value))
{
    printf("Value: %f", value);
}

Returns: 1 on success, 0 on failure. Works on JSON_TYPE_FLOAT nodes.

---

JSON_GetBool(nodeId, &bool:value)

Gets the boolean value of a node.

new bool:value;
if (JSON_GetBool(node, value))
{
    printf("Value: %s", value ? "true" : "false");
}

Returns: 1 on success, 0 on failure. Works on JSON_TYPE_BOOL nodes.

---

Navigation

These functions let you traverse the node tree manually.

JSON_GetParent(nodeId)

new parent = JSON_GetParent(childNode);

Returns: Parent node ID, or JSON_INVALID_NODE.

---

JSON_GetFirstChild(nodeId)

new first = JSON_GetFirstChild(objectNode);

Returns: First child node ID, or JSON_INVALID_NODE.

---

JSON_GetLastChild(nodeId)

new last = JSON_GetLastChild(objectNode);

Returns: Last child node ID, or JSON_INVALID_NODE.

---

JSON_GetNextSibling(nodeId)

new next = JSON_GetNextSibling(currentNode);

Returns: Next sibling node ID, or JSON_INVALID_NODE.

---

JSON_GetPrevSibling(nodeId)

new prev = JSON_GetPrevSibling(currentNode);

Returns: Previous sibling node ID, or JSON_INVALID_NODE.

---

Object Lookup

JSON_GetObjectChild(objectNode, const key[])

Finds a direct child of an object by key name.

new nameNode = JSON_GetObjectChild(root, "name");
if (nameNode != JSON_INVALID_NODE)
{
    new name[32];
    JSON_GetString(nameNode, name);
}

Returns: Node ID or JSON_INVALID_NODE.

---

JSON_ObjectHasKey(objectNode, const key[])

Checks if an object contains a specific key.

if (JSON_ObjectHasKey(root, "email"))
{
    // key exists
}

Returns: bool.

---

Array Access

JSON_GetArrayElement(arrayNode, index)

Gets an array element by zero-based index.

new elem = JSON_GetArrayElement(arrayNode, 0); // first element
if (elem != JSON_INVALID_NODE)
{
    new val;
    JSON_GetInt(elem, val);
}

Returns: Node ID or JSON_INVALID_NODE.

---

JSON_GetArraySize(arrayNode)

Returns the number of elements in an array.

new size = JSON_GetArraySize(arrayNode