mirror of
https://github.com/ddidderr/wuffs.git
synced 2026-11-19 00:38:14 +01:00
Add dumbindent algorithm comment
This commit is contained in:
1 parent
e42d126667
commit
22d08366c8
3 files changed
+112
-32
No files matched your search
+22
-19
@@ -17,31 +17,34 @@
|
||||
// dumbindent formats C (and C-like) programs.
|
||||
//
|
||||
// Without explicit paths, it rewrites the standard input to standard output.
|
||||
// Otherwise, the -l or -w or both flags must be given. Given a file path, it
|
||||
// operates on that file; given a directory path, it operates on all *.{c,h}
|
||||
// files in that directory, recursively. File paths starting with a period are
|
||||
// ignored.
|
||||
// Otherwise, the -l (list files that would change) or -w (write files in
|
||||
// place) or both flags must be given. Given a file path, it operates on that
|
||||
// file; given a directory path, it operates on all *.{c,h} files in that
|
||||
// directory, recursively. File paths starting with a period are ignored.
|
||||
//
|
||||
// Pass -spaces=N or -tabs to use N spaces or 1 tab per indent level. The
|
||||
// default is 2 spaces per indent level.
|
||||
//
|
||||
// It is similar in concept to pretty-printers like `indent` or `clang-format`.
|
||||
// It is much dumber (it will not add line breaks or otherwise re-flow lines of
|
||||
// code just to fit within an 80 character limit) but it can therefore be much,
|
||||
// much faster at the basic task of automatically indenting nested blocks. The
|
||||
// code just to fit within an 80 character limit) but it can therefore be much
|
||||
// faster at the basic task of automatically indenting nested blocks. The
|
||||
// output isn't 'perfect', but it's usually sufficiently readable if the input
|
||||
// already has sensible line breaks.
|
||||
//
|
||||
// An example of "much, much faster", 80 times faster than clang-format:
|
||||
// ----
|
||||
// $ wc release/c/wuffs-v0.2.c
|
||||
// 11858 35980 431885 release/c/wuffs-v0.2.c
|
||||
// $ time clang-format-9 < release/c/wuffs-v0.2.c > /dev/null
|
||||
// real 0m0.677s
|
||||
// user 0m0.620s
|
||||
// sys 0m0.040s
|
||||
// $ time dumbindent < release/c/wuffs-v0.2.c > /dev/null
|
||||
// real 0m0.008s
|
||||
// user 0m0.005s
|
||||
// sys 0m0.005s
|
||||
// ----
|
||||
// To quantify "much faster", on this one C file, this program was 80 times
|
||||
// faster than `clang-format`:
|
||||
//
|
||||
// $ wc release/c/wuffs-v0.2.c
|
||||
// 11858 35980 431885 release/c/wuffs-v0.2.c
|
||||
// $ time clang-format-9 < release/c/wuffs-v0.2.c > /dev/null
|
||||
// real 0m0.677s
|
||||
// user 0m0.620s
|
||||
// sys 0m0.040s
|
||||
// $ time dumbindent < release/c/wuffs-v0.2.c > /dev/null
|
||||
// real 0m0.008s
|
||||
// user 0m0.005s
|
||||
// sys 0m0.005s
|
||||
package main
|
||||
|
||||
import (
|
||||
|
||||
@@ -18,13 +18,92 @@
|
||||
//
|
||||
// It is similar in concept to pretty-printers like `indent` or `clang-format`.
|
||||
// It is much dumber (it will not add line breaks or otherwise re-flow lines of
|
||||
// code just to fit within an 80 character limit) but it can therefore be much,
|
||||
// much faster at the basic task of automatically indenting nested blocks. The
|
||||
// code just to fit within an 80 character limit) but it can therefore be much
|
||||
// faster at the basic task of automatically indenting nested blocks. The
|
||||
// output isn't 'perfect', but it's usually sufficiently readable if the input
|
||||
// already has sensible line breaks.
|
||||
//
|
||||
// See `cmd/dumbindent/main.go` in this repository for an example where
|
||||
// `dumbindent` was 80 times faster than `clang-format`.
|
||||
// To quantify "much faster", on this one C file, `cmd/dumbindent` in this
|
||||
// repository was 80 times faster than `clang-format`:
|
||||
//
|
||||
// $ wc release/c/wuffs-v0.2.c
|
||||
// 11858 35980 431885 release/c/wuffs-v0.2.c
|
||||
// $ time clang-format-9 < release/c/wuffs-v0.2.c > /dev/null
|
||||
// real 0m0.677s
|
||||
// user 0m0.620s
|
||||
// sys 0m0.040s
|
||||
// $ time dumbindent < release/c/wuffs-v0.2.c > /dev/null
|
||||
// real 0m0.008s
|
||||
// user 0m0.005s
|
||||
// sys 0m0.005s
|
||||
//
|
||||
// Apart from some rare and largely uninteresting exceptions, the dumbindent
|
||||
// algorithm only considers:
|
||||
//
|
||||
// ∙ '{' and '}' curly braces,
|
||||
// ∙ '(' and ')' round parentheses,
|
||||
// ∙ ';' semi-colons (if they're not within parentheses),
|
||||
// ∙ strings, comments and preprocessor directives,
|
||||
// ∙ '\n' line breaks, and
|
||||
// ∙ ' ' spaces and '\t' tabs adjacent to any of the above.
|
||||
//
|
||||
// Everything else is an opaque byte. Consider this input:
|
||||
//
|
||||
// for (i = 0; i < 3; i++) {
|
||||
// j = 0; j++; // Semi-colons not within parentheses.
|
||||
// if (i < j) { foo(); }
|
||||
// u = (v +
|
||||
// w);
|
||||
// }
|
||||
//
|
||||
// From the algorithm's point of view, this input is equivalent to:
|
||||
//
|
||||
// ... (.................) {
|
||||
// .....; ...; //....................................
|
||||
// .. (.....) { ...(); }
|
||||
// ... (...
|
||||
// .);
|
||||
// }
|
||||
//
|
||||
// The formatted output (using the default of 2 spaces per indent level) is:
|
||||
//
|
||||
// ... (.................) {
|
||||
// .....;
|
||||
// ...; //....................................
|
||||
// .. (.....) {
|
||||
// ...();
|
||||
// }
|
||||
// ... (...
|
||||
// .);
|
||||
// }
|
||||
//
|
||||
// Line breaks are generally forced after semi-colons (outside of a for loop's
|
||||
// triple expressions) and open-braces. Each output line is then indented
|
||||
// according to the net number of open braces preceding it, although lines
|
||||
// starting with close braces will outdent first, similar to `gofmt` style. A
|
||||
// line whose start is inside a so-far-unbalanced open parenthesis, such as the
|
||||
// "w);" line above, gets 2 additional indent levels.
|
||||
//
|
||||
// Dumbindent will remove some superfluous blank lines, but it will not remove
|
||||
// line breaks between consecutive non-empty lines, such as between "u = (v +"
|
||||
// and "w);" in the example above.
|
||||
//
|
||||
// Dumbindent does not parse the input as C/C++ source code. In particular, the
|
||||
// algorithm has no interest in solving C++'s "most vexing parse" or
|
||||
// determining whether "x*y" is a multiplication or a type definition (where
|
||||
// "x" is a type and "y" is a pointer-typed variable, such as "int*p"). For a
|
||||
// type definition, where other formatting algorithms would re-write around the
|
||||
// "*" as either "x* y" or "x *y", dumbindent will not insert spaces.
|
||||
//
|
||||
// Similarly, dumbindent will not correct this mis-indentation:
|
||||
//
|
||||
// if (condition)
|
||||
// goto fail;
|
||||
// goto fail;
|
||||
//
|
||||
// Instead, when automatically or manually generating the input for dumbindent,
|
||||
// it is recommended to always emit curly braces (again, similar to `gofmt`
|
||||
// style), even for what would otherwise be 'one-liner' if statements.
|
||||
package dumbindent
|
||||
|
||||
import (
|
||||
@@ -67,7 +146,7 @@ type Options struct {
|
||||
// (cap(dst) - len(dst)) is too short to hold the formatted program. In this
|
||||
// case, a new slice will be allocated and returned.
|
||||
//
|
||||
// Passing a nil opts means to use the default options.
|
||||
// Passing a nil opts is valid and equivalent to passing &Options{}.
|
||||
func FormatBytes(dst []byte, src []byte, opts *Options) []byte {
|
||||
src = trimLeadingWhiteSpaceAndNewLines(src)
|
||||
if len(src) == 0 {
|
||||
|
||||
@@ -95,26 +95,24 @@ func TestTabs(tt *testing.T) {
|
||||
|
||||
func ExampleFormatBytes() {
|
||||
const src = `
|
||||
// Blah blah blah.
|
||||
|
||||
|
||||
for (i = 0; i < 3; i++) {
|
||||
j = 0; j < 4; j++;
|
||||
j = 0; j++; // Semi-colons not within parentheses.
|
||||
if (i < j) { foo(); }
|
||||
u = (v +
|
||||
w);
|
||||
}
|
||||
`
|
||||
|
||||
os.Stdout.Write(FormatBytes(nil, []byte(src), nil))
|
||||
|
||||
// Output:
|
||||
// // Blah blah blah.
|
||||
//
|
||||
// for (i = 0; i < 3; i++) {
|
||||
// j = 0;
|
||||
// j < 4;
|
||||
// j++;
|
||||
// j++; // Semi-colons not within parentheses.
|
||||
// if (i < j) {
|
||||
// foo();
|
||||
// }
|
||||
// u = (v +
|
||||
// w);
|
||||
// }
|
||||
}
|
||||
Reference in new issue
Block a user