mirror of
https://github.com/denoland/deno.git
synced 2024-11-23 15:16:54 -05:00
211 lines
8.5 KiB
Markdown
211 lines
8.5 KiB
Markdown
# Printf for Deno
|
|
|
|
This is very much a work-in-progress. I'm actively soliciting feedback. What
|
|
immediately follows are points for discussion.
|
|
|
|
If you are looking for the documentation proper, skip to:
|
|
|
|
"printf: prints formatted output"
|
|
|
|
below.
|
|
|
|
## Discussion
|
|
|
|
This is very much a work-in-progress. I'm actively soliciting feedback.
|
|
|
|
- What useful features are available in other languages apart from Golang and C?
|
|
|
|
- behaviour of `%v` verb. In Golang, this is a shortcut verb to "print the
|
|
default format" of the argument. It is currently implemented to format using
|
|
`toString` in the default case and `inpect` if the `%#v` alternative format
|
|
flag is used in the format directive. Alternativly, `%V` could be used to
|
|
distinguish the two.
|
|
|
|
`inspect` output is not defined, however. This may be problematic if using
|
|
this code on other plattforms (and expecting interoperability). To my
|
|
knowledge, no suitable specification of object representation aside from JSON
|
|
and `toString` exist. ( Aside: see "[Common object formats][3]" in the
|
|
"Console Living Standard" which basically says "do whatever" )
|
|
|
|
- `%j` verb. This is an extension particular to this implementation. Currently
|
|
not very sophisticated, it just runs `JSON.stringify` on the argument.
|
|
Consider possible modifier flags, etc.
|
|
|
|
- `<` verb. This is an extension that assumes the argument is an array and will
|
|
format each element according to the format (surrounded by [] and seperated by
|
|
comma) (`<` Mnemonic: pull each element out of array)
|
|
|
|
- how to deal with more newfangled Javascript features ( generic Iterables, Map
|
|
and Set types, typed Arrays, ...)
|
|
|
|
- the implementation is fairly rough around the edges:
|
|
|
|
- currently contains little in the way of checking for correctness. Conceivably,
|
|
there will be a 'strict' form, e.g. that ensures only Number-ish arguments are
|
|
passed to %f flags
|
|
|
|
- assembles output using string concatenation instead of utilizing buffers or
|
|
other optimizations. It would be nice to have printf / sprintf / fprintf (etc)
|
|
all in one.
|
|
|
|
- float formatting is handled by toString() and to `toExponential` along with a
|
|
mess of Regexp. Would be nice to use fancy match
|
|
|
|
- some flags that are potentially applicable ( POSIX long and unsigned modifiers
|
|
are not likely useful) are missing, namely %q (print quoted), %U (unicode
|
|
format)
|
|
|
|
## Author
|
|
|
|
Tim Becker (tim@presseverykey.com)
|
|
|
|
## License
|
|
|
|
MIT
|
|
|
|
The implementation is inspired by POSIX and Golang (see above) but does not port
|
|
implementation code. A number of Golang test-cases based on:
|
|
|
|
https://golang.org/src/fmt/fmt_test.go
|
|
( BSD: Copyright (c) 2009 The Go Authors. All rights reserved. )
|
|
|
|
were used.
|
|
|
|
# printf: prints formatted output
|
|
|
|
sprintf converts and formats a variable number of arguments as is specified by a
|
|
`format string`. In it's basic form, a format string may just be a literal. In
|
|
case arguments are meant to be formatted, a `directive` is contained in the
|
|
format string, preceded by a '%' character:
|
|
|
|
%<verb>
|
|
|
|
E.g. the verb `s` indicates the directive should be replaced by the string
|
|
representation of the argument in the corresponding position of the argument
|
|
list. E.g.:
|
|
|
|
Hello %s!
|
|
|
|
applied to the arguments "World" yields "Hello World!"
|
|
|
|
The meaning of the format string is modelled after [POSIX][1] format strings as
|
|
well as well as [Golang format strings][2]. Both contain elements specific to
|
|
the respective programming language that don't apply to JavaScript, so they can
|
|
not be fully supported. Furthermore we implement some functionality that is
|
|
specific to JS.
|
|
|
|
## Verbs
|
|
|
|
The following verbs are supported:
|
|
|
|
| Verb | Meaning |
|
|
| ----- | -------------------------------------------------------------- |
|
|
| `%` | print a literal percent |
|
|
| `t` | evaluate arg as boolean, print `true` or `false` |
|
|
| `b` | eval as number, print binary |
|
|
| `c` | eval as number, print character corresponding to the codePoint |
|
|
| `o` | eval as number, print octal |
|
|
| `x X` | print as hex (ff FF), treat string as list of bytes |
|
|
| `e E` | print number in scientific/exponent format 1.123123e+01 |
|
|
| `f F` | print number as float with decimal point and no exponent |
|
|
| `g G` | use %e %E or %f %F depending on size of argument |
|
|
| `s` | interpolate string |
|
|
| `T` | type of arg, as returned by `typeof` |
|
|
| `v` | value of argument in 'default' format (see below) |
|
|
| `j` | argument as formatted by `JSON.stringify` |
|
|
|
|
## Width and Precision
|
|
|
|
Verbs may be modified by providing them with width and precision, either or both
|
|
may be omitted:
|
|
|
|
%9f width 9, default precision
|
|
%.9f default width, precision 9
|
|
%8.9f width 8, precision 9
|
|
%8.f width 9, precision 0
|
|
|
|
In general, 'width' describes the minimum length of the output, while
|
|
'precision' limits the output.
|
|
|
|
| verb | precision |
|
|
| --------- | -------------------------------------------------------------- |
|
|
| `t` | n/a |
|
|
| `b c o` | n/a |
|
|
| `x X` | n/a for number, strings are truncated to p bytes(!) |
|
|
| `e E f F` | number of places after decimal, default 6 |
|
|
| `g G` | set maximum number of digits |
|
|
| `s` | truncate input |
|
|
| `T` | truncate |
|
|
| `v` | tuncate, or depth if used with # see "'default' format", below |
|
|
| `j` | n/a |
|
|
|
|
Numerical values for width and precision can be substituted for the `*` char, in
|
|
which case the values are obtained from the next args, e.g.:
|
|
|
|
sprintf ("%*.*f", 9,8,456.0)
|
|
|
|
is equivalent to
|
|
|
|
sprintf ("%9.9f", 456.0)
|
|
|
|
## Flags
|
|
|
|
The effects of the verb may be further influenced by using flags to modify the
|
|
directive:
|
|
|
|
| Flag | Verb | Meaning |
|
|
| ----- | --------- | -------------------------------------------------------------------------- |
|
|
| `+` | numeric | always print sign |
|
|
| `-` | all | pad to the right (left justify) |
|
|
| `#` | | alternate format |
|
|
| `#` | `b o x X` | prefix with `0b 0 0x` |
|
|
| `#` | `g G` | don't remove trailing zeros |
|
|
| `#` | `v` | ues output of `inspect` instead of `toString` |
|
|
| `' '` | | space character |
|
|
| `' '` | `x X` | leave spaces between bytes when printing string |
|
|
| `' '` | `d` | insert space for missing `+` sign character |
|
|
| `0` | all | pad with zero, `-` takes precedence, sign is appended in front of padding |
|
|
| `<` | all | format elements of the passed array according to the directive (extension) |
|
|
|
|
## 'default' format
|
|
|
|
The default format used by `%v` is the result of calling `toString()` on the
|
|
relevant argument. If the `#` flags is used, the result of calling `inspect()`
|
|
is interpolated. In this case, the precision, if set is passed to `inspect()` as
|
|
the 'depth' config parameter
|
|
|
|
## Positional arguments
|
|
|
|
Arguments do not need to be consumed in the order they are provded and may be
|
|
consumed more than once. E.g.:
|
|
|
|
sprintf("%[2]s %[1]s", "World", "Hello")
|
|
|
|
returns "Hello World". The precence of a positional indicator resets the arg
|
|
counter allowing args to be reused:
|
|
|
|
sprintf("dec[%d]=%d hex[%[1]d]=%x oct[%[1]d]=%#o %s", 1, 255, "Third")
|
|
|
|
returns `dec[1]=255 hex[1]=0xff oct[1]=0377 Third`
|
|
|
|
Width and precision my also use positionals:
|
|
|
|
"%[2]*.[1]*d", 1, 2
|
|
|
|
This follows the golang conventions and not POSIX.
|
|
|
|
## Errors
|
|
|
|
The following errors are handled:
|
|
|
|
Incorrect verb:
|
|
|
|
S("%h", "") %!(BAD VERB 'h')
|
|
|
|
Too few arguments:
|
|
|
|
S("%d") %!(MISSING 'd')"
|
|
|
|
[1]: https://pubs.opengroup.org/onlinepubs/009695399/functions/fprintf.html
|
|
[2]: https://golang.org/pkg/fmt/
|
|
[3]: https://console.spec.whatwg.org/#object-formats
|