[28.x backport] cli/command/*: deprecate formatting-related functions and types

cli/command/checkpoint/formatter.go

@@ -11,15 +11,29 @@ const (
 )
 
 // NewFormat returns a format for use with a checkpoint Context
+//
+// Deprecated: this function was only used internally and will be removed in the next release.
 func NewFormat(source string) formatter.Format {
+	return newFormat(source)
+}
+
+// newFormat returns a format for use with a checkpointContext.
+func newFormat(source string) formatter.Format {
 	if source == formatter.TableFormatKey {
 		return defaultCheckpointFormat
 	}
 	return formatter.Format(source)
 }
 
 // FormatWrite writes formatted checkpoints using the Context
-func FormatWrite(ctx formatter.Context, checkpoints []checkpoint.Summary) error {
+//
+// Deprecated: this function was only used internally and will be removed in the next release.
+func FormatWrite(fmtCtx formatter.Context, checkpoints []checkpoint.Summary) error {
+	return formatWrite(fmtCtx, checkpoints)
+}
+
+// formatWrite writes formatted checkpoints using the Context
+func formatWrite(fmtCtx formatter.Context, checkpoints []checkpoint.Summary) error {
 	render := func(format func(subContext formatter.SubContext) error) error {
 		for _, cp := range checkpoints {
 			if err := format(&checkpointContext{c: cp}); err != nil {
@@ -28,7 +42,7 @@ func FormatWrite(ctx formatter.Context, checkpoints []checkpoint.Summary) error
 		}
 		return nil
 	}
-	return ctx.Write(newCheckpointContext(), render)
+	return fmtCtx.Write(newCheckpointContext(), render)
 }
 
 type checkpointContext struct {

cli/command/checkpoint/formatter_test.go

@@ -15,22 +15,22 @@ func TestCheckpointContextFormatWrite(t *testing.T) {
 		expected string
 	}{
 		{
-			formatter.Context{Format: NewFormat(defaultCheckpointFormat)},
+			formatter.Context{Format: newFormat(defaultCheckpointFormat)},
 			`CHECKPOINT NAME
 checkpoint-1
 checkpoint-2
 checkpoint-3
 `,
 		},
 		{
-			formatter.Context{Format: NewFormat("{{.Name}}")},
+			formatter.Context{Format: newFormat("{{.Name}}")},
 			`checkpoint-1
 checkpoint-2
 checkpoint-3
 `,
 		},
 		{
-			formatter.Context{Format: NewFormat("{{.Name}}:")},
+			formatter.Context{Format: newFormat("{{.Name}}:")},
 			`checkpoint-1:
 checkpoint-2:
 checkpoint-3:
@@ -41,7 +41,7 @@ checkpoint-3:
 	for _, testcase := range cases {
 		out := bytes.NewBufferString("")
 		testcase.context.Output = out
-		err := FormatWrite(testcase.context, []checkpoint.Summary{
+		err := formatWrite(testcase.context, []checkpoint.Summary{
 			{Name: "checkpoint-1"},
 			{Name: "checkpoint-2"},
 			{Name: "checkpoint-3"},

cli/command/checkpoint/list.go

@@ -45,7 +45,7 @@ func runList(ctx context.Context, dockerCli command.Cli, container string, opts
 
 	cpCtx := formatter.Context{
 		Output: dockerCli.Out(),
-		Format: NewFormat(formatter.TableFormatKey),
+		Format: newFormat(formatter.TableFormatKey),
 	}
-	return FormatWrite(cpCtx, checkpoints)
+	return formatWrite(cpCtx, checkpoints)
 }

cli/command/config/formatter.go

@@ -30,7 +30,14 @@ Data:
 )
 
 // NewFormat returns a Format for rendering using a config Context
+//
+// Deprecated: this function was only used internally and will be removed in the next release.
 func NewFormat(source string, quiet bool) formatter.Format {
+	return newFormat(source, quiet)
+}
+
+// newFormat returns a Format for rendering using a configContext.
+func newFormat(source string, quiet bool) formatter.Format {
 	switch source {
 	case formatter.PrettyFormatKey:
 		return configInspectPrettyTemplate
@@ -44,7 +51,14 @@ func NewFormat(source string, quiet bool) formatter.Format {
 }
 
 // FormatWrite writes the context
-func FormatWrite(ctx formatter.Context, configs []swarm.Config) error {
+//
+// Deprecated: this function was only used internally and will be removed in the next release.
+func FormatWrite(fmtCtx formatter.Context, configs []swarm.Config) error {
+	return formatWrite(fmtCtx, configs)
+}
+
+// formatWrite writes the context
+func formatWrite(fmtCtx formatter.Context, configs []swarm.Config) error {
 	render := func(format func(subContext formatter.SubContext) error) error {
 		for _, config := range configs {
 			configCtx := &configContext{c: config}
@@ -54,7 +68,7 @@ func FormatWrite(ctx formatter.Context, configs []swarm.Config) error {
 		}
 		return nil
 	}
-	return ctx.Write(newConfigContext(), render)
+	return fmtCtx.Write(newConfigContext(), render)
 }
 
 func newConfigContext() *configContext {
@@ -115,9 +129,16 @@ func (c *configContext) Label(name string) string {
 }
 
 // InspectFormatWrite renders the context for a list of configs
-func InspectFormatWrite(ctx formatter.Context, refs []string, getRef inspect.GetRefFunc) error {
-	if ctx.Format != configInspectPrettyTemplate {
-		return inspect.Inspect(ctx.Output, refs, string(ctx.Format), getRef)
+//
+// Deprecated: this function was only used internally and will be removed in the next release.
+func InspectFormatWrite(fmtCtx formatter.Context, refs []string, getRef inspect.GetRefFunc) error {
+	return inspectFormatWrite(fmtCtx, refs, getRef)
+}
+
+// inspectFormatWrite renders the context for a list of configs
+func inspectFormatWrite(fmtCtx formatter.Context, refs []string, getRef inspect.GetRefFunc) error {
+	if fmtCtx.Format != configInspectPrettyTemplate {
+		return inspect.Inspect(fmtCtx.Output, refs, string(fmtCtx.Format), getRef)
 	}
 	render := func(format func(subContext formatter.SubContext) error) error {
 		for _, ref := range refs {
@@ -135,7 +156,7 @@ func InspectFormatWrite(ctx formatter.Context, refs []string, getRef inspect.Get
 		}
 		return nil
 	}
-	return ctx.Write(&configInspectContext{}, render)
+	return fmtCtx.Write(&configInspectContext{}, render)
 }
 
 type configInspectContext struct {

cli/command/config/formatter_test.go

@@ -27,21 +27,21 @@ func TestConfigContextFormatWrite(t *testing.T) {
 		},
 		// Table format
 		{
-			formatter.Context{Format: NewFormat("table", false)},
+			formatter.Context{Format: newFormat("table", false)},
 			`ID        NAME        CREATED                  UPDATED
 1         passwords   Less than a second ago   Less than a second ago
 2         id_rsa      Less than a second ago   Less than a second ago
 `,
 		},
 		{
-			formatter.Context{Format: NewFormat("table {{.Name}}", true)},
+			formatter.Context{Format: newFormat("table {{.Name}}", true)},
 			`NAME
 passwords
 id_rsa
 `,
 		},
 		{
-			formatter.Context{Format: NewFormat("{{.ID}}-{{.Name}}", false)},
+			formatter.Context{Format: newFormat("{{.ID}}-{{.Name}}", false)},
 			`1-passwords
 2-id_rsa
 `,
@@ -64,7 +64,7 @@ id_rsa
 		t.Run(string(tc.context.Format), func(t *testing.T) {
 			var out bytes.Buffer
 			tc.context.Output = &out
-			if err := FormatWrite(tc.context, configs); err != nil {
+			if err := formatWrite(tc.context, configs); err != nil {
 				assert.ErrorContains(t, err, tc.expected)
 			} else {
 				assert.Equal(t, out.String(), tc.expected)

cli/command/config/inspect.go

@@ -63,10 +63,10 @@ func RunConfigInspect(ctx context.Context, dockerCLI command.Cli, opts InspectOp
 
 	configCtx := formatter.Context{
 		Output: dockerCLI.Out(),
-		Format: NewFormat(f, false),
+		Format: newFormat(f, false),
 	}
 
-	if err := InspectFormatWrite(configCtx, opts.Names, getRef); err != nil {
+	if err := inspectFormatWrite(configCtx, opts.Names, getRef); err != nil {
 		return cli.StatusError{StatusCode: 1, Status: err.Error()}
 	}
 	return nil

cli/command/config/ls.go

@@ -68,7 +68,7 @@ func RunConfigList(ctx context.Context, dockerCLI command.Cli, options ListOptio
 
 	configCtx := formatter.Context{
 		Output: dockerCLI.Out(),
-		Format: NewFormat(format, options.Quiet),
+		Format: newFormat(format, options.Quiet),
 	}
-	return FormatWrite(configCtx, configs)
+	return formatWrite(configCtx, configs)
 }

cli/command/container/diff.go

@@ -39,7 +39,7 @@ func runDiff(ctx context.Context, dockerCLI command.Cli, containerID string) err
 	}
 	diffCtx := formatter.Context{
 		Output: dockerCLI.Out(),
-		Format: NewDiffFormat("{{.Type}} {{.Path}}"),
+		Format: newDiffFormat("{{.Type}} {{.Path}}"),
 	}
-	return DiffFormatWrite(diffCtx, changes)
+	return diffFormatWrite(diffCtx, changes)
 }

cli/command/container/formatter_diff.go

@@ -13,24 +13,37 @@ const (
 )
 
 // NewDiffFormat returns a format for use with a diff Context
+//
+// Deprecated: this function was only used internally and will be removed in the next release.
 func NewDiffFormat(source string) formatter.Format {
+	return newDiffFormat(source)
+}
+
+// newDiffFormat returns a format for use with a diff [formatter.Context].
+func newDiffFormat(source string) formatter.Format {
 	if source == formatter.TableFormatKey {
 		return defaultDiffTableFormat
 	}
 	return formatter.Format(source)
 }
 
 // DiffFormatWrite writes formatted diff using the Context
-func DiffFormatWrite(ctx formatter.Context, changes []container.FilesystemChange) error {
-	render := func(format func(subContext formatter.SubContext) error) error {
+//
+// Deprecated: this function was only used internally and will be removed in the next release.
+func DiffFormatWrite(fmtCtx formatter.Context, changes []container.FilesystemChange) error {
+	return diffFormatWrite(fmtCtx, changes)
+}
+
+// diffFormatWrite writes formatted diff using the [formatter.Context].
+func diffFormatWrite(fmtCtx formatter.Context, changes []container.FilesystemChange) error {
+	return fmtCtx.Write(newDiffContext(), func(format func(subContext formatter.SubContext) error) error {
 		for _, change := range changes {
 			if err := format(&diffContext{c: change}); err != nil {
 				return err
 			}
 		}
 		return nil
-	}
-	return ctx.Write(newDiffContext(), render)
+	})
 }
 
 type diffContext struct {
@@ -39,12 +52,14 @@ type diffContext struct {
 }
 
 func newDiffContext() *diffContext {
-	diffCtx := diffContext{}
-	diffCtx.Header = formatter.SubHeaderContext{
-		"Type": changeTypeHeader,
-		"Path": pathHeader,
+	return &diffContext{
+		HeaderContext: formatter.HeaderContext{
+			Header: formatter.SubHeaderContext{
+				"Type": changeTypeHeader,
+				"Path": pathHeader,
+			},
+		},
 	}
-	return &diffCtx
 }
 
 func (d *diffContext) MarshalJSON() ([]byte, error) {

cli/command/container/formatter_diff_test.go

@@ -16,23 +16,23 @@ func TestDiffContextFormatWrite(t *testing.T) {
 		expected string
 	}{
 		{
-			formatter.Context{Format: NewDiffFormat("table")},
+			formatter.Context{Format: newDiffFormat("table")},
 			`CHANGE TYPE   PATH
 C             /var/log/app.log
 A             /usr/app/app.js
 D             /usr/app/old_app.js
 `,
 		},
 		{
-			formatter.Context{Format: NewDiffFormat("table {{.Path}}")},
+			formatter.Context{Format: newDiffFormat("table {{.Path}}")},
 			`PATH
 /var/log/app.log
 /usr/app/app.js
 /usr/app/old_app.js
 `,
 		},
 		{
-			formatter.Context{Format: NewDiffFormat("{{.Type}}: {{.Path}}")},
+			formatter.Context{Format: newDiffFormat("{{.Type}}: {{.Path}}")},
 			`C: /var/log/app.log
 A: /usr/app/app.js
 D: /usr/app/old_app.js
@@ -50,7 +50,7 @@ D: /usr/app/old_app.js
 		t.Run(string(tc.context.Format), func(t *testing.T) {
 			out := bytes.NewBufferString("")
 			tc.context.Output = out
-			err := DiffFormatWrite(tc.context, diffs)
+			err := diffFormatWrite(tc.context, diffs)
 			if err != nil {
 				assert.Error(t, err, tc.expected)
 			} else {

cli/command/image/formatter_history.go

@@ -20,7 +20,14 @@ const (
 )
 
 // NewHistoryFormat returns a format for rendering an HistoryContext
+//
+// Deprecated: this function was only used internally and will be removed in the next release.
 func NewHistoryFormat(source string, quiet bool, human bool) formatter.Format {
+	return newHistoryFormat(source, quiet, human)
+}
+
+// newHistoryFormat returns a format for rendering a historyContext.
+func newHistoryFormat(source string, quiet bool, human bool) formatter.Format {
 	if source == formatter.TableFormatKey {
 		switch {
 		case quiet:
@@ -36,10 +43,17 @@ func NewHistoryFormat(source string, quiet bool, human bool) formatter.Format {
 }
 
 // HistoryWrite writes the context
-func HistoryWrite(ctx formatter.Context, human bool, histories []image.HistoryResponseItem) error {
+//
+// Deprecated: this function was only used internally and will be removed in the next release.
+func HistoryWrite(fmtCtx formatter.Context, human bool, histories []image.HistoryResponseItem) error {
+	return historyWrite(fmtCtx, human, histories)
+}
+
+// historyWrite writes the context
+func historyWrite(fmtCtx formatter.Context, human bool, histories []image.HistoryResponseItem) error {
 	render := func(format func(subContext formatter.SubContext) error) error {
 		for _, history := range histories {
-			historyCtx := &historyContext{trunc: ctx.Trunc, h: history, human: human}
+			historyCtx := &historyContext{trunc: fmtCtx.Trunc, h: history, human: human}
 			if err := format(historyCtx); err != nil {
 				return err
 			}
@@ -55,7 +69,7 @@ func HistoryWrite(ctx formatter.Context, human bool, histories []image.HistoryRe
 		"Size":         formatter.SizeHeader,
 		"Comment":      commentHeader,
 	}
-	return ctx.Write(historyCtx, render)
+	return fmtCtx.Write(historyCtx, render)
 }
 
 type historyContext struct {

cli/command/image/formatter_history_test.go

@@ -237,15 +237,15 @@ imageID6   17 years ago   /bin/bash echo                                  183MB
 	}{
 		{
 			formatter.Context{
-				Format: NewHistoryFormat("table", false, true),
+				Format: newHistoryFormat("table", false, true),
 				Trunc:  true,
 				Output: out,
 			},
 			expectedTrunc,
 		},
 		{
 			formatter.Context{
-				Format: NewHistoryFormat("table", false, true),
+				Format: newHistoryFormat("table", false, true),
 				Trunc:  false,
 				Output: out,
 			},
@@ -255,7 +255,7 @@ imageID6   17 years ago   /bin/bash echo                                  183MB
 
 	for _, tc := range cases {
 		t.Run(string(tc.context.Format), func(t *testing.T) {
-			err := HistoryWrite(tc.context, true, histories)
+			err := historyWrite(tc.context, true, histories)
 			assert.NilError(t, err)
 			assert.Equal(t, out.String(), tc.expected)
 			// Clean buffer