Commit 3c46da14db296beec186c3df4fe3669f6c99b715 | zig

doc/langref.html.in+17-36

 @@ -7274,46 +7274,27 @@ fn readU32Be() u32 {}
       </ul>
       {#header_close#}
       {#header_close#}
       {#header_open|Source Encoding#}
-      <p>Zig source code is encoded in UTF-8. An invalid UTF-8 byte sequence results in a compile error.</p>
+      <p>Zig source code is UTF-8 encoded. Invalid UTF-8 byte sequences are not allowed anywhere.</p>
-      <p>Throughout all zig source code (including in comments), some code points are never allowed:</p>
+      <p>Some code points are never allowed, even in {#link|Comments#}:</p>
       <ul>
-        <li>Ascii control characters, except for U+000a (LF), U+000d (CR), and U+0009 (HT): U+0000 - U+0008, U+000b - U+000c, U+000e - U+0001f, U+007f.</li>
+        <li>ASCII control characters, except for U+000a (LF): U+0000...U+0009, U+000b...U+0001f, U+007f.</li>
-        <li>Non-Ascii Unicode line endings: U+0085 (NEL), U+2028 (LS), U+2029 (PS).</li>
+        <li>Non-ASCII Unicode line endings: U+0085 (NEL), U+2028 (LS), U+2029 (PS).</li>
+        <li>Byte order marks: U+FEFF (BOM).</li>
       </ul>
       <p>
-      LF (byte value 0x0a, code point U+000a, {#syntax#}'\n'{#endsyntax#}) is the line terminator in Zig source code.
+      LF (byte value 0x0a, code point U+000a, {#syntax#}'\n'{#endsyntax#}) is
-      This byte value terminates every line of zig source code except the last line of the file.
+      the line terminator in Zig source code. This byte value terminates every
-      It is recommended that non-empty source files end with an empty line, which means the last byte would be 0x0a (LF).
+      line of Zig source code, including last line of the file.
       </p>
-      <p>
+      <p>These conservative rules mean that third party tools reading
-      Each LF may be immediately preceded by a single CR (byte value 0x0d, code point U+000d, {#syntax#}'\r'{#endsyntax#})
+      already-validated Zig source code may make simplifying assumptions, such
-      to form a Windows style line ending, but this is discouraged. Note that in multiline strings, CRLF sequences will
+      as naively separating lines based on {#syntax#}'\n'{#endsyntax#}.
-      be encoded as LF when compiled into a zig program.
+      However, tooling such as <kbd>zig fmt</kbd> provides convenience
-      A CR in any other context is not allowed.
+      functionality to convert invalid source encodings to valid source
-      </p>
+      encodings, for instance by stripping byte order marks and carriage
-      <p>
+      returns.</p>
-      HT hard tabs (byte value 0x09, code point U+0009, {#syntax#}'\t'{#endsyntax#}) are interchangeable with
-      SP spaces (byte value 0x20, code point U+0020, {#syntax#}' '{#endsyntax#}) as a token separator,
-      but use of hard tabs is discouraged. See {#link|Grammar#}.
-      </p>
-      <p>
-      For compatibility with other tools, the compiler ignores a UTF-8-encoded byte order mark (U+FEFF)
-      if it is the first Unicode code point in the source text. A byte order mark is not allowed anywhere else in the source.
-      </p>
-      <p>
-      Note that running <kbd>zig fmt</kbd> on a source file will implement all recommendations mentioned here.
-      </p>
-      <p>
-      Note that a tool reading Zig source code can make assumptions if the source code is assumed to be correct Zig code.
-      For example, when identifying the ends of lines, a tool can use a naive search such as <code>/\n/</code>,
-      or an <a href="https://msdn.microsoft.com/en-us/library/dd409797.aspx">advanced</a>
-      search such as <code>/\r\n?|[\n\u0085\u2028\u2029]/</code>, and in either case line endings will be correctly identified.
-      For another example, when identifying the whitespace before the first token on a line,
-      a tool can either use a naive search such as <code>/[ \t]/</code>,
-      or an <a href="https://tc39.es/ecma262/#sec-characterclassescape">advanced</a> search such as <code>/\s/</code>,
-      and in either case whitespace will be correctly identified.
-      </p>
       {#header_close#}
       {#header_open|Keyword Reference#}

lib/compiler/Maker.zig+26-20

 @@ -292,9 +292,7 @@ pub fn main(init: process.Init.Minimal) !void {
                 try cached_passthru_configure.append(arena, @intCast(configure_argv.items.len));
                 configure_argv.appendAssumeCapacity(arg);
             } else if (mem.eql(u8, arg, "--color")) {
-                const next_arg = nextArgOrFatal(args, &arg_i);
+                color = nextEnumArg(args, &arg_i, Color);
-                color = stringToEnum(Color, next_arg) orelse
-                    fatalWithHint("expected [auto|on|off] found {q}", .{next_arg});
                 try cached_passthru_configure.append(arena, @intCast(configure_argv.items.len));
                 configure_argv.appendAssumeCapacity(try arena.print("--color={t}", .{color}));
 @@ -401,25 +399,11 @@ pub fn main(init: process.Init.Minimal) !void {
             } else if (mem.eql(u8, arg, "--libc")) {
                 graph.libc_file = nextArgOrFatal(args, &arg_i);
             } else if (mem.eql(u8, arg, "--error-style")) {
-                const next_arg = nextArg(args, &arg_i) orelse
+                error_style = nextEnumArg(args, &arg_i, ErrorStyle);
-                    fatalWithHint("expected style after {q}", .{arg});
-                error_style = stringToEnum(ErrorStyle, next_arg) orelse {
-                    fatalWithHint("expected style after {q}, found {q}", .{ arg, next_arg });
-                };
             } else if (mem.eql(u8, arg, "--multiline-errors")) {
-                const next_arg = nextArg(args, &arg_i) orelse
+                multiline_errors = nextEnumArg(args, &arg_i, MultilineErrors);
-                    fatalWithHint("expected style after {q}", .{arg});
-                multiline_errors = stringToEnum(MultilineErrors, next_arg) orelse {
-                    fatalWithHint("expected style after {q}, found {q}", .{ arg, next_arg });
-                };
             } else if (mem.eql(u8, arg, "--summary")) {
-                const next_arg = nextArg(args, &arg_i) orelse
+                summary = nextEnumArg(args, &arg_i, Summary);
-                    fatalWithHint("expected [all|new|failures|line|none] after {q}", .{arg});
-                summary = stringToEnum(Summary, next_arg) orelse {
-                    fatalWithHint("expected [all|new|failures|line|none] after {q}, found {q}", .{
-                        arg, next_arg,
-                    });
-                };
             } else if (mem.cutPrefix(u8, arg, "--seed=")) |rest| {
                 graph.random_seed = parseRandomSeed(rest);
             } else if (mem.eql(u8, arg, "--build-id")) {
 @@ -4053,3 +4037,25 @@ fn confPathDepToCachePath(
         .install_include => @panic("TODO"),
     };
 }
+fn fatalEnumHint(comptime E: type, arg: []const u8, param: ?[]const u8) noreturn {
+    var buf: [100]u8 = undefined;
+    var w: Io.Writer = .fixed(&buf);
+    for (@typeInfo(E).@"enum".field_names) |field_name| {
+        w.writeAll(field_name) catch unreachable;
+        w.writeByte('|') catch unreachable;
+    }
+    const buffered = w.buffered();
+    const enum_options_text = buffered[0 .. buffered.len - 1];
+    if (param) |p| {
+        fatalWithHint("expected [{s}] after {q}; found {q}", .{ enum_options_text, arg, p });
+    } else {
+        fatalWithHint("expected [{s}] after {q}", .{ enum_options_text, arg });
+    }
+}
+fn nextEnumArg(args: []const []const u8, i: *usize, comptime E: type) E {
+    const arg = args[i.* - 1];
+    const next_arg = nextArg(args, i) orelse fatalEnumHint(E, arg, null);
+    return stringToEnum(E, next_arg) orelse fatalEnumHint(E, arg, next_arg);
+}

lib/std/Io/Writer.zig+42-20

 @@ -584,36 +584,41 @@ pub fn writeAll(w: *Writer, bytes: []const u8) Error!void {
 /// required, otherwise the digit following ':' is interpreted as **width**.
 ///
 /// **specifier** supports:
-/// - `x` and `X`: numeric value in hexadecimal notation, or string in hexadecimal bytes
+/// - "x" and "X": numeric value in hexadecimal notation, or string in hexadecimal bytes
-/// - `s`:
+/// - "s":
 ///   - for pointer-to-many and C pointers of u8, print as a C-string using zero-termination
 ///   - for slices of u8, print the entire slice as a string without zero-termination
-/// - `t`:
+/// - "t":
 ///   - for enums and tagged unions: prints the tag name
 ///   - for error sets: prints the error name
-/// - `b64`: string as standard base64
+/// - "b64": string as standard base64
-/// - `e`: floating point value in scientific notation
+/// - "e": floating point value in scientific notation
-/// - `d`: numeric value in decimal notation
+/// - "d": numeric value in decimal notation
-/// - `b`: integer value in binary notation
+/// - "b": integer value in binary notation
-/// - `o`: integer value in octal notation
+/// - "o": integer value in octal notation
-/// - `c`: integer as an ASCII character. Integer type must have 8 bits at max.
+/// - "c": integer as an ASCII character. Integer type must have 8 bits at max.
-/// - `u`: integer as an UTF-8 sequence. Integer type must have 21 bits at max.
+/// - "u": integer as an UTF-8 sequence. Integer type must have 21 bits at max.
-/// - `B`: bytes in SI units (decimal)
+/// - "B": bytes in SI units (decimal)
-/// - `Bi`: bytes in IEC units (binary)
+/// - "Bi": bytes in IEC units (binary)
-/// - `?`: optional value as either the unwrapped value, or `null`; may be
+/// - "?": optional value as either the unwrapped value, or `null`; may be
 ///   followed by a format specifier for the underlying value.
-/// - `!`: error union value as either the unwrapped value, or the formatted
+/// - "!": error union value as either the unwrapped value, or the formatted
 ///   error value; may be followed by a format specifier for the underlying
 ///   value.
-/// - `*`: the address of the value instead of the value itself.
+/// - "*": the address of the value instead of the value itself.
-/// - `any`: a value of any type using its default format.
+/// - "any": a value of any type using its default format.
-/// - `f`: delegates to the `format` method of the type, passing `*Writer` and
+/// - "f": delegates to the `format` method of the type, passing `*Writer` and
 ///   expecting `Error!void` returned.
-///
+/// - "q": prints as a double-quote escaped string. Inside the double-quoted
-/// A user type may be a struct, vector, union or enum type.
+///   string, everything is passed through unmodified, except for the following
+///   transformations:
+///   - escaped: '\n', '\r', '\t', '\\', '"'
+///   - hex-encoded: ASCII control characters
+/// - "qf": delegates to the `format` method of the type, while double-quote
+///   escaping.
 ///
 /// Literal curly braces can be escaped in the format string via doubling, e.g.
-/// `{{` or `}}`.
+/// "{{" or "}}".
 pub fn print(w: *Writer, comptime fmt: []const u8, args: anytype) Error!void {
     const ArgsType = @TypeOf(args);
     const args_type_info = @typeInfo(ArgsType);
 @@ -1231,6 +1236,18 @@ pub fn printValue(
                 },
                 else => {},
             },
+            'q' => switch (fmt[1]) {
+                'f' => {
+                    try w.writeByte('"');
+                    var buffer: [64]u8 = undefined;
+                    var escaping_writer: std.zig.StringEscapeWriter = .init(w, &buffer);
+                    try value.format(&escaping_writer.writer);
+                    try escaping_writer.writer.flush();
+                    try w.writeByte('"');
+                    return;
+                },
+                else => {},
+            },
             else => {},
         },
         3 => if (fmt[0] == 'b' and fmt[1] == '6' and fmt[2] == '4') switch (@typeInfo(T)) {
 @@ -2143,6 +2160,11 @@ test "{q} format string" {
     try testing.expectFmt("hello \"i\\tlike\\\"cheese\\x00\\x05cheese\" world", "hello {q} world", .{data});
 }
+test "{qf} format string" {
+    const data: []const u8 = "😎";
+    try testing.expectFmt("hello \"@\\\"😎\\\"\" world", "hello {qf} world", .{std.zig.fmtId(data)});
+}
 fn testPrintIntCase(expected: []const u8, value: anytype, base: u8, case: std.fmt.Case, options: std.fmt.Options) !void {
     var buffer: [100]u8 = undefined;
     var w: Writer = .fixed(&buffer);

lib/std/zig.zig+69-7

...	@@ -538,21 +538,83 @@ test fmtChar {	...	@@ -538,21 +538,83 @@ test fmtChar {
538	}	538	}
539		539
540	/// Print the string as escaped contents of a double quoted string.	540	/// Print the string as escaped contents of a double quoted string.
		541	///
		542	/// The following transformations are made:
		543	/// * escaped: '\n', '\r', '\t', '\\', '"'
		544	/// * hex-encoded: ascii control characters
		545	///
		546	/// Everything else is passed through unmodified.
541	pub fn stringEscape(bytes: []const u8, w: *Writer) Writer.Error!void {	547	pub fn stringEscape(bytes: []const u8, w: *Writer) Writer.Error!void {
		548	_ = try stringEscapeCounting(bytes, w);
		549	}
		550
		551	pub fn stringEscapeCounting(bytes: []const u8, w: *Writer) Writer.Error!usize {
		552	var n: usize = 0;
542	for (bytes) \|byte\| switch (byte) {	553	for (bytes) \|byte\| switch (byte) {
543	'\n' => try w.writeAll("\\n"),	554	'\t' => {
544	'\r' => try w.writeAll("\\r"),	555	try w.writeAll("\\t");
545	'\t' => try w.writeAll("\\t"),	556	n += 2;
546	'\\' => try w.writeAll("\\\\"),	557	},
547	'"' => try w.writeAll("\\\""),	558	'\n' => {
548	' ', '!', '#'...'[', ']'...'~' => try w.writeByte(byte),	559	try w.writeAll("\\n");
549	else => {	560	n += 2;
		561	},
		562	'\r' => {
		563	try w.writeAll("\\r");
		564	n += 2;
		565	},
		566	'\\' => {
		567	try w.writeAll("\\\\");
		568	n += 2;
		569	},
		570	'"' => {
		571	try w.writeAll("\\\"");
		572	n += 2;
		573	},
		574	0...8, 11, 12, 14...0x1f, 0x7f => {
550	try w.writeAll("\\x");	575	try w.writeAll("\\x");
551	try w.printInt(byte, 16, .lower, .{ .width = 2, .fill = '0' });	576	try w.printInt(byte, 16, .lower, .{ .width = 2, .fill = '0' });
		577	n += 4;
		578	},
		579	else => {
		580	try w.writeByte(byte);
		581	n += 1;
552	},	582	},
553	};	583	};
		584	return n;
554	}	585	}
555		586
		587	pub const StringEscapeWriter = struct {
		588	out: *Writer,
		589	writer: Writer,
		590
		591	pub fn init(out: *Writer, buffer: []u8) @This() {
		592	return .{
		593	.out = out,
		594	.writer = .{
		595	.vtable = &.{ .drain = @This().drain },
		596	.buffer = buffer,
		597	},
		598	};
		599	}
		600
		601	fn drain(w: *Writer, data: []const []const u8, splat: usize) Io.Writer.Error!usize {
		602	const sew: *StringEscapeWriter = @alignCast(@fieldParentPtr("writer", w));
		603	const out = sew.out;
		604	_ = try stringEscapeCounting(w.buffered(), out);
		605	w.end = 0;
		606	var n: usize = 0;
		607	for (data[0 .. data.len - 1]) \|bytes\| {
		608	n += try stringEscapeCounting(bytes, out);
		609	}
		610	const pattern = data[data.len - 1];
		611	for (0..splat) \|_\| {
		612	n += try stringEscapeCounting(pattern, out);
		613	}
		614	return n;
		615	}
		616	};
		617
556	/// Print as escaped contents of a single-quoted string.	618	/// Print as escaped contents of a single-quoted string.
557	pub fn charEscape(codepoint: u21, w: *Writer) Writer.Error!void {	619	pub fn charEscape(codepoint: u21, w: *Writer) Writer.Error!void {
558	switch (codepoint) {	620	switch (codepoint) {

lib/std/zig/parser_generated_oracle.zig+5-5

...	@@ -3073,7 +3073,7 @@ const Parser = struct {	...	@@ -3073,7 +3073,7 @@ const Parser = struct {
3073	return blk_0: {	3073	return blk_0: {
3074	const pos_0 = p.i;	3074	const pos_0 = p.i;
3075	if (blk_1: {	3075	if (blk_1: {
3076	if (std.mem.startsWith(u8, p.source[p.i..], "\xef\xbb\xbf")) {	3076	if (std.mem.startsWith(u8, p.source[p.i..], "")) {
3077	p.i += 3;	3077	p.i += 3;
3078	break :blk_1 true;	3078	break :blk_1 true;
3079	}	3079	}
...	@@ -3145,7 +3145,7 @@ const Parser = struct {	...	@@ -3145,7 +3145,7 @@ const Parser = struct {
3145	return blk_0: {	3145	return blk_0: {
3146	const pos_0 = p.i;	3146	const pos_0 = p.i;
3147	if (blk_1: {	3147	if (blk_1: {
3148	if (std.mem.startsWith(u8, p.source[p.i..], "\xf4")) {	3148	if (std.mem.startsWith(u8, p.source[p.i..], "�")) {
3149	p.i += 1;	3149	p.i += 1;
3150	break :blk_1 true;	3150	break :blk_1 true;
3151	}	3151	}
...	@@ -3201,7 +3201,7 @@ const Parser = struct {	...	@@ -3201,7 +3201,7 @@ const Parser = struct {
3201	return blk_0: {	3201	return blk_0: {
3202	const pos_0 = p.i;	3202	const pos_0 = p.i;
3203	if (blk_1: {	3203	if (blk_1: {
3204	if (std.mem.startsWith(u8, p.source[p.i..], "\xf0")) {	3204	if (std.mem.startsWith(u8, p.source[p.i..], "�")) {
3205	p.i += 1;	3205	p.i += 1;
3206	break :blk_1 true;	3206	break :blk_1 true;
3207	}	3207	}
...	@@ -3257,7 +3257,7 @@ const Parser = struct {	...	@@ -3257,7 +3257,7 @@ const Parser = struct {
3257	return blk_0: {	3257	return blk_0: {
3258	const pos_0 = p.i;	3258	const pos_0 = p.i;
3259	if (blk_1: {	3259	if (blk_1: {
3260	if (std.mem.startsWith(u8, p.source[p.i..], "\xed")) {	3260	if (std.mem.startsWith(u8, p.source[p.i..], "�")) {
3261	p.i += 1;	3261	p.i += 1;
3262	break :blk_1 true;	3262	break :blk_1 true;
3263	}	3263	}
...	@@ -3313,7 +3313,7 @@ const Parser = struct {	...	@@ -3313,7 +3313,7 @@ const Parser = struct {
3313	return blk_0: {	3313	return blk_0: {
3314	const pos_0 = p.i;	3314	const pos_0 = p.i;
3315	if (blk_1: {	3315	if (blk_1: {
3316	if (std.mem.startsWith(u8, p.source[p.i..], "\xe0")) {	3316	if (std.mem.startsWith(u8, p.source[p.i..], "�")) {
3317	p.i += 1;	3317	p.i += 1;
3318	break :blk_1 true;	3318	break :blk_1 true;
3319	}	3319	}

tools/gen_parser_oracle.zig+3-6

 @@ -267,17 +267,14 @@ const Generator = struct {
                 const bytes = g.p.strings.items[literal.off..][0..literal.len];
                 try g.w.print(
                     \\blk_{d}: {{
-                    \\if (std.mem.startsWith(u8, p.source[p.i..], "
+                    \\if (std.mem.startsWith(u8, p.source[p.i..], {q})) {{
-                , .{suffix});
+                    \\
-                try std.zig.stringEscape(bytes, g.w);
-                try g.w.print(
-                    \\")) {{
                     \\p.i += {d};
                     \\    break :blk_{d} true;
                     \\}}
                     \\break :blk_{d} false;
                     \\}}
-                , .{ bytes.len, suffix, suffix });
+                , .{ suffix, bytes, bytes.len, suffix, suffix });
             },
             .class => |ranges| {
                 try g.w.writeAll("(p.i < p.source.len and switch (p.source[p.i]) {");

author	Andrew Kelley <andrew@ziglang.org> 2026-08-21 11:01:51+02:00
committer	Andrew Kelley <andrew@ziglang.org> 2026-08-21 11:01:51+02:00
log	3c46da14db296beec186c3df4fe3669f6c99b715
tree	8c34fd2046c87da2592b39454e833e0160900af0
parent	bf4e2ab8d16e74374c4769f90e1f4042c0f968a1
parent	9296ec14e9efe901b397cf8560f75cacf867f170

Merge pull request 'std.Io.Writer: string formatting enhancements' (#36596) from string-formatting into master