Add fmt modules (printf implementation) (denoland/std#566)

Original: denoland/std@f7b5116

fmt/README.md

@@ -0,0 +1,212 @@
+# 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

fmt/TODO

@@ -0,0 +1,12 @@
+
+* "native" formatting, json, arrays, object/structs, functions ...
+* %q %U
+* Java has a %n flag to print the plattform native newline... in POSIX
+  that means "number of chars printed so far", though.
+* use of Writer and Buffer internally in order to make FPrintf, Printf, etc.
+  easier and more elegant.
+* see "Discussion" in README
+
+*scanf , pack,unpack, annotated hex
+* error handling, consistantly
+* probably rewrite, now that I konw how it's done.