{"id":13419999,"url":"https://github.com/tgockel/json-voorhees","last_synced_at":"2025-03-15T06:31:13.642Z","repository":{"id":20399840,"uuid":"23675821","full_name":"tgockel/json-voorhees","owner":"tgockel","description":"A killer modern C++ library for interacting with JSON.","archived":false,"fork":false,"pushed_at":"2024-07-27T05:10:46.000Z","size":8384,"stargazers_count":128,"open_issues_count":20,"forks_count":18,"subscribers_count":10,"default_branch":"trunk","last_synced_at":"2024-07-31T22:52:55.389Z","etag":null,"topics":["c-plus-plus","json","json-serialization"],"latest_commit_sha":null,"homepage":"http://tgockel.github.io/json-voorhees/","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tgockel.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.rst","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2014-09-04T19:14:32.000Z","updated_at":"2024-07-27T05:10:51.000Z","dependencies_parsed_at":"2022-07-25T07:47:05.264Z","dependency_job_id":null,"html_url":"https://github.com/tgockel/json-voorhees","commit_stats":null,"previous_names":[],"tags_count":18,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tgockel%2Fjson-voorhees","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tgockel%2Fjson-voorhees/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tgockel%2Fjson-voorhees/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tgockel%2Fjson-voorhees/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tgockel","download_url":"https://codeload.github.com/tgockel/json-voorhees/tar.gz/refs/heads/trunk","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":221548254,"owners_count":16840981,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["c-plus-plus","json","json-serialization"],"created_at":"2024-07-30T22:01:24.214Z","updated_at":"2025-03-15T06:31:13.636Z","avatar_url":"https://github.com/tgockel.png","language":"C++","funding_links":[],"categories":["TODO scan for Android support in followings","JSON","进程间通信"],"sub_categories":["Json"],"readme":"JSON Voorhees\n=============\n\nYet another [JSON][JSON] library for C++.\nThis one touts new C++11 features for developer-friendliness, an extremely slow-speed parser and no dependencies beyond\n a compliant compiler.\nIf you love Doxygen, check out the [documentation](http://tgockel.github.io/json-voorhees/).\n\nFeatures include (but are not necessarily limited to):\n\n - Simple\n   - A `value` should not feel terribly different from a C++ Standard Library container\n   - Write valid JSON with `operator\u003c\u003c`\n   - Simple JSON parsing with `parse`\n   - Reasonable error messages when parsing fails\n   - Full support for Unicode-filled JSON (encoded in UTF-8 in C++)\n - Efficient\n   - Minimal overhead to store values (a `value` is 16 bytes on a 64-bit platform)\n   - No-throw move semantics wherever possible\n - Easy\n   - Convert a `value` into a C++ type using `extract\u003cT\u003e`\n   - Encode a C++ type into a value using `to_json`\n - Safe\n   - In the best case, illegal code should fail to compile\n   - An illegal action should throw an exception\n   - Almost all utility functions have a [strong exception guarantee](http://www.gotw.ca/gotw/082.htm)\n - Stable\n   - Worry less about upgrading -- the API and ABI will not change out from under you\n - Documented\n   - Consumable by human beings\n   - Answers questions you might actually ask\n - Compiler support\n     - GCC (4.8+)\n     - Clang++ (3.3+)\n\n[![Build Status](https://travis-ci.org/tgockel/json-voorhees.svg?branch=master)](https://travis-ci.org/tgockel/json-voorhees)\n[![Coverage Status](https://coveralls.io/repos/tgockel/json-voorhees/badge.svg?branch=master\u0026service=github)](https://coveralls.io/github/tgockel/json-voorhees?branch=master)\n[![Flattr this git repo](http://api.flattr.com/button/flattr-badge-large.png)](https://flattr.com/submit/auto?user_id=tgockel\u0026url=https://github.com/tgockel/json-voorhees\u0026title=json-voorhees\u0026language=c++\u0026tags=github\u0026category=software)\n\n![JSON Conversions](https://raw.githubusercontent.com/tgockel/json-voorhees/master/doc/conversions.png)\n\nCompile and Install\n-------------------\n\nJSON Voorhees uses [CMake](http://www.cmake.org/) as the automatic configuration software.\nOn Linux or Mac OSX, if you have `boost`, `cmake`, `g++` and `make` installed, simply:\n\n    $\u003e cmake .\n    $\u003e make\n    $\u003e sudo make install\n\nIf you want to customize your compilation or installation, see the options in `CMakeLists.txt` for easy-to-use\n configuration options.\n\nIf you are on Windows, you can also use CMake if you want.\nHowever, it is probably easier to use the provided Visual Studio project files in `msvc/vs2015` to get going.\nHitting F5 should perform a NuGet restore, then compile and run all the unit tests.\n\n### Arch Linux\n\nIf you use [Arch Linux](https://www.archlinux.org/), JSON Voorhees is easily installable via AUR.\nThe \"latest stable\" is called [json-voorhees](https://aur.archlinux.org/packages/json-voorhees), while there is a \"close\n to tip\" package called [json-voorhees-git](https://aur.archlinux.org/packages/json-voorhees-git).\nWith Arch, installation is as easy as `yaourt json-voorhees`!\n\nFuture\n------\n\nFuture planned features can be found on the [issue tracker][future-features].\n\nLicense\n-------\n\nLicensed under the Apache License, Version 2.0 (the \"License\"); you may not use this file except in compliance with\nthe License. You may obtain a copy of the License at\n\n  [http://www.apache.org/licenses/LICENSE-2.0](http://www.apache.org/licenses/LICENSE-2.0)\n\nUnless required by applicable law or agreed to in writing, software distributed under the License is distributed on\nan \"AS IS\" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the\nspecific language governing permissions and limitations under the License.\n\nMiscellaneous\n=============\n\nCompiler Support\n----------------\n\n - Supported\n     - GCC 4.8+\n     - Clang 3.3+\n - Experimental\n     - MSVC 14.0 CTP5+ (Visual C++ 2015)\n\nVersioning\n----------\n\nLike every software system ever, JSON Voorhees describes versions in 3 part [semantic versioning](http://semver.org/):\n `${major}.${minor}.${patch}`.\nThe version components changing have very specific meanings:\n\n - `major`: There are no guarantees whatsoever across major releases.\n - `minor`: For a given minor release, all code is forward-compatible source-code compliant.\n            That means code written against version 1.1 can be recompiled against version 1.4 and continue to work.\n            No guarantees are made for going backwards (version 1.4 might have added new functions).\n - `patch`: Code is ABI-compatible across patch.\n                  Library *A* built against JSON Voorhees 1.2.4 should be able to pass a `jsonv::value` to library *B*\n                   built against JSON Voorhees 1.2.9.\n                  Any change to publicly-visible data structures or calling conventions will correspond to a bump in the\n                   minor version.\n\nThe preceding statements are not true if the version is suffixed with `-preN`.\nThese values are \"pre-release\" and are allowed to do whatever they feel like before a release.\n\nWhen developing code, follow this simple workflow to determine which version components need to change:\n\n 1. *Will this change force users to change their source code?*\n    If yes, bump the `major` version.\n 2. *Will this change force users to recompile to continue to work?*\n    If yes, bump the `minor` version.\n 3. *Will this change the behavior in any way?*\n    If yes, bump the `patch` version.\n 4. *Did I only change comments or rearrange code positioning (indentation, etc)?*\n    If yes, you do not need to update any part of the version.\n 5. *Did I miss something?*\n    Yes. Go back to #1 and try again.\n\nCharacter Encoding\n------------------\n\nThis library assumes you [really love UTF-8][utf8].\nWhen parsing JSON, this library happily assumes all sequences of bytes from C++ are UTF-8 encoded strings; it assumes\n you also want UTF-8 encoded strings when converting from JSON in C++ land; and it assumes the non-ASCII contents of a\n source string should be treated as UTF-8.\nIf you wish to use some other encoding format for your `std::string`, there is no convenient way to do that beyond\n conversion at every use site.\nThere is a [proposal][decode-non-utf8] to potentially address this.\n\nOn output, the system takes the \"safe\" route of using the numeric encoding for dealing with non-ASCII `std::string`s.\nFor example, the `std::string` for `\"Travis Göckel\"` (`\"Travis G\\xc3\\xb6ckel\"`) will be encoded in JSON as\n `\"Travis G\\u00f6ckel\"`, despite the fact that the character `'ö'` is the most basic of the Unicode Basic Multilingual\n Planes.\nThis is generally considered the most compatible option, as (hopefully) every transport mechanism can gracefully\n transmit ASCII character sequences without molestation.\nThe drawback to this route is a needlessly lengthened resultant encoding if all components of the pipeline gracefully\n deal with UTF-8.\nThere is an [outstanding issue][encode-utf8] to address this shortcoming.\n\nF.A.Q.\n------\n\n### What makes JSON Voorhees different from the other C++ JSON libraries?\n\nJSON Voorhees was written for a C++ programmer who wants to be productive in this modern world.\nWhat does that mean?\nThere are a *ton* of JSON libraries floating around touting how they are \"modern\" C++ and so on.\nBut who really cares?\nJSON Voorhees puts the focus more on the resulting C++ than any \"modern\" feature set.\nThis means the library does not skip on string encoding details like having full support for [UTF-8][utf8].\nAre there \"modern\" features?\nSure, but this library is *not* meant to be a gallery of them -- a good API should get out of your way and let you work.\n\nAnother thing JSON Voorhees does not attempt to do is be a lightweight library; in fact, it wants to be the kitchen sink\n for anything you want to do in JSON in your C++ application.\nThis means it is [*configurable*](https://github.com/tgockel/json-voorhees/blob/master/include/jsonv/config.hpp) for your\n needs.\nThat said, the library does not depend on strange environment settings, so you can still drop the `.cpp` and `.hpp` files\n into your own project if you want.\n\nIt also includes a powerful serialization framework for converting from JSON into C++ types and back again.\nThere is an extensible [Serialization Builder DSL](http://tgockel.github.io/json-voorhees/serialization_builder_dsl.html)\n to help you writing your application.\nThe serialization framework was designed with the modern application in mind -- you will like it or your money back!\n\n### Why are `integer` and `decimal` distinct types?\n\nThe [JSON specification][JSON] only has a *number* type, whereas this library has `kind::integer` and `kind::decimal`.\nBehavior between the two types should be fairly consistent -- comparisons between two different `kind`s should behave as\n you would expect (assuming you expect things like `value(1) == value(1.0)` and `value(2.0) \u003c value(10)`).\nIf you wish for behavior more like JavaScript, feel free to only use `as_decimal()`.\n\nThe reason integer and decimal are not a single type is because of how people tend to use JSON in C++.\nIf you look at projects that consume JSON, they make a distinction between integer and decimal values.\nEven in specification land, a distinction between the numeric type is pretty normal (for example:\n [Swagger](http://swagger.io/)).\nTo ultimately answer the question: integer and decimal are distinct types for the convenience of users.\n\n### Why are `NaN` and `INFINITY` serialized as a `null`?\n\nThe [JSON specification][JSON] does *not* have support for non-finite floating-point numbers like `NaN` and infinity.\nThis means the `value` defined with `object({ { \"nan\", std::nan(\"\") }, { \"infinity\", INFINITY } })` to get serialized as\n `{ \"nan\": null, \"infinity\": null }`.\nWhile this seems to constitute a loss of information, not doing this would lead to the encoder outputting invalid JSON\n text, which is completely unacceptable (unfortunately, this is a *very common* mistake in JSON libraries).\nIf you want to check that there will be no information loss when encoding, use the utility funciton `validate`.\n\n*Why not throw when encoding?*\nOne could imagine the `encoder::encode` throwing something like an `encode_error` instead of outputting `null` to the\n stream.\nHowever, that would make `operator\u003c\u003c` a potentially-throwing operation, which is extremely uncommon and would be very\n surprizing (imagine if you tried to log a `value` and it threw).\n\n*Why not throw when constructing the `value`?*\nInstead of waiting for encoding time to do anything about the problem, the library could attack the issue at the source\n and throw an exception if someone says `value(INFINITY)`.\nThis was not chosen as the behavior, because non-finite values are only an issue in the string representation, which is\n not a problem if the `value` is never encoded.\nYou are free to use this JSON library without `parse` and `encode`, so it should not prevent an action simply because\n someone *might* use `encode`.\n\n### Why are there so many corruption checks?\n\nIf you are looking through the implementation, you will find a ton of places where there are `default` cases in `switch`\n statements that should be impossible to hit without memory corruption.\nThis is because it is unclear what should happen when the library detects something like an invalid `kind`.\nThe library could `assert`, but that seems overbearing when there is a reasonable option to fall back to.\nAlternatively, the library could throw in these cases, but that leads to innocuous-looking operations like `x == y`\n being able to throw, which is somewhat disconcerning.\n\n### This is really helpful! Can I give you money?\n\nI would be [Flattr-ed](https://flattr.com/submit/auto?user_id=tgockel\u0026url=https://github.com/tgockel/json-voorhees\u0026title=json-voorhees\u0026language=c++\u0026tags=github\u0026category=software)!\n\n### With such a cool name, do you have an equally cool logo?\n\nNot really...\n\n![JSON: Serialized Killer](https://raw.githubusercontent.com/tgockel/json-voorhees/master/doc/meme.jpg)\n\n\n [decode-non-utf8]: https://github.com/tgockel/json-voorhees/issues/10\n    \"Decode numeric encodings into arbitrarily encoded std::string\"\n [encode-utf8]: https://github.com/tgockel/json-voorhees/issues/11\n    \"Issue 21: String encoding should allow UTF-8 output\"\n [future-features]: https://github.com/tgockel/json-voorhees/issues?q=is%3Aopen+is%3Aissue+no%3Amilestone\n    \"Future features\"\n [JSON]: http://www.json.org/\n    \"JSON Specification\"\n [utf8]: http://www.utf8everywhere.org/\n    \"UTF8 Everywhere!\"\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftgockel%2Fjson-voorhees","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftgockel%2Fjson-voorhees","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftgockel%2Fjson-voorhees/lists"}