scriptprintf

package
v1.166.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 20, 2026 License: Apache-2.0 Imports: 12 Imported by: 0

Documentation

Overview

Package scriptprintf is the string formatting a managed script's `%` operator and str.format method run (#2048).

Starlark's own `%` takes bare verbs only and its str.format takes no format spec, so "%02X" % b, "%.2f" % rate and "{:>10}".format(name) fail at run time with "unknown conversion". Every Python-shaped language an author knows accepts them, and the failure surfaces on the first run that reaches the line, often a branch no draft took. This package implements the printf subset (flags - 0 + space #, width, precision, * for either) and Python's format-spec mini-language, and Rewrite routes a script's `%` and .format through them before the script is compiled. A left operand that is not a string, and a .format on anything but a string, go to Starlark's own.

The package knows nothing about runs or the platform; CheckPercent and CheckFormat let the authoring gates refuse a literal format string that would still fail, at save rather than mid-run.

Index

Constants

View Source
const (
	PercentName = "%"
	FormatName  = ".format"
)

PercentName and FormatName are the globals Rewrite routes `%` and .format through. Neither is an identifier a script can write, so a script can neither call nor shadow them: the resolver looks a name up by its text and does not check that it could have been typed.

View Source
const MaxField = 1 << 20

MaxField is the widest field and the longest precision a format may ask for (#2713). The text a field pads or a precision prints to is allocated whole, outside the run's memory budget until the next host call, so "%100000000000000c" asked one replica for a hundred terabytes and ended it (found by FuzzFormatting). Python refuses such a field too.

Variables

This section is empty.

Functions

func Bind

Bind returns env with PercentName and FormatName bound, for the module a rewritten file is compiled against.

func CheckFormat

func CheckFormat(template string) error

CheckFormat reports why template would be refused by str.format, or nil. It reads the template alone: whether the arguments fit is the run's to find out.

func CheckPercent

func CheckPercent(format string) error

CheckPercent reports why format would be refused as the left operand of `%`, or nil. It reads the format alone: whether the arguments fit is the run's to find out.

func Format

func Format(template string, args starlark.Tuple, kwargs []starlark.Tuple) (starlark.Value, error)

Format is s.format(*args, **kwargs) for a string s.

func Percent

func Percent(x, y starlark.Value) (starlark.Value, error)

Percent is `x % y`: Python's printf-style formatting when x is a string, and Starlark's own operator otherwise.

func Rewrite

func Rewrite(file *syntax.File)

Rewrite routes every `x % y`, `name %= y` and `x.format(...)` in file through PercentName and FormatName, in place. Positions are kept: the call is placed at the operator or the method name, so an error is reported where the script wrote it.

It has to be a rewrite. Starlark evaluates `%` and a string's methods inside the interpreter, with no hook a predeclared value can take, and the alternative is a fork of the interpreter.

A `%=` whose target is not a plain name (d["k"] %= v) is left to Starlark: rewriting it would evaluate the target twice.

Types

This section is empty.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL