Skip to content

Commit a6616a0

Browse files
the follow-ups of #866 and #867: a bare partial requirement is a caret; the TOML writer escapes every control character
#866: a bare requirement is a caret, so "0" and "0.0" take the wildcard bounds as well (<1.0.0, <0.1.0); a unit test pins bare against caret, docs/05 states it in both languages. #867: with \b, \f and \uXXXX read, a value may hold any control character; escape_string escapes U+0000-U+001F and U+007F (short forms where TOML has one, \uXXXX elsewhere, never the reader's \0), so serialize writes TOML. A round trip test covers every control character. Design 2026-10-30 part 2 §17. Co-authored-by: speak-agent <248744407+speak-agent@users.noreply.github.com>
1 parent 26db6a4 commit a6616a0

6 files changed

Lines changed: 78 additions & 2 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,15 @@
2828
true`) made `-p` of each write its own key and hash. The key is the
2929
workspace's spelling: its `[dependencies]`, `[workspace.dependencies]`, then
3030
the members in the order `members` lists them (docs/07, e2e 990).
31+
- **A partial caret or tilde requirement treats unwritten segments as
32+
wildcards** (#866, NopeCharon): `^0` is `< 1.0.0`, `^0.0` is `< 0.1.0`, `~1` is
33+
`< 2.0.0`. A bare requirement is a caret, so the bare partial spellings `"0"`
34+
and `"0.0"` take the same bounds; before, they matched 0.0.0 alone (docs/05).
35+
- **The TOML reader accepts every escape TOML 1.0 defines** (#867, NopeCharon):
36+
`\b`, `\f`, `\uXXXX` and `\UXXXXXXXX`. The writer escapes every control
37+
character in turn (`\uXXXX` where TOML has no short form), so a normalised
38+
manifest that holds one is still TOML; `\0` is this reader's extension and is
39+
never written.
3140

3241
## [2026.10.30.1] - 2026-10-30
3342

‎docs/05-dependencies.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -121,6 +121,13 @@ baz = "=1.2.3" # Exact match
121121
qux = ">=1.0, <2.0" # Range combination
122122
```
123123

124+
A bare requirement is a caret: `foo = "1.2.3"` is `^1.2.3`, except that a bare
125+
version equal to a published key addresses that key exactly. A bare partial
126+
spelling follows the caret's wildcard rule as well: `"0"` is `>= 0.0.0, < 1.0.0`
127+
and `"0.0"` is `>= 0.0.0, < 0.1.0` (before 2026.10.31.1 both matched 0.0.0
128+
alone). The dependency conflict check and the address check of `--locked` read
129+
requirements the same way.
130+
124131
### `visibility` — whether a dependency's usage crosses this package's own boundary
125132

126133
```toml

‎docs/zh/05-dependencies.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -111,6 +111,10 @@ baz = "=1.2.3" # Exact match
111111
qux = ">=1.0, <2.0" # Range combination
112112
```
113113

114+
不带运算符的要求即 caret:`foo = "1.2.3"` 等于 `^1.2.3`;唯一的例外是不带运算符的版本恰为已发布的键时,它精确地指向该键。
115+
不带运算符的部分写法同样按 caret 的通配规则:`"0"` 为 `>= 0.0.0, < 1.0.0`,`"0.0"` 为 `>= 0.0.0, < 0.1.0`(2026.10.31.1 之前
116+
两者都只匹配 0.0.0)。依赖冲突检查与 `--locked` 的地址核对以同样的方式读取要求。
117+
114118
### `visibility` —— 一个依赖的用法是否跨越本包自己的边界
115119

116120
```toml

‎modules/libs/src/toml.cppm‎

Lines changed: 14 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -841,16 +841,28 @@ std::string serialize(const Document& doc) {
841841
return w.out;
842842
}
843843

844+
// A basic string TOML 1.0 reads back as `raw`. Every control character
845+
// (U+0000-U+001F, U+007F) is escaped, since TOML forbids them unescaped in a
846+
// basic string: the reader accepts `\b`, `\f` and `\uXXXX` (#867), so a value
847+
// may hold one, and `serialize` (the normalised manifest of `mcpp publish`)
848+
// would otherwise write a document no TOML reader accepts. The short forms are
849+
// used where TOML has one, `\uXXXX` elsewhere; `\0`, which this reader also
850+
// accepts, is not TOML 1.0 and is never written.
844851
std::string escape_string(std::string_view raw) {
845852
std::string out = "\"";
846853
for (char c : raw) {
854+
const auto u = static_cast<unsigned char>(c);
847855
switch (c) {
848856
case '"': out += "\\\""; break;
849857
case '\\': out += "\\\\"; break;
850-
case '\n': out += "\\n"; break;
858+
case '\b': out += "\\b"; break;
851859
case '\t': out += "\\t"; break;
860+
case '\n': out += "\\n"; break;
861+
case '\f': out += "\\f"; break;
852862
case '\r': out += "\\r"; break;
853-
default: out.push_back(c);
863+
default:
864+
if (u < 0x20 || u == 0x7F) out += std::format("\\u{:04X}", static_cast<unsigned>(u));
865+
else out.push_back(c);
854866
}
855867
}
856868
out += '"';

‎tests/unit/test_toml_serialize.cpp‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -125,6 +125,32 @@ version = "0.1.0"
125125
)", "implicit container");
126126
}
127127

128+
// The reader accepts every TOML 1.0 escape (#867), so a value may hold any
129+
// control character; the writer escapes each one, so the text it produces is
130+
// TOML and reads back as the same value. `\0` is this reader's extension and
131+
// not TOML 1.0, so it is written as `\u0000`.
132+
TEST(TomlSerialize, ControlCharactersAreEscaped) {
133+
expect_round_trip(R"(
134+
[package]
135+
name = "p"
136+
version = "0.1.0"
137+
description = "b\b f\f t\t n\n r\r e\u001B d\u007F z\u0000 nul\0 ué"
138+
)", "control characters");
139+
140+
std::string all;
141+
for (int c = 0; c < 0x20; ++c) all.push_back(static_cast<char>(c));
142+
all.push_back('\x7F');
143+
const auto text = t::escape_string(all);
144+
for (char c : text) {
145+
const auto u = static_cast<unsigned char>(c);
146+
EXPECT_FALSE(u < 0x20 || u == 0x7F) << "an unescaped control character in " << text;
147+
}
148+
EXPECT_EQ(text.find("\\0"), std::string::npos) << "\\0 is not TOML 1.0: " << text;
149+
auto back = t::parse("v = " + text + "\n");
150+
ASSERT_TRUE(back.has_value()) << back.error().message << "\n" << text;
151+
EXPECT_EQ(back->root().at("v").as_string(), all);
152+
}
153+
128154
TEST(TomlSerialize, RepositoryManifestsRoundTrip) {
129155
// Every manifest in the repository's examples, and the project's own. The
130156
// repository is located from this file's own path rather than from the

‎tests/unit/test_version_req.cpp‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -96,6 +96,24 @@ TEST(VersionReq, PartialCaretBoundsFollowTheWrittenSegments) {
9696
EXPECT_FALSE(matches(*zeroFive, *parse_version("0.6.0")));
9797
}
9898

99+
// A bare requirement is a caret (#866's follow-up), so a bare partial spelling
100+
// takes the same wildcard bounds: "0" is <1.0.0 and "0.0" is <0.1.0, where
101+
// before #866 both matched 0.0.0 alone.
102+
TEST(VersionReq, BarePartialRequirementsAreCarets) {
103+
for (auto [bare, caret] : {std::pair{"0", "^0"}, std::pair{"0.0", "^0.0"},
104+
std::pair{"1", "^1"}, std::pair{"1.2", "^1.2"}}) {
105+
auto b = parse_req(bare); ASSERT_TRUE(b) << bare;
106+
auto c = parse_req(caret); ASSERT_TRUE(c) << caret;
107+
for (auto v : {"0.0.0", "0.0.7", "0.1.0", "0.9.3", "1.0.0", "1.2.0", "1.2.9", "1.3.0", "2.0.0"})
108+
EXPECT_EQ(matches(*b, *parse_version(v)), matches(*c, *parse_version(v)))
109+
<< bare << " against " << v;
110+
}
111+
EXPECT_TRUE (matches(*parse_req("0"), *parse_version("0.9.3")));
112+
EXPECT_FALSE(matches(*parse_req("0"), *parse_version("1.0.0")));
113+
EXPECT_TRUE (matches(*parse_req("0.0"), *parse_version("0.0.7")));
114+
EXPECT_FALSE(matches(*parse_req("0.0"), *parse_version("0.1.0")));
115+
}
116+
99117
TEST(VersionReq, PartialTildeWithOnlyAMajorHoldsTheMajor) {
100118
auto r = parse_req("~1"); ASSERT_TRUE(r);
101119
EXPECT_TRUE (matches(*r, *parse_version("1.0.0")));

0 commit comments

Comments
 (0)