2.4.14.2 parse ( text [ , reviver ] )

  • Article

The parse function parses a JSON text (a JSON-formatted String) and produces an ECMAScript value. The JSON format is a restricted form of ECMAScript literal. JSON objects are realized as ECMAScript objects. JSON arrays are realized as ECMAScript arrays. JSON strings, numbers, booleans, and null are realized as ECMAScript Strings, Numbers, Booleans, and null. JSON uses a more limited set of white space characters than WhiteSpace, and allows Unicode code points U+2028 and U+2029 to directly appear in JSONString literals without using an escape sequence. The process of parsing is similar to [ECMA-262/5] sections 11.1.4 and 11.1.5 as constrained by the JSON grammar.

The optional reviver parameter is a function that takes two parameters, (key and value). It can filter and transform the results. It is called with each of the key/value pairs produced by the parse, and its return value is used instead of the original value. If it returns what it received, the structure is not modified. If it returns undefined, the property is deleted from the result.

  1. Let JText be ToString(text).

  2. Parse JText using the grammars in [ECMA-262/5] section 15.12.1. Raise a SyntaxError exception if JText did not conform to the JSON grammar for the goal symbol JSONText.

  3. Let unfiltered be the result of parsing and evaluating JText as if it was the source text of an ECMAScript program (see [ECMA-262-1999] section 14) but using JSONString in place of StringLiteral. Note that since JText conforms to the JSON grammar, this result will be either a primitive value or an object that is defined by either an ArrayLiteral or an ObjectLiteral.

  4. If (reviver) has a [[Call]] internal property, then

    1. Let root be a new object created as if by the expression new Object(), where Object is the standard built-in constructor with that name.

    2. Call the [[Put]] internal method of root with the empty String and unfiltered as arguments.

    3. Return the result of calling the abstract operation Walk, passing root and the empty String. The abstract operation Walk is described later in this section.

  5. Else

    1. Return unfiltered.

The abstract operation Walk is a recursive abstract operation that takes two parameters: a holder object and the String name of a property in that object. Walk uses the value of reviver that was originally passed to the previous parse function.

  1. Let val be the result of calling the [[Get]] internal method of holder with argument name.

  2. If val is an object, then

    1. If the [[Class]] internal property of val is "Array"

      1. Set I to 0.

      2. Let len be the result of calling the [[Get]] internal method of val with argument "length".

      3. Repeat while I < len,

        1. Let newElement be the result of calling the abstract operation Walk, passing val and ToString(I).

        2. If newElement is undefined, then

          1. Call the [[Delete]] internal method of val with ToString(I).

        3. Else

          1. Call the [[Put]] internal method of val with arguments ToString(I) and newElement.

        4. Add 1 to I.

    2. Else

      1. Let keys be an internal list of String values consisting of the names of all the own properties of val that do not have the DontEnum attribute. The ordering of the Strings should be the same as that used by the for-in statement.

        Note that JScript 5.x defines properties (see [ECMA-262-1999] 8.6.2.2) such that their DontEnum attribute is inherited from prototype properties with the same name. As a result of this, any own properties of value that have the same name as built-in properties that have the DontEnum attribute are not included in keys.

      2. For each String P in keys do,

        1. Let newElement be the result of calling the abstract operation Walk, passing val and P.

        2. If newElement is undefined, then

          1. Call the [[Delete]] internal method of val with argument P.

        3. Else

          1. Call the [[Put]] internal method of val with arguments P and newElement.

      3. Return the result of calling the [[Call]] internal method of reviver passing holder as the this value and with an argument list consisting of name and val.

It is not permitted for a conforming implementation of JSON.parse to extend the JSON grammars. If an implementation wants to support a modified or extended JSON interchange format, it must do so by defining a different parse function.

NOTE:  In the case where there are duplicate name Strings within an object, lexically preceding values for the same key shall be overwritten.