Note: This website is archived. For up-to-date information about D projects and development, please visit wiki.dlang.org.

cashew.json -- 1.1.2

Table of Contents

  1. Introduction
  2. cashew.json.Value
    1. class JsonValue
  3. cashew.json.Exception
  4. cashew.json.Parser

Introduction

The CashewJson library (package cashew.json) provides support for the JSON (JavaScript Object Notation) data format. JSON is suitable for a number of transmission cases, such as the common usage in AJAX web-apps, and some storage cases, such as human-readable application config files. The library includes three modules, but only cashew.json.Value is necessary to import in order to use the library. Just the same, documentation for all three follows.

cashew.json.Value

This is the main module of the library, the one which user code is expected to import and interact with. It defines a few different top-level entities, the first of these being an enum of the JSON data types:

  public enum JsonType {
      Null    , /// keyword 'null'
      Object  , /// a JSON Object
      Array   , /// a JSON Array
      String  , /// a JSON String
      Bool    , /// keywords 'true' and 'false'
      Int     , /// an integral number
      Float   , /// a floating-point number
      Unknown   //  unknown type, used for sanity testing
  }

There is also a constant associative array called `JsonTypeStrings`, pairing the enum states above with a string of their name. For example, the expression JsonTypeStrings[JsonType.Int] returns the string "Int".

After this comes a set of type aliases for the D types used to represent the various JSON types:

public alias JsonValue[dchar[]]  JsonObject ;
public alias JsonValue[]         JsonArray  ;
public alias dchar[]             JsonString ;
public alias bool                JsonBool   ;
public alias long                JsonInt    ;
public alias double              JsonFloat  ;

Finally there is the JsonValue class which encapsulates JSON based data.

class JsonValue

(TODO: Fully document this class.)

cashew.json.Exception

This class defines various exceptions which may be thrown by library code.

JsonException
This is the abstract base class of all the library's exceptions.

JsonUnknownTypeException
Thrown by the JsonValue constructor and encode method when an invalid type has somehow been set. If you actually encounter this exception in the wild, please attempt to re-create it and submit a detailed bug report. Simply shouldn't ever happen.

JsonWrongTypeException
Thrown by various methods of JsonValue when attempting an operation on a type which does not support it. For example, attempting to use the index operator on a floating-point JSON value. The exception message will include what type the value actually is, and what it was most likely expected to be.

JsonArrayBoundsException
Thrown by the index operators when used with invalid indices on a JSON array value. The exception message includes the index that was attempted, and the current length of the array, for confirmation of the error.

JsonSyntaxException
Thrown by the parser when it encounters a syntactic error in a JSON source text. The exception message includes a line number and further details provided by the parser.

cashew.json.Parser