source/modules/juce_core/javascript/juce_JSON.h

   1 /*
   2   ==============================================================================
   3
   4    This file is part of the JUCE library.
   5    Copyright (c) 2022 - Raw Material Software Limited
   6
   7    JUCE is an open source library subject to commercial or open-source
   8    licensing.
   9
  10    The code included in this file is provided under the terms of the ISC license
  11    http://www.isc.org/downloads/software-support-policy/isc-license. Permission
  12    To use, copy, modify, and/or distribute this software for any purpose with or
  13    without fee is hereby granted provided that the above copyright notice and
  14    this permission notice appear in all copies.
  15
  16    JUCE IS PROVIDED "AS IS" WITHOUT ANY WARRANTY, AND ALL WARRANTIES, WHETHER
  17    EXPRESSED OR IMPLIED, INCLUDING MERCHANTABILITY AND FITNESS FOR PURPOSE, ARE
  18    DISCLAIMED.
  19
  20   ==============================================================================
  21 */
  22
  23 namespace juce
  24 {
  25
  26 //==============================================================================
  27 /**
  28     Contains static methods for converting JSON-formatted text to and from var objects.
  29
  30     The var class is structurally compatible with JSON-formatted data, so these
  31     functions allow you to parse JSON into a var object, and to convert a var
  32     object to JSON-formatted text.
  33
  34     @see var
  35
  36     @tags{Core}
  37 */
  38 class JUCE_API  JSON
  39 {
  40 public:
  41     //==============================================================================
  42     /** Parses a string of JSON-formatted text, and returns a result code containing
  43         any parse errors.
  44
  45         This will return the parsed structure in the parsedResult parameter, and will
  46         return a Result object to indicate whether parsing was successful, and if not,
  47         it will contain an error message.
  48
  49         If you're not interested in the error message, you can use one of the other
  50         shortcut parse methods, which simply return a var() if the parsing fails.
  51
  52         Note that this will only parse valid JSON, which means that the item given must
  53         be either an object or an array definition. If you want to also be able to parse
  54         any kind of primitive JSON object, use the fromString() method.
  55     */
  56     static Result parse (const String& text, var& parsedResult);
  57
  58     /** Attempts to parse some JSON-formatted text, and returns the result as a var object.
  59
  60         If the parsing fails, this simply returns var() - if you need to find out more
  61         detail about the parse error, use the alternative parse() method which returns a Result.
  62
  63         Note that this will only parse valid JSON, which means that the item given must
  64         be either an object or an array definition. If you want to also be able to parse
  65         any kind of primitive JSON object, use the fromString() method.
  66     */
  67     static var parse (const String& text);
  68
  69     /** Attempts to parse some JSON-formatted text from a file, and returns the result
  70         as a var object.
  71
  72         Note that this is just a short-cut for reading the entire file into a string and
  73         parsing the result.
  74
  75         If the parsing fails, this simply returns var() - if you need to find out more
  76         detail about the parse error, use the alternative parse() method which returns a Result.
  77     */
  78     static var parse (const File& file);
  79
  80     /** Attempts to parse some JSON-formatted text from a stream, and returns the result
  81         as a var object.
  82
  83         Note that this is just a short-cut for reading the entire stream into a string and
  84         parsing the result.
  85
  86         If the parsing fails, this simply returns var() - if you need to find out more
  87         detail about the parse error, use the alternative parse() method which returns a Result.
  88     */
  89     static var parse (InputStream& input);
  90
  91     //==============================================================================
  92     /** Returns a string which contains a JSON-formatted representation of the var object.
  93         If allOnOneLine is true, the result will be compacted into a single line of text
  94         with no carriage-returns. If false, it will be laid-out in a more human-readable format.
  95         The maximumDecimalPlaces parameter determines the precision of floating point numbers
  96         in scientific notation.
  97         @see writeToStream
  98     */
  99     static String toString (const var& objectToFormat,
 100                             bool allOnOneLine = false,
 101                             int maximumDecimalPlaces = 15);
 102
 103     /** Parses a string that was created with the toString() method.
 104         This is slightly different to the parse() methods because they will reject primitive
 105         values and only accept array or object definitions, whereas this method will handle
 106         either.
 107     */
 108     static var fromString (StringRef);
 109
 110     /** Writes a JSON-formatted representation of the var object to the given stream.
 111         If allOnOneLine is true, the result will be compacted into a single line of text
 112         with no carriage-returns. If false, it will be laid-out in a more human-readable format.
 113         The maximumDecimalPlaces parameter determines the precision of floating point numbers
 114         in scientific notation.
 115         @see toString
 116     */
 117     static void writeToStream (OutputStream& output,
 118                                const var& objectToFormat,
 119                                bool allOnOneLine = false,
 120                                int maximumDecimalPlaces = 15);
 121
 122     /** Returns a version of a string with any extended characters escaped. */
 123     static String escapeString (StringRef);
 124
 125     /** Parses a quoted string-literal in JSON format, returning the un-escaped result in the
 126         result parameter, and an error message in case the content was illegal.
 127         This advances the text parameter, leaving it positioned after the closing quote.
 128     */
 129     static Result parseQuotedString (String::CharPointerType& text, var& result);
 130
 131 private:
 132     //==============================================================================
 133     JSON() = delete; // This class can't be instantiated - just use its static methods.
 134 };
 135
 136 } // namespace juce