include/openvswitch/json.h

   1 /*
   2  * Copyright (c) 2009, 2010, 2015, 2016 Nicira, Inc.
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at:
   7  *
   8  *     http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 #ifndef JSON_H
  18 #define JSON_H 1
  19
  20 /* This is an implementation of JavaScript Object Notation (JSON) as specified
  21  * by RFC 4627.  It is intended to fully comply with RFC 4627, with the
  22  * following known exceptions and clarifications:
  23  *
  24  *      - Null bytes (\u0000) are not allowed in strings.
  25  *
  26  *      - Only UTF-8 encoding is supported (RFC 4627 allows for other Unicode
  27  *        encodings).
  28  *
  29  *      - Names within an object must be unique (RFC 4627 says that they
  30  *        "should" be unique).
  31  */
  32
  33 #include <stdio.h>
  34 #include "openvswitch/shash.h"
  35
  36 #ifdef  __cplusplus
  37 extern "C" {
  38 #endif
  39
  40 struct ds;
  41 struct uuid;
  42
  43 /* Type of a JSON value. */
  44 enum json_type {
  45     JSON_NULL,                  /* null */
  46     JSON_FALSE,                 /* false */
  47     JSON_TRUE,                  /* true */
  48     JSON_OBJECT,                /* {"a": b, "c": d, ...} */
  49     JSON_ARRAY,                 /* [1, 2, 3, ...] */
  50     JSON_INTEGER,               /* 123. */
  51     JSON_REAL,                  /* 123.456. */
  52     JSON_STRING,                /* "..." */
  53     JSON_N_TYPES
  54 };
  55
  56 const char *json_type_to_string(enum json_type);
  57
  58 /* A JSON array. */
  59 struct json_array {
  60     size_t n, n_allocated;
  61     struct json **elems;
  62 };
  63
  64 /* A JSON value. */
  65 struct json {
  66     enum json_type type;
  67     size_t count;
  68     union {
  69         struct shash *object;   /* Contains "struct json *"s. */
  70         struct json_array array;
  71         long long int integer;
  72         double real;
  73         char *string;
  74     } u;
  75 };
  76
  77 struct json *json_null_create(void);
  78 struct json *json_boolean_create(bool);
  79 struct json *json_string_create(const char *);
  80 struct json *json_string_create_nocopy(char *);
  81 struct json *json_integer_create(long long int);
  82 struct json *json_real_create(double);
  83
  84 struct json *json_array_create_empty(void);
  85 void json_array_add(struct json *, struct json *element);
  86 void json_array_trim(struct json *);
  87 struct json *json_array_create(struct json **, size_t n);
  88 struct json *json_array_create_1(struct json *);
  89 struct json *json_array_create_2(struct json *, struct json *);
  90 struct json *json_array_create_3(struct json *, struct json *, struct json *);
  91
  92 struct json *json_object_create(void);
  93 void json_object_put(struct json *, const char *name, struct json *value);
  94 void json_object_put_nocopy(struct json *, char *name, struct json *value);
  95 void json_object_put_string(struct json *,
  96                             const char *name, const char *value);
  97 void json_object_put_format(struct json *,
  98                             const char *name, const char *format, ...)
  99     OVS_PRINTF_FORMAT(3, 4);
 100
 101 const char *json_string(const struct json *);
 102 struct json_array *json_array(const struct json *);
 103 struct shash *json_object(const struct json *);
 104 bool json_boolean(const struct json *);
 105 double json_real(const struct json *);
 106 int64_t json_integer(const struct json *);
 107
 108 struct json *json_deep_clone(const struct json *);
 109 struct json *json_clone(const struct json *);
 110 struct json *json_nullable_clone(const struct json *);
 111 void json_destroy(struct json *);
 112
 113 size_t json_hash(const struct json *, size_t basis);
 114 bool json_equal(const struct json *, const struct json *);
 115 \f
 116 /* Parsing JSON. */
 117 enum {
 118     JSPF_TRAILER = 1 << 0       /* Check for garbage following input.  */
 119 };
 120
 121 struct json_parser *json_parser_create(int flags);
 122 size_t json_parser_feed(struct json_parser *, const char *, size_t);
 123 bool json_parser_is_done(const struct json_parser *);
 124 struct json *json_parser_finish(struct json_parser *);
 125 void json_parser_abort(struct json_parser *);
 126
 127 struct json *json_from_string(const char *string);
 128 struct json *json_from_file(const char *file_name);
 129 struct json *json_from_stream(FILE *stream);
 130 \f
 131 /* Serializing JSON. */
 132
 133 enum {
 134     JSSF_PRETTY = 1 << 0,       /* Multiple lines with indentation, if true. */
 135     JSSF_SORT = 1 << 1          /* Object members in sorted order, if true. */
 136 };
 137 char *json_to_string(const struct json *, int flags);
 138 void json_to_ds(const struct json *, int flags, struct ds *);
 139 \f
 140 /* JSON string formatting operations. */
 141
 142 bool json_string_unescape(const char *in, size_t in_len, char **outp);
 143 void json_string_escape(const char *in, struct ds *out);
 144
 145 #ifdef  __cplusplus
 146 }
 147 #endif
 148
 149 #endif /* json.h */