diff --git a/docs/mkdocs/docs/api/basic_json/format_as.md b/docs/mkdocs/docs/api/basic_json/format_as.md index 129e537cf..d4315ce44 100644 --- a/docs/mkdocs/docs/api/basic_json/format_as.md +++ b/docs/mkdocs/docs/api/basic_json/format_as.md @@ -49,21 +49,24 @@ std::string format_as(const BasicJsonType& j) `fmt` only picks up a `format_as` overload that returns a `std::string` in fmt **10.0.0 through 11.0.2**. Starting with fmt **11.1.0**, `fmt` restricts automatic `format_as` pickup to overloads that return an arithmetic type, so this function has no effect there (it is simply unused, not a compile - error). If you use fmt \>= 11.1.0 (or want the same `#!cpp "{:#}"` pretty-print support that - [`std::formatter`](std_formatter.md) has), define your own `fmt::formatter` specialization, - for example: + error). + + If you use fmt \>= 11.1.0, or want the same pretty-print spec support that + [`std::formatter`](std_formatter.md) has (`#!cpp "{:#}"`, a width to set the indent such + as `#!cpp "{:2}"`/`#!cpp "{:#2}"`, and fill-and-align to pick the indent character such as + `#!cpp "{:.>#}"`), define your own `fmt::formatter` specialization mirroring the same logic: ```cpp - template <> - struct fmt::formatter : fmt::formatter - { - auto format(const nlohmann::json& j, format_context& ctx) const - { - return fmt::formatter::format(j.dump(), ctx); - } - }; + --8<-- "../../../tests/fmt_formatter/project/main.cpp:formatter_recipe" ``` + This recipe isn't shipped by the library itself, since doing so would make `fmt` a build dependency + (see the FAQ entry on + [using JSON values with `std::format` or `fmt`](../../home/faq.md#using-json-values-with-stdformat-or-fmt) + for more background) — but it *is* compiled and exercised against a real, current `fmt` release as + part of the library's own test suite (`tests/fmt_formatter`, via CMake `FetchContent`), so it's kept in + sync with `std::formatter` and verified to actually work, not just illustrative. + ## Examples ??? example diff --git a/docs/mkdocs/docs/api/basic_json/std_formatter.md b/docs/mkdocs/docs/api/basic_json/std_formatter.md index 2d3278a75..dee77ef6c 100644 --- a/docs/mkdocs/docs/api/basic_json/std_formatter.md +++ b/docs/mkdocs/docs/api/basic_json/std_formatter.md @@ -10,11 +10,21 @@ namespace std { Specialization to make JSON values formattable with [`std::format`](https://en.cppreference.com/w/cpp/utility/format/format) (and the other members of C++20's `` header, such as `std::format_to`). -Only an empty format spec (`#!cpp "{}"`) or the single flag `#!cpp "{:#}"` are accepted; any other spec -throws [`std::format_error`](https://en.cppreference.com/w/cpp/utility/format/format_error). +A subset of the [standard format spec grammar](https://en.cppreference.com/w/cpp/utility/format/spec) is +supported, repurposed for JSON pretty-printing; any other spec component (sign, the `0` flag, precision, +`L`, a dynamic width such as `#!cpp "{:{}}"`, or a trailing type character) throws +[`std::format_error`](https://en.cppreference.com/w/cpp/utility/format/format_error): - `#!cpp "{}"` serializes the value the same way as [`dump()`](dump.md) (compact, no whitespace). -- `#!cpp "{:#}"` serializes the value the same way as `#!cpp dump(4)` (pretty-printed with an indent of 4). +- `#!cpp "{:#}"` ("alternate form") serializes the value the same way as `#!cpp dump(4)` (pretty-printed + with an indent of 4). +- A width, with or without `#!cpp "#"` (e.g. `#!cpp "{:2}"` or `#!cpp "{:#2}"`), serializes the value the + same way as `#!cpp dump(width)` — a width on its own implies pretty-printing, since an indent size has + no meaning for compact output. +- `fill-and-align` (e.g. `#!cpp "{:.>#}"` or `#!cpp "{:.>3}"`) picks a custom indent character, the same + way as `#!cpp dump(indent, indent_char)`. The alignment direction itself (`#!cpp '<'`, `#!cpp '>'`, + `#!cpp '^'`) has no separate meaning for JSON values — only the fill character before it is used, and + any of the three directions is accepted. This specialization is only available for `#!cpp char`-based JSON values and only if the standard library provides ``, controlled by the [`JSON_HAS_STD_FORMAT`](../macros/json_has_std_format.md) macro. diff --git a/docs/mkdocs/docs/examples/std_formatter.c++20.cpp b/docs/mkdocs/docs/examples/std_formatter.c++20.cpp index 811225afc..d249415d7 100644 --- a/docs/mkdocs/docs/examples/std_formatter.c++20.cpp +++ b/docs/mkdocs/docs/examples/std_formatter.c++20.cpp @@ -12,5 +12,11 @@ int main() std::cout << std::format("{}", j) << "\n\n"; // pretty-printed formatting, like dump(4) - std::cout << std::format("{:#}", j) << std::endl; + std::cout << std::format("{:#}", j) << "\n\n"; + + // a width sets the indent, like dump(2) + std::cout << std::format("{:2}", j) << "\n\n"; + + // fill-and-align sets the indent character, like dump(4, '.') + std::cout << std::format("{:.>#}", j) << std::endl; } diff --git a/docs/mkdocs/docs/examples/std_formatter.c++20.output b/docs/mkdocs/docs/examples/std_formatter.c++20.output index 75db501c9..679c8be00 100644 --- a/docs/mkdocs/docs/examples/std_formatter.c++20.output +++ b/docs/mkdocs/docs/examples/std_formatter.c++20.output @@ -4,3 +4,13 @@ "one": 1, "two": 2 } + +{ + "one": 1, + "two": 2 +} + +{ +...."one": 1, +...."two": 2 +} diff --git a/docs/mkdocs/docs/home/faq.md b/docs/mkdocs/docs/home/faq.md index 739ce9330..4af6fc0fa 100644 --- a/docs/mkdocs/docs/home/faq.md +++ b/docs/mkdocs/docs/home/faq.md @@ -181,13 +181,14 @@ See [this section](../features/types/number_handling.md#number-serialization) on `std::format` works out of the box since version 3.12.x, as long as the standard library provides `` (see [`JSON_HAS_STD_FORMAT`](../api/macros/json_has_std_format.md)); see [`std::formatter`](../api/basic_json/std_formatter.md) for details, including the `#!cpp "{:#}"` -pretty-print spec. +pretty-print spec, indent widths (`#!cpp "{:2}"`), and custom indent characters (`#!cpp "{:.>#}"`). For `fmt`, the library ships [`format_as`](../api/basic_json/format_as.md), a small customization point `fmt` looks for via argument-dependent lookup. It only has an effect on fmt 10.0.0 through 11.0.2 — from fmt 11.1.0 onwards, `fmt` no longer picks up a `format_as` overload that returns a `std::string`. On such -versions (or any version, if you also want `#!cpp "{:#}"` pretty-print support), define your own -`fmt::formatter` specialization; see [`format_as`](../api/basic_json/format_as.md) for a two-line recipe. +versions (or any version, if you also want the same `#!cpp "{:#}"`/width/fill-and-align spec support that +`std::formatter` has), define your own `fmt::formatter` specialization; see +[`format_as`](../api/basic_json/format_as.md) for a recipe that mirrors it. If you get ambiguous-overload errors when passing a JSON value to `fmt::format`/`fmt::print` without any `fmt::formatter` specialization in scope, that's `fmt` picking up `basic_json`'s implicit diff --git a/include/nlohmann/json.hpp b/include/nlohmann/json.hpp index 73cd46545..6a34898d7 100644 --- a/include/nlohmann/json.hpp +++ b/include/nlohmann/json.hpp @@ -5382,27 +5382,75 @@ inline void swap(nlohmann::NLOHMANN_BASIC_JSON_TPL& j1, nlohmann::NLOHMANN_BASIC NLOHMANN_BASIC_JSON_TPL_DECLARATION struct formatter // NOLINT(cert-dcl58-cpp) { - bool pretty = false; + // -1 means compact output (dump()); any value >= 0 means pretty-printed + // output with that many spaces (or indent_char) per level (dump(indent, indent_char)). + int indent = -1; + char indent_char = ' '; constexpr auto parse(format_parse_context& ctx) -> format_parse_context::iterator { auto it = ctx.begin(); - if (it != ctx.end() && *it == '#') + const auto end = ctx.end(); + constexpr auto is_align = [](char c) + { + return c == '<' || c == '>' || c == '^'; + }; + + // [[fill] align] - repurposed here to pick a custom indent character, + // e.g. "{:.>#4}" pretty-prints with '.' as the indent character + if (it != end && it + 1 != end && is_align(it[1])) + { + indent_char = *it; + it += 2; + } + else if (it != end && is_align(*it)) + { + ++it; + } + + // ['#'] - "alternate form", used here to request pretty-printing + bool pretty = false; + if (it != end && *it == '#') { pretty = true; ++it; } - if (it != ctx.end() && *it != '}') + + // [width] - repurposed here to pick the indent size for pretty-printing, + // e.g. "{:2}" or "{:#2}" pretty-print with an indent of 2; a width without + // '#' implies pretty-printing since an indent otherwise has no meaning + if (it != end && *it >= '1' && *it <= '9') + { + indent = 0; + while (it != end && *it >= '0' && *it <= '9') + { + indent = (indent * 10) + (*it - '0'); + ++it; + } + } + else if (pretty) + { + indent = 4; + } + + // sign, the '0' flag, precision, locale-specific formatting ('L'), dynamic + // width/precision ("{...}"), and type characters all have no meaning for + // JSON values; none of them are consumed above, so they all end up rejected + // by this single check along with any other unrecognized trailing spec. + if (it != end && *it != '}') { JSON_THROW(format_error("invalid format args for nlohmann::json")); } + return it; } template auto format(const nlohmann::NLOHMANN_BASIC_JSON_TPL& j, FormatContext& ctx) const -> decltype(ctx.out()) { - const auto dumped = pretty ? j.dump(4) : j.dump(); + // dump()'s own default (indent = -1) already means compact output, so this + // covers both the compact and pretty-printed cases without a branch. + const auto dumped = j.dump(indent, indent_char); return std::copy(dumped.begin(), dumped.end(), ctx.out()); } }; diff --git a/single_include/nlohmann/json.hpp b/single_include/nlohmann/json.hpp index b0ded13bc..544d8ddd5 100644 --- a/single_include/nlohmann/json.hpp +++ b/single_include/nlohmann/json.hpp @@ -25908,27 +25908,75 @@ inline void swap(nlohmann::NLOHMANN_BASIC_JSON_TPL& j1, nlohmann::NLOHMANN_BASIC NLOHMANN_BASIC_JSON_TPL_DECLARATION struct formatter // NOLINT(cert-dcl58-cpp) { - bool pretty = false; + // -1 means compact output (dump()); any value >= 0 means pretty-printed + // output with that many spaces (or indent_char) per level (dump(indent, indent_char)). + int indent = -1; + char indent_char = ' '; constexpr auto parse(format_parse_context& ctx) -> format_parse_context::iterator { auto it = ctx.begin(); - if (it != ctx.end() && *it == '#') + const auto end = ctx.end(); + constexpr auto is_align = [](char c) + { + return c == '<' || c == '>' || c == '^'; + }; + + // [[fill] align] - repurposed here to pick a custom indent character, + // e.g. "{:.>#4}" pretty-prints with '.' as the indent character + if (it != end && it + 1 != end && is_align(it[1])) + { + indent_char = *it; + it += 2; + } + else if (it != end && is_align(*it)) + { + ++it; + } + + // ['#'] - "alternate form", used here to request pretty-printing + bool pretty = false; + if (it != end && *it == '#') { pretty = true; ++it; } - if (it != ctx.end() && *it != '}') + + // [width] - repurposed here to pick the indent size for pretty-printing, + // e.g. "{:2}" or "{:#2}" pretty-print with an indent of 2; a width without + // '#' implies pretty-printing since an indent otherwise has no meaning + if (it != end && *it >= '1' && *it <= '9') + { + indent = 0; + while (it != end && *it >= '0' && *it <= '9') + { + indent = (indent * 10) + (*it - '0'); + ++it; + } + } + else if (pretty) + { + indent = 4; + } + + // sign, the '0' flag, precision, locale-specific formatting ('L'), dynamic + // width/precision ("{...}"), and type characters all have no meaning for + // JSON values; none of them are consumed above, so they all end up rejected + // by this single check along with any other unrecognized trailing spec. + if (it != end && *it != '}') { JSON_THROW(format_error("invalid format args for nlohmann::json")); } + return it; } template auto format(const nlohmann::NLOHMANN_BASIC_JSON_TPL& j, FormatContext& ctx) const -> decltype(ctx.out()) { - const auto dumped = pretty ? j.dump(4) : j.dump(); + // dump()'s own default (indent = -1) already means compact output, so this + // covers both the compact and pretty-printed cases without a branch. + const auto dumped = j.dump(indent, indent_char); return std::copy(dumped.begin(), dumped.end(), ctx.out()); } }; diff --git a/tests/CMakeLists.txt b/tests/CMakeLists.txt index 41301ab67..027881095 100644 --- a/tests/CMakeLists.txt +++ b/tests/CMakeLists.txt @@ -195,3 +195,4 @@ add_subdirectory(cmake_add_subdirectory) add_subdirectory(cmake_fetch_content) add_subdirectory(cmake_fetch_content2) add_subdirectory(cmake_target_include_directories) +add_subdirectory(fmt_formatter) diff --git a/tests/fmt_formatter/CMakeLists.txt b/tests/fmt_formatter/CMakeLists.txt new file mode 100644 index 000000000..2d7509cd0 --- /dev/null +++ b/tests/fmt_formatter/CMakeLists.txt @@ -0,0 +1,20 @@ +if (${CMAKE_VERSION} VERSION_GREATER "3.14.0") + add_test(NAME fmt_formatter_configure + COMMAND ${CMAKE_COMMAND} + -G "${CMAKE_GENERATOR}" + -DCMAKE_CXX_COMPILER=${CMAKE_CXX_COMPILER} + -DCMAKE_CXX_FLAGS=${CMAKE_CXX_FLAGS} + ${CMAKE_CURRENT_SOURCE_DIR}/project + ) + add_test(NAME fmt_formatter_build + COMMAND ${CMAKE_COMMAND} --build . + ) + set_tests_properties(fmt_formatter_configure PROPERTIES + FIXTURES_SETUP fmt_formatter + LABELS "git_required;not_reproducible" + ) + set_tests_properties(fmt_formatter_build PROPERTIES + FIXTURES_REQUIRED fmt_formatter + LABELS "git_required;not_reproducible" + ) +endif() diff --git a/tests/fmt_formatter/project/CMakeLists.txt b/tests/fmt_formatter/project/CMakeLists.txt new file mode 100644 index 000000000..01a36f275 --- /dev/null +++ b/tests/fmt_formatter/project/CMakeLists.txt @@ -0,0 +1,36 @@ +cmake_minimum_required(VERSION 3.14) + +project(FmtFormatterTest CXX) + +include(FetchContent) + +get_filename_component(GIT_REPOSITORY_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/../../.. ABSOLUTE) +FetchContent_Declare(json GIT_REPOSITORY ${GIT_REPOSITORY_DIRECTORY} GIT_TAG HEAD) + +set(FMT_TEST OFF CACHE BOOL "" FORCE) +set(FMT_DOC OFF CACHE BOOL "" FORCE) +set(FMT_INSTALL OFF CACHE BOOL "" FORCE) +FetchContent_Declare(fmt + GIT_REPOSITORY https://github.com/fmtlib/fmt.git + GIT_TAG 12.2.0 + GIT_SHALLOW TRUE +) + +FetchContent_MakeAvailable(json fmt) + +if(MSVC) + add_compile_options(/EHsc) +endif() + +add_executable(fmt_formatter_test main.cpp) +target_link_libraries(fmt_formatter_test PRIVATE nlohmann_json::nlohmann_json fmt::fmt) +target_compile_features(fmt_formatter_test PRIVATE cxx_std_17) + +# Fail the build itself (and therefore the ctest "build" step that drives it) if the +# recipe's runtime assertions don't hold -- there is no separate "run" step, since the +# executable's location varies by platform/generator, but CMake resolves a target name +# passed to a custom command's COMMAND for us. +add_custom_command(TARGET fmt_formatter_test POST_BUILD + COMMAND fmt_formatter_test + COMMENT "Running fmt::formatter recipe test" +) diff --git a/tests/fmt_formatter/project/main.cpp b/tests/fmt_formatter/project/main.cpp new file mode 100644 index 000000000..c0cecdc23 --- /dev/null +++ b/tests/fmt_formatter/project/main.cpp @@ -0,0 +1,98 @@ +#include +#include +#include + +// A fmt::formatter specialization mirroring std::formatter +// (see docs/mkdocs/docs/api/basic_json/std_formatter.md), for use with fmt versions that +// no longer pick up format_as() (fmt >= 11.1.0), or to get the same "{:#}"/width/ +// fill-and-align spec support with any fmt version. +// --8<-- [start:formatter_recipe] +template <> +struct fmt::formatter +{ + // -1 means compact output (dump()); any value >= 0 means pretty-printed + // output with that many spaces (or indent_char) per level. + int indent = -1; + char indent_char = ' '; + + constexpr auto parse(format_parse_context& ctx) -> format_parse_context::iterator + { + auto it = ctx.begin(); + const auto end = ctx.end(); + constexpr auto is_align = [](char c) + { + return c == '<' || c == '>' || c == '^'; + }; + + // [[fill] align] - repurposed here to pick a custom indent character + if (it != end && it + 1 != end && is_align(it[1])) + { + indent_char = *it; + it += 2; + } + else if (it != end && is_align(*it)) + { + ++it; + } + + // ['#'] - "alternate form", used here to request pretty-printing + bool pretty = false; + if (it != end && *it == '#') + { + pretty = true; + ++it; + } + + // [width] - repurposed here to pick the indent size; a width without '#' + // implies pretty-printing since an indent otherwise has no meaning + if (it != end && *it >= '1' && *it <= '9') + { + indent = 0; + while (it != end && *it >= '0' && *it <= '9') + { + indent = (indent * 10) + (*it - '0'); + ++it; + } + } + else if (pretty) + { + indent = 4; + } + + if (it != end && *it != '}') + { + throw fmt::format_error("invalid format args for nlohmann::json"); + } + + return it; + } + + auto format(const nlohmann::json& j, format_context& ctx) const + { + const auto dumped = j.dump(indent, indent_char); + return fmt::format_to(ctx.out(), "{}", dumped); + } +}; +// --8<-- [end:formatter_recipe] + +int main() +{ + const nlohmann::json j = {{"foo", 1}, {"bar", {1, 2, 3}}}; + + assert(fmt::format("{}", j) == j.dump()); + assert(fmt::format("{:#}", j) == j.dump(4)); + assert(fmt::format("{:2}", j) == j.dump(2)); + assert(fmt::format("{:#2}", j) == j.dump(2)); + assert(fmt::format("{:.>#}", j) == j.dump(4, '.')); + + bool threw = false; + try + { + (void)fmt::vformat("{:x}", fmt::make_format_args(j)); + } + catch (const fmt::format_error&) + { + threw = true; + } + assert(threw); +} diff --git a/tests/src/unit-std-format.cpp b/tests/src/unit-std-format.cpp index 334f0b0a2..f7a364884 100644 --- a/tests/src/unit-std-format.cpp +++ b/tests/src/unit-std-format.cpp @@ -46,7 +46,27 @@ TEST_CASE("std::formatter") CHECK(std::format("{:#}", json::array()) == json::array().dump(4)); } - SECTION("format args other than an empty spec or '#' are rejected") + SECTION("a width sets the indent, like dump(width), with or without '#'") + { + const json j = {{"foo", 1}, {"bar", {1, 2, 3}}}; + CHECK(std::format("{:2}", j) == j.dump(2)); + CHECK(std::format("{:#2}", j) == j.dump(2)); + CHECK(std::format("{:8}", j) == j.dump(8)); + } + + SECTION("fill-and-align sets the indent character, like dump(indent, indent_char)") + { + const json j = {{"foo", 1}, {"bar", {1, 2, 3}}}; + CHECK(std::format("{:.>#}", j) == j.dump(4, '.')); + CHECK(std::format("{:.>#3}", j) == j.dump(3, '.')); + CHECK(std::format("{:.>3}", j) == j.dump(3, '.')); + // the alignment direction itself ('<', '>', '^') has no separate meaning for + // JSON values -- only the fill character before it is used as the indent character + CHECK(std::format("{:.<3}", j) == j.dump(3, '.')); + CHECK(std::format("{:.^3}", j) == j.dump(3, '.')); + } + + SECTION("format args with no meaning for JSON values are rejected") { // std::vformat parses the format string at runtime (unlike std::format, whose // format_string type is checked at compile time), so it lets us verify that an @@ -54,7 +74,14 @@ TEST_CASE("std::formatter") // format string. const json j = 42; CHECK_THROWS_AS(std::vformat("{:x}", std::make_format_args(j)), std::format_error); - CHECK_THROWS_AS(std::vformat("{:10}", std::make_format_args(j)), std::format_error); + CHECK_THROWS_AS(std::vformat("{:+}", std::make_format_args(j)), std::format_error); // sign + CHECK_THROWS_AS(std::vformat("{:-}", std::make_format_args(j)), std::format_error); // sign + CHECK_THROWS_AS(std::vformat("{: }", std::make_format_args(j)), std::format_error); // sign + CHECK_THROWS_AS(std::vformat("{:04}", std::make_format_args(j)), std::format_error); // '0' flag + CHECK_THROWS_AS(std::vformat("{:.2}", std::make_format_args(j)), std::format_error); // precision + CHECK_THROWS_AS(std::vformat("{:L}", std::make_format_args(j)), std::format_error); // locale + const int dynamic_width = 4; + CHECK_THROWS_AS(std::vformat("{:{}}", std::make_format_args(j, dynamic_width)), std::format_error); // dynamic width } SECTION("std::format_to writes through an arbitrary output iterator")