| // Copyright 2022 The Go Authors. All rights reserved. |
| // Use of this source code is governed by a BSD-style |
| // license that can be found in the LICENSE file. |
| |
| // Package syntax documents the syntax used by benchmark filter and |
| // projection expressions. |
| // |
| // These expressions work with benchmark data in the Go benchmark |
| // format (https://golang.org/design/14313-benchmark-format). Each |
| // benchmark result (a line beginning with "Benchmark") consists of |
| // several field, including a name, name-based configuration, and |
| // file configuration pairs ("key: value" lines). |
| // |
| // # Keys |
| // |
| // Filters and projections share a common set of keys for referring to |
| // these fields of a benchmark result: |
| // |
| // - ".name" refers to the benchmark name, excluding per-benchmark |
| // configuration. For example, the ".name" of the |
| // "BenchmarkCopy/size=4k-16" benchmark is "Copy". |
| // |
| // - ".fullname" refers to the full benchmark name, including |
| // per-benchmark configuration, but excluding the "Benchmark" prefix. |
| // For example, the ".fullname" of "BenchmarkCopy/size=4k-16" is |
| // "Copy/size=4k-16". |
| // |
| // - "/{key}" refers to value of {key} from the benchmark name |
| // configuration. For example, the "/size" of |
| // "BenchmarkCopy/size=4k-16", is "4k". As a special case, |
| // "/gomaxprocs" recognizes both a literal "/gomaxprocs=" in the name, |
| // and the "-N" convention. For the above example, "/gomaxprocs" is |
| // "16". |
| // |
| // - Any name NOT prefixed with "/" or "." refers to the value of a |
| // file configuration key. For example, the "testing" package |
| // automatically emits a few file configuration keys, including "pkg", |
| // "goos", and "goarch", so the projection "pkg" extracts the package |
| // path of a benchmark. |
| // |
| // - ".config" (only in projections) refers to the all file |
| // configuration keys of a benchmark. The value of .config isn't a |
| // string like the other fields, but rather a tuple. .config is useful |
| // for grouping results by all file configuration keys to avoid grouping |
| // together incomparable results. For example, benchstat separates |
| // results with different .config into different tables. |
| // |
| // - ".unit" (only in filters) refers to individual measurements in a |
| // result, such as the "ns/op" measurement. The filter ".unit:ns/op" |
| // extracts just the ns/op measurement of a result. This will match |
| // both original units (e.g., "ns/op") and tidied units (e.g., |
| // "sec/op"). |
| // |
| // - ".file" refers to the input file provided on the command line |
| // (for command-line tools that use benchfmt.Files). |
| // |
| // # Filters |
| // |
| // Filters are boolean expressions that match or exclude benchmark |
| // results or individual measurements. |
| // |
| // Filters are built from key-value terms: |
| // |
| // key:value - Match if key's value is exactly "value". |
| // key:"value" - Same, but value is a double-quoted Go string that |
| // may contain spaces or other special characters. |
| // "key":value - Keys may also be double-quoted. |
| // key:/regexp/ - Match if key's value matches a regular expression. |
| // key:(val1 OR val2 OR ...) |
| // - Short-hand for key:val1 OR key:val2. Values may be |
| // double-quoted strings or regexps. |
| // * - Match everything. |
| // |
| // These terms can be combined into larger expressions as follows: |
| // |
| // x y ... - Match if x, y, etc. all match. |
| // x AND y - Same as x y. |
| // x OR y - Match if x or y match. |
| // -x - Match if x does not match. |
| // (...) - Subexpression. |
| // |
| // Precise syntax: |
| // |
| // expr = andExpr {"OR" andExpr} |
| // andExpr = match {"AND"? match} |
| // match = "(" expr ")" |
| // | "-" match |
| // | "*" |
| // | key ":" value |
| // | key ":" "(" value {"OR" value} ")" |
| // key = word |
| // value = word |
| // | "/" regexp "/" |
| // |
| // # Projections |
| // |
| // A projection expresses how to extract a tuple of data from a |
| // benchmark result, as well as a sort order for projected tuples. |
| // |
| // A projection is a comma- or space-separated list of fields. |
| // Each field specifies a key and optionally a sort order and a |
| // filter as follows: |
| // |
| // - "key" extracts the named field and orders it using the order |
| // values of this key are first observed in the data. |
| // |
| // - "key@order" specifies one of the built-in named sort orders. This |
| // can be "alpha" or "num" for alphabetic or numeric sorting. "num" |
| // understands basic use of metric and IEC prefixes like "2k" and |
| // "1Mi". |
| // |
| // - "key@(value value ...)" specifies a fixed value order for key. |
| // It also specifies a filter: if key has a value that isn't any of |
| // the specified values, the result is filtered out. |
| // |
| // Precise syntax: |
| // |
| // expr = part {","? part} |
| // part = key |
| // | key "@" order |
| // | key "@" "(" word {word} ")" |
| // key = word |
| // order = word |
| // |
| // # Common syntax |
| // |
| // Filters and projections share the following common base syntax: |
| // |
| // word = bareWord |
| // | double-quoted Go string |
| // bareWord = [^-*"():@,][^ ():@,]* |
| package syntax |
