# Module json

This module implements a simple high performance JSON parser. JSON (JavaScript Object Notation) is a lightweight data-interchange format that is easy for humans to read and write (unlike XML). It is easy for machines to parse and generate. JSON is based on a subset of the JavaScript Programming Language, Standard ECMA-262 3rd Edition - December 1999.

# Imports

hashes, strutils, lexbase, streams, unicode

# Types

    TJsonEventKind* = enum
      jsonError,                  ## an error ocurred during parsing
      jsonEof,                    ## end of file reached
      jsonString,                 ## a string literal
      jsonInt,                    ## an integer literal
      jsonFloat,                  ## a float literal
      jsonTrue,                   ## the value ``true``
      jsonFalse,                  ## the value ``false``
      jsonNull,                   ## the value ``null``
      jsonObjectStart,            ## start of an object: the ``{`` token
      jsonObjectEnd,              ## end of an object: the ``}`` token
      jsonArrayStart,             ## start of an array: the ``[`` token
      jsonArrayEnd                ## start of an array: the ``]`` token

  enumeration of all events that may occur when parsing

    TJsonError* = enum
      errNone,                    ## no error
      errInvalidToken,            ## invalid token
      errStringExpected,          ## string expected
      errColonExpected,           ## ``:`` expected
      errCommaExpected,           ## ``,`` expected
      errBracketRiExpected,       ## ``]`` expected
      errCurlyRiExpected,         ## ``}`` expected
      errQuoteExpected,           ## ``"`` or ``'`` expected
      errEOC_Expected,            ## ``*/`` expected
      errEofExpected,             ## EOF expected
      errExprExpected             ## expr expected

  enumeration that lists all errors that can occur

    TJsonParser* = object of TBaseLexer
      a: string
      tok: TTokKind
      kind: TJsonEventKind
      err: TJsonError
      state: seq[TParserState]
      filename: string

  the parser object.

    TJsonNodeKind* = enum
      JNull, JBool, JInt, JFloat, JString, JObject, JArray

  possible JSON node types

    PJsonNode* = ref TJsonNode

  JSON node

    TJsonNode* {.final, pure, acyclic.} = object
      case kind*: TJsonNodeKind
      of JString:
          str*: string

      of JInt:
          num*: biggestInt

      of JFloat:
          fnum*: float

      of JBool:
          bval*: bool

      of JNull:
          nil

      of JObject:
          fields*: seq[tuple[key: string, val: PJsonNode]]

      of JArray:
          elems*: seq[PJsonNode]

    EJsonParsingError* = object of EInvalidValue

  is raised for a JSON error

# Procs

    proc open*(my: var TJsonParser; input: PStream; filename: string)

  initializes the parser with an input stream. Filename is only used for nice error messages.

    proc close*(my: var TJsonParser) {.inline.}

  closes the parser my and its associated input stream.

    proc str*(my: TJsonParser): string {.inline.}

  returns the character data for the events: `jsonInt`, `jsonFloat`, `jsonString`

    proc getInt*(my: TJsonParser): biggestInt {.inline.}

  returns the number for the event: `jsonInt`

    proc getFloat*(my: TJsonParser): float {.inline.}

  returns the number for the event: `jsonFloat`

    proc kind*(my: TJsonParser): TJsonEventKind {.inline.}

  returns the current event type for the JSON parser

    proc getColumn*(my: TJsonParser): int {.inline.}

  get the current column the parser has arrived at.

    proc getLine*(my: TJsonParser): int {.inline.}

  get the current line the parser has arrived at.

    proc getFilename*(my: TJsonParser): string {.inline.}

  get the filename of the file that the parser processes.

    proc errorMsg*(my: TJsonParser): string

  returns a helpful error message for the event `jsonError`

    proc errorMsgExpected*(my: TJsonParser; e: string): string

  returns an error message "e expected" in the same format as the other error messages

    proc next*(my: var TJsonParser)

  retrieves the first/next event. This controls the parser.

    proc raiseParseErr*(p: TJsonParser; msg: string) {.noinline, noreturn.}

  raises an EJsonParsingError exception.

    proc newJString*(s: String): PJsonNode

  Creates a new JString PJsonNode.

    proc newJInt*(n: biggestInt): PJsonNode

  Creates a new JInt PJsonNode.

    proc newJFloat*(n: Float): PJsonNode

  Creates a new JFloat PJsonNode.

    proc newJBool*(b: Bool): PJsonNode

  Creates a new JBool PJsonNode.

    proc newJNull*(): PJsonNode

  Creates a new JNull PJsonNode.

    proc newJObject*(): PJsonNode

  Creates a new JObject PJsonNode

    proc newJArray*(): PJsonNode

  Creates a new JArray PJsonNode

    proc `%`*(s: string): PJsonNode

  Generic constructor for JSON data. Creates a new JString PJsonNode.

    proc `%`*(n: biggestInt): PJsonNode

  Generic constructor for JSON data. Creates a new JInt PJsonNode.

    proc `%`*(n: float): PJsonNode

  Generic constructor for JSON data. Creates a new JFloat PJsonNode.

    proc `%`*(b: bool): PJsonNode

  Generic constructor for JSON data. Creates a new JBool PJsonNode.

    proc `%`*(keyVals: openArray[tuple[key: string, val: PJsonNode]]): PJsonNode

  Generic constructor for JSON data. Creates a new JObject PJsonNode

    proc `%`*(elements: openArray[PJSonNode]): PJsonNode

  Generic constructor for JSON data. Creates a new JArray PJsonNode

    proc len*(n: PJsonNode): int

  If n is a JArray, it returns the number of elements. If n is a JObject, it returns the number of pairs. Else it returns 0.

    proc `[]`*(node: PJsonNode; name: String): PJsonNode

  Gets a field from a JObject.

    proc `[]`*(node: PJsonNode; index: Int): PJsonNode

  Gets the node at index in an Array.

    proc existsKey*(node: PJsonNode; key: String): Bool

  Checks if key exists in node.

    proc add*(father, child: PJsonNode)

  Adds child to a JArray node father.

    proc add*(obj: PJsonNode; key: string; val: PJsonNode)

  Adds `(key, val)` pair to the JObject node obj. For speed reasons no check for duplicate keys is performed! But `[]=` performs the check.

    proc `[] =`*(obj: PJsonNode; key: String; val: PJsonNode)

  Sets a field from a JObject. Performs a check for duplicate keys.

    proc delete*(obj: PJsonNode; key: string)

  Deletes `obj[key]` preserving the order of the other (key, value)-pairs.

    proc copy*(p: PJsonNode): PJsonNode

  Performs a deep copy of a.

    proc escapeJson*(s: string): string

  Converts a string s to its JSON representation.

    proc pretty*(node: PJsonNode; indent = 2): String

  Converts node to its JSON Representation, with indentation and on multiple lines.

    proc `$`*(node: PJsonNode): String

  Converts node to its JSON Representation on one line.

    proc parseJson*(s: PStream; filename: string): PJsonNode

  Parses from a stream s into a PJsonNode. filename is only needed for nice error messages.

    proc parseJson*(buffer: string): PJsonNode

  Parses JSON from buffer.

    proc parseFile*(filename: string): PJsonNode

  Parses file into a PJsonNode.

# Iterators

    iterator items*(node: PJsonNode): PJSonNode

  Iterator for the items of node. node has to be a JArray.

    iterator pairs*(node: PJsonNode): tuple[key: string, val: PJsonNode]

  Iterator for the child elements of node. node has to be a JObject.

Generated: 2012-09-23 21:47:54 UTC