♻️ reorganize PR

Signed-off-by: Niels Lohmann <mail@nlohmann.me>

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<basic_json>`](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<basic_json>`](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<nlohmann::json> : fmt::formatter<std::string>
-    {
-        auto format(const nlohmann::json& j, format_context& ctx) const
-        {
-            return fmt::formatter<std::string>::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<basic_json>` and verified to actually work, not just illustrative.
+
 ## Examples
 
 ??? example

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 `<format>` 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 `<format>`, controlled by the [`JSON_HAS_STD_FORMAT`](../macros/json_has_std_format.md) macro.

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;
 }

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
+}

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
 `<format>` (see [`JSON_HAS_STD_FORMAT`](../api/macros/json_has_std_format.md)); see
 [`std::formatter<basic_json>`](../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<basic_json>` 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<json>` specialization in scope, that's `fmt` picking up `basic_json`'s implicit

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<nlohmann::NLOHMANN_BASIC_JSON_TPL, char> // 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<typename FormatContext>
     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());
     }
 };

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<nlohmann::NLOHMANN_BASIC_JSON_TPL, char> // 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<typename FormatContext>
     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());
     }
 };

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)

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()

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<nlohmann::json> recipe test"
+)

tests/fmt_formatter/project/main.cpp

@@ -0,0 +1,98 @@
+#include <cassert>
+#include <fmt/format.h>
+#include <nlohmann/json.hpp>
+
+// A fmt::formatter<nlohmann::json> specialization mirroring std::formatter<basic_json>
+// (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<nlohmann::json>
+{
+    // -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);
+}

tests/src/unit-std-format.cpp

@@ -46,7 +46,27 @@ TEST_CASE("std::formatter<nlohmann::json>")
         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<nlohmann::json>")
         // 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")