diff options
Diffstat (limited to 'docs/handbook/json4cpp/code-style.md')
| -rw-r--r-- | docs/handbook/json4cpp/code-style.md | 209 |
1 files changed, 209 insertions, 0 deletions
diff --git a/docs/handbook/json4cpp/code-style.md b/docs/handbook/json4cpp/code-style.md new file mode 100644 index 0000000000..05fb76f4dd --- /dev/null +++ b/docs/handbook/json4cpp/code-style.md @@ -0,0 +1,209 @@ +# json4cpp — Code Style & Conventions + +## Source Organisation + +### Directory Layout + +``` +json4cpp/ +├── include/nlohmann/ # Multi-header installation +│ ├── json.hpp # Main header (includes everything) +│ ├── json_fwd.hpp # Forward declarations only +│ ├── adl_serializer.hpp # ADL-based serializer +│ ├── byte_container_with_subtype.hpp +│ ├── ordered_map.hpp # Insertion-order map +│ └── detail/ # Internal implementation +│ ├── exceptions.hpp # Exception hierarchy +│ ├── hash.hpp # std::hash specialization +│ ├── json_pointer.hpp # RFC 6901 implementation +│ ├── json_ref.hpp # Internal reference wrapper +│ ├── macro_scope.hpp # Macro definitions +│ ├── macro_unscope.hpp # Macro undefinitions +│ ├── string_concat.hpp # String concatenation helper +│ ├── string_escape.hpp # String escaping utilities +│ ├── value_t.hpp # value_t enum +│ ├── abi_macros.hpp # ABI versioning macros +│ ├── conversions/ # Type conversion traits +│ ├── input/ # Parsing pipeline +│ ├── iterators/ # Iterator implementations +│ ├── meta/ # Type traits & SFINAE +│ └── output/ # Serialization pipeline +├── single_include/nlohmann/ # Single-header (amalgamated) +│ └── json.hpp # Complete library in one file +├── tests/ # Test suite (doctest) +│ ├── CMakeLists.txt +│ └── src/ +│ └── unit-*.cpp # One file per feature area +└── CMakeLists.txt # Build configuration +``` + +### Public vs. Internal API + +- `include/nlohmann/*.hpp` — public API, included by users +- `include/nlohmann/detail/` — internal, not for direct inclusion +- `single_include/` — generated amalgamation, mirrors the public API + +Users should only include `<nlohmann/json.hpp>` or +`<nlohmann/json_fwd.hpp>`. + +## Naming Conventions + +### Types + +- Template parameters: `PascalCase` — `BasicJsonType`, `ObjectType`, + `InputAdapterType` +- Type aliases: `snake_case` — `value_t`, `object_t`, `string_t`, + `number_integer_t` +- Internal classes: `snake_case` — `iter_impl`, `binary_reader`, + `json_sax_dom_parser` + +### Functions and Methods + +- All functions: `snake_case` — `parse()`, `dump()`, `push_back()`, + `is_null()`, `get_to()`, `merge_patch()` +- Private methods: `snake_case` — `set_parent()`, `assert_invariant()` + +### Variables + +- Member variables: `m_` prefix — `m_type`, `m_value`, `m_parent` +- Local variables: `snake_case` — `reference_tokens`, `token_buffer` + +### Macros + +- All macros: `SCREAMING_SNAKE_CASE` with project prefix +- Public macros: `NLOHMANN_` prefix or `JSON_` prefix + - `NLOHMANN_DEFINE_TYPE_INTRUSIVE` + - `NLOHMANN_JSON_SERIALIZE_ENUM` + - `JSON_DIAGNOSTICS` + - `JSON_USE_IMPLICIT_CONVERSIONS` +- Internal macros: `NLOHMANN_JSON_` prefix for implementation detail macros +- All macros are undefined by `macro_unscope.hpp` to avoid pollution + +### Namespaces + +```cpp +namespace nlohmann { + // Public API: basic_json, json, ordered_json, json_pointer, ... + namespace detail { + // Internal implementation + } + namespace literals { + namespace json_literals { + // _json, _json_pointer UDLs + } + } +} +``` + +The `NLOHMANN_JSON_NAMESPACE_BEGIN` / `NLOHMANN_JSON_NAMESPACE_END` macros +handle optional ABI versioning via inline namespaces. + +## Template Style + +### SFINAE Guards + +The library uses SFINAE extensively to constrain overloads: + +```cpp +template<typename BasicJsonType, typename T, + enable_if_t<is_compatible_type<BasicJsonType, T>::value, int> = 0> +void to_json(BasicJsonType& j, T&& val); +``` + +The `enable_if_t<..., int> = 0` pattern is used throughout instead of +`enable_if_t<..., void>` or return-type SFINAE. + +### Tag Dispatch + +Priority tags resolve overload ambiguity: + +```cpp +template<unsigned N> struct priority_tag : priority_tag<N - 1> {}; +template<> struct priority_tag<0> {}; +``` + +Higher-numbered tags are tried first (since they inherit from lower ones). + +### `static_assert` Guards + +Critical type requirements use `static_assert` with readable messages: + +```cpp +static_assert(std::is_default_constructible<T>::value, + "T must be default constructible"); +``` + +## Header Guards + +Each header uses `#ifndef` guards following the pattern: + +```cpp +#ifndef INCLUDE_NLOHMANN_JSON_HPP_ +#define INCLUDE_NLOHMANN_JSON_HPP_ +// ... +#endif // INCLUDE_NLOHMANN_JSON_HPP_ +``` + +Detail headers follow `INCLUDE_NLOHMANN_JSON_DETAIL_*` naming. + +## Code Documentation + +### Doxygen-Style Comments + +Public API methods use `///` or `/** */` with standard Doxygen tags: + +```cpp +/// @brief parse a JSON value from a string +/// @param[in] i the input to parse +/// @param[in] cb a callback function (default: none) +/// @param[in] allow_exceptions whether exceptions should be thrown +/// @return the parsed JSON value +static basic_json parse(InputType&& i, ...); +``` + +### `@sa` Cross References + +Related methods are linked with `@sa`: + +```cpp +/// @sa dump() for serialization +/// @sa operator>> for stream parsing +``` + +### `@throw` Documentation + +Exception-throwing methods document which exceptions they throw: + +```cpp +/// @throw parse_error.101 if unexpected token +/// @throw parse_error.102 if invalid unicode escape +``` + +## Error Handling Style + +- Public API methods that can fail throw typed exceptions from the + hierarchy (`parse_error`, `type_error`, `out_of_range`, + `invalid_iterator`, `other_error`) +- Each exception has a unique numeric ID for programmatic handling +- Error messages follow the format: + `[json.exception.<type>.<id>] <description>` +- Internal assertions use `JSON_ASSERT(condition)` which maps to + `assert()` by default + +## Compatibility + +### C++ Standard + +- Minimum: C++11 +- Optional features with C++14: heterogeneous lookup + (`std::less<>`) +- Optional features with C++17: `std::string_view`, `std::optional`, + `std::variant`, `std::filesystem::path`, structured bindings, + `if constexpr` +- Optional features with C++20: modules, `operator<=>` + +### Compiler Notes + +Tested compilers include GCC ≥ 4.8, Clang ≥ 3.4, MSVC ≥ 2015, Intel +C++, and various others. Compiler-specific workarounds are guarded with +preprocessor conditionals. |