authorgravatar for 178735591+87flowers@users.noreply.github.com87flowers <178735591+87flowers@users.noreply.github.com> 2024-10-18 10:06:02+01:00
committergravatar for andrew@ziglang.orgAndrew Kelley <andrew@ziglang.org> 2025-02-22 17:09:20-08:00
log87172ee4e609ca8298a48f4ae92f1c539368e12e
treed4ee30a7b2b51cd9807398f2e1caf8546057570d
parentfdf68c2f2e4f6f7ca77752b8610e05778b07a22b

std/zig/render: Add doc comments to AutoIndentingStream

1 files changed, 34 insertions(+), 2 deletions(-)

lib/std/zig/render.zig+34-2
......@@ -3302,6 +3302,26 @@ fn rowSize(tree: Ast, exprs: []const Ast.Node.Index, rtoken: Ast.TokenIndex) usi
33023302
33033303/// Automatically inserts indentation of written data by keeping
33043304/// track of the current indentation level
3305///
3306/// We introduce a new indentation scope with pushIndent/popIndent whenever
3307/// we potentially want to introduce an indent after the next newline.
3308///
3309/// Indentation should only ever increment by one from one line to the next,
3310/// no matter how many new indentation scopes are introduced. This is done by
3311/// only realizing the indentation from the most recent scope. As an example:
3312///
3313/// while (foo) if (bar)
3314/// f(x);
3315///
3316/// The body of `while` introduces a new indentation scope and the body of
3317/// `if` also introduces a new indentation scope. When the newline is seen,
3318/// only the indentation scope of the `if` is realized, and the `while` is
3319/// not.
3320///
3321/// As comments are rendered during space rendering, we need to keep track
3322/// of the appropriate indentation level for them with pushSpace/popSpace.
3323/// This should be done whenever a scope that ends in a .semicolon or a
3324/// .comma is introduced.
33053325fn AutoIndentingStream(comptime UnderlyingWriter: type) type {
33063326 return struct {
33073327 const Self = @This();
......@@ -3400,8 +3420,11 @@ fn AutoIndentingStream(comptime UnderlyingWriter: type) type {
34003420
34013421 fn resetLine(self: *Self) void {
34023422 self.current_line_empty = true;
3423
34033424 if (self.disable_indent_committing > 0) return;
3425
34043426 if (self.indent_stack.items.len > 0) {
3427 // By default, we realize the most recent indentation scope.
34053428 var to_realize = self.indent_stack.items.len - 1;
34063429
34073430 if (self.indent_stack.items.len >= 2 and
......@@ -3409,12 +3432,18 @@ fn AutoIndentingStream(comptime UnderlyingWriter: type) type {
34093432 self.indent_stack.items[to_realize - 1].realized and
34103433 self.indent_stack.items[to_realize].indent_type == .binop)
34113434 {
3412 // collapse one level of indentation in binop after equals sign
3435 // If we are in a .binop scope and our direct parent is .after_equals, don't indent.
3436 // This ensures correct indentation in the below example:
3437 //
3438 // const foo =
3439 // (x >= 'a' and x <= 'z') or //<-- we are here
3440 // (x >= 'A' and x <= 'Z');
3441 //
34133442 return;
34143443 }
34153444
34163445 if (self.indent_stack.items[to_realize].indent_type == .field_access) {
3417 // only realize topmost field_access in a chain
3446 // Only realize the top-most field_access in a chain.
34183447 while (to_realize > 0 and self.indent_stack.items[to_realize - 1].indent_type == .field_access)
34193448 to_realize -= 1;
34203449 }
......@@ -3425,6 +3454,7 @@ fn AutoIndentingStream(comptime UnderlyingWriter: type) type {
34253454 }
34263455 }
34273456
3457 /// Disables indentation level changes during the next newlines until re-enabled.
34283458 pub fn disableIndentCommitting(self: *Self) void {
34293459 self.disable_indent_committing += 1;
34303460 }
......@@ -3442,6 +3472,7 @@ fn AutoIndentingStream(comptime UnderlyingWriter: type) type {
34423472 _ = self.space_stack.pop();
34433473 }
34443474
3475 /// Sets current indentation level to be the same as that of the last pushSpace.
34453476 pub fn enableSpaceMode(self: *Self, space: Space) void {
34463477 if (self.space_stack.items.len == 0) return;
34473478 const curr = self.space_stack.getLast();
......@@ -3471,6 +3502,7 @@ fn AutoIndentingStream(comptime UnderlyingWriter: type) type {
34713502 try self.indent_stack.append(.{ .indent_type = indent_type, .realized = false });
34723503 }
34733504
3505 /// Forces an indentation level to be realized.
34743506 pub fn forcePushIndent(self: *Self, indent_type: IndentType) !void {
34753507 try self.indent_stack.append(.{ .indent_type = indent_type, .realized = true });
34763508 self.indent_count += 1;