From 700bbb37c5f5a7b097cbcf4ce0774f76fbb9b29c Mon Sep 17 00:00:00 2001 From: Dave Henderson Date: Sun, 18 Nov 2018 10:23:15 -0500 Subject: [PATCH] textfile collector: Skip BOM when present Signed-off-by: Dave Henderson --- Gopkg.lock | 64 +- collector/textfile.go | 4 +- .../github.com/alecthomas/template/README.md | 25 - vendor/github.com/alecthomas/units/README.md | 11 - vendor/github.com/dimchansky/utfbom/LICENSE | 201 ++++++ vendor/github.com/dimchansky/utfbom/utfbom.go | 174 +++++ .../gopkg.in/alecthomas/kingpin.v2/README.md | 674 ------------------ .../alecthomas/kingpin.v2/values.json | 25 - 8 files changed, 435 insertions(+), 743 deletions(-) delete mode 100644 vendor/github.com/alecthomas/template/README.md delete mode 100644 vendor/github.com/alecthomas/units/README.md create mode 100644 vendor/github.com/dimchansky/utfbom/LICENSE create mode 100644 vendor/github.com/dimchansky/utfbom/utfbom.go delete mode 100644 vendor/gopkg.in/alecthomas/kingpin.v2/README.md delete mode 100644 vendor/gopkg.in/alecthomas/kingpin.v2/values.json diff --git a/Gopkg.lock b/Gopkg.lock index 4efe3a53..02a86fda 100644 --- a/Gopkg.lock +++ b/Gopkg.lock @@ -2,124 +2,174 @@ [[projects]] + digest = "1:3ccf8ba7afe02fd470c4f07d6eea4d0e6875da3d129f95b925f2003ce5dd2024" name = "github.com/StackExchange/wmi" packages = ["."] + pruneopts = "NUT" revision = "5d049714c4a64225c3c79a7cf7d02f7fb5b96338" version = "1.0.0" [[projects]] branch = "master" + digest = "1:f3793f8a708522400cef1dba23385e901aede5519f68971fd69938ef330b07a1" name = "github.com/alecthomas/template" packages = [ ".", - "parse" + "parse", ] + pruneopts = "NUT" revision = "a0175ee3bccc567396460bf5acd36800cb10c49c" [[projects]] branch = "master" + digest = "1:fdd419e104ec26bb5bd63cc62637c640453ed2929a7453f3afadbd9a0223da66" name = "github.com/alecthomas/units" packages = ["."] + pruneopts = "NUT" revision = "2efee857e7cfd4f3d0138cc3cbb1b4966962b93a" [[projects]] branch = "master" + digest = "1:cb0535f5823b47df7dcb9768ebb6c000b79ad115472910c70efe93c9ed9b2315" name = "github.com/beorn7/perks" packages = ["quantile"] + pruneopts = "NUT" revision = "4c0e84591b9aa9e6dcfdf3e020114cd81f89d5f9" [[projects]] + digest = "1:ec6271918b59b872a2d25e374569a4f75f1839d91e4191470c297b7eaaaf7641" + name = "github.com/dimchansky/utfbom" + packages = ["."] + pruneopts = "NUT" + revision = "5448fe645cb1964ba70ac8f9f2ffe975e61a536c" + version = "v1.0.0" + +[[projects]] + digest = "1:cb4e216bd9f58866f42dc65893455b24f879b026fdaa1ecc3aafff625fdb5a66" name = "github.com/go-ole/go-ole" packages = [ ".", - "oleutil" + "oleutil", ] + pruneopts = "NUT" revision = "a41e3c4b706f6ae8dfbff342b06e40fa4d2d0506" version = "v1.2.1" [[projects]] + digest = "1:9f35c1344b56e5868d511d231f215edd0650aa572664f856444affdd256e43e4" name = "github.com/golang/protobuf" packages = ["proto"] + pruneopts = "NUT" revision = "925541529c1fa6821df4e44ce2723319eb2be768" version = "v1.0.0" [[projects]] + digest = "1:5985ef4caf91ece5d54817c11ea25f182697534f8ae6521eadcd628c142ac4b6" name = "github.com/matttproud/golang_protobuf_extensions" packages = ["pbutil"] + pruneopts = "NUT" revision = "3247c84500bff8d9fb6d579d800f20b3e091582c" version = "v1.0.0" [[projects]] + digest = "1:03bca087b180bf24c4f9060775f137775550a0834e18f0bca0520a868679dbd7" name = "github.com/prometheus/client_golang" packages = [ "prometheus", - "prometheus/promhttp" + "prometheus/promhttp", ] + pruneopts = "NUT" revision = "c5b7fccd204277076155f10851dad72b76a49317" version = "v0.8.0" [[projects]] branch = "master" + digest = "1:32d10bdfa8f09ecf13598324dba86ab891f11db3c538b6a34d1c3b5b99d7c36b" name = "github.com/prometheus/client_model" packages = ["go"] + pruneopts = "NUT" revision = "99fa1f4be8e564e8a6b613da7fa6f46c9edafc6c" [[projects]] branch = "master" + digest = "1:ce98e83b2b9486b6a9ce5e44fd4097c64e8f2f0eaa6c5041a8f12d3aaa5c17b3" name = "github.com/prometheus/common" packages = [ "expfmt", "internal/bitbucket.org/ww/goautoneg", "log", "model", - "version" + "version", ] + pruneopts = "NUT" revision = "e4aa40a9169a88835b849a6efb71e05dc04b88f0" [[projects]] branch = "master" + digest = "1:61a95e8d3e39e94207fba1b56d3c2182a356a1e41017aa647f523ae964b6bb0c" name = "github.com/prometheus/procfs" packages = [ ".", "internal/util", "nfs", - "xfs" + "xfs", ] + pruneopts = "NUT" revision = "54d17b57dd7d4a3aa092476596b3f8a933bde349" [[projects]] + digest = "1:6989062eb7ccf25cf38bf4fe3dba097ee209f896cda42cefdca3927047bef7b6" name = "github.com/sirupsen/logrus" packages = ["."] + pruneopts = "NUT" revision = "c155da19408a8799da419ed3eeb0cb5db0ad5dbc" version = "v1.0.5" [[projects]] branch = "master" + digest = "1:3f3a05ae0b95893d90b9b3b5afdb79a9b3d96e4e36e099d841ae602e4aca0da8" name = "golang.org/x/crypto" packages = ["ssh/terminal"] + pruneopts = "NUT" revision = "182114d582623c1caa54f73de9c7224e23a48487" [[projects]] branch = "master" + digest = "1:ea69008276e11262595a1f9a279ffd51d93e21c32c13b0f81856e962c6f607dd" name = "golang.org/x/sys" packages = [ "unix", "windows", "windows/registry", "windows/svc", - "windows/svc/eventlog" + "windows/svc/eventlog", ] + pruneopts = "NUT" revision = "8c0ece68c28377f4c326d85b94f8df0dace46f80" [[projects]] + digest = "1:22b2dee6f30bc8601f087449a2a819df8388e54e9547349c658f14d8f8c590f2" name = "gopkg.in/alecthomas/kingpin.v2" packages = ["."] + pruneopts = "NUT" revision = "947dcec5ba9c011838740e680966fd7087a71d0d" version = "v2.2.6" [solve-meta] analyzer-name = "dep" analyzer-version = 1 - inputs-digest = "01d9c528210a99a08cc65af3a40d23a31df0c00193639751917ea1adb7d1ee1c" + input-imports = [ + "github.com/StackExchange/wmi", + "github.com/dimchansky/utfbom", + "github.com/prometheus/client_golang/prometheus", + "github.com/prometheus/client_golang/prometheus/promhttp", + "github.com/prometheus/client_model/go", + "github.com/prometheus/common/expfmt", + "github.com/prometheus/common/log", + "github.com/prometheus/common/version", + "golang.org/x/sys/windows/registry", + "golang.org/x/sys/windows/svc", + "gopkg.in/alecthomas/kingpin.v2", + ] solver-name = "gps-cdcl" solver-version = 1 diff --git a/collector/textfile.go b/collector/textfile.go index e3fdf094..02cb7a40 100644 --- a/collector/textfile.go +++ b/collector/textfile.go @@ -25,6 +25,7 @@ import ( "strings" "time" + "github.com/dimchansky/utfbom" "github.com/prometheus/client_golang/prometheus" dto "github.com/prometheus/client_model/go" "github.com/prometheus/common/expfmt" @@ -236,7 +237,8 @@ fileLoop: continue } var parser expfmt.TextParser - parsedFamilies, err := parser.TextToMetricFamilies(carriageReturnFilteringReader{r: file}) + r := utfbom.SkipOnly(carriageReturnFilteringReader{r: file}) + parsedFamilies, err := parser.TextToMetricFamilies(r) file.Close() if err != nil { log.Errorf("Error parsing %q: %v", path, err) diff --git a/vendor/github.com/alecthomas/template/README.md b/vendor/github.com/alecthomas/template/README.md deleted file mode 100644 index ef6a8ee3..00000000 --- a/vendor/github.com/alecthomas/template/README.md +++ /dev/null @@ -1,25 +0,0 @@ -# Go's `text/template` package with newline elision - -This is a fork of Go 1.4's [text/template](http://golang.org/pkg/text/template/) package with one addition: a backslash immediately after a closing delimiter will delete all subsequent newlines until a non-newline. - -eg. - -``` -{{if true}}\ -hello -{{end}}\ -``` - -Will result in: - -``` -hello\n -``` - -Rather than: - -``` -\n -hello\n -\n -``` diff --git a/vendor/github.com/alecthomas/units/README.md b/vendor/github.com/alecthomas/units/README.md deleted file mode 100644 index bee884e3..00000000 --- a/vendor/github.com/alecthomas/units/README.md +++ /dev/null @@ -1,11 +0,0 @@ -# Units - Helpful unit multipliers and functions for Go - -The goal of this package is to have functionality similar to the [time](http://golang.org/pkg/time/) package. - -It allows for code like this: - -```go -n, err := ParseBase2Bytes("1KB") -// n == 1024 -n = units.Mebibyte * 512 -``` diff --git a/vendor/github.com/dimchansky/utfbom/LICENSE b/vendor/github.com/dimchansky/utfbom/LICENSE new file mode 100644 index 00000000..8dada3ed --- /dev/null +++ b/vendor/github.com/dimchansky/utfbom/LICENSE @@ -0,0 +1,201 @@ + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "{}" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright {yyyy} {name of copyright owner} + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. diff --git a/vendor/github.com/dimchansky/utfbom/utfbom.go b/vendor/github.com/dimchansky/utfbom/utfbom.go new file mode 100644 index 00000000..648184a1 --- /dev/null +++ b/vendor/github.com/dimchansky/utfbom/utfbom.go @@ -0,0 +1,174 @@ +// Package utfbom implements the detection of the BOM (Unicode Byte Order Mark) and removing as necessary. +// It wraps an io.Reader object, creating another object (Reader) that also implements the io.Reader +// interface but provides automatic BOM checking and removing as necessary. +package utfbom + +import ( + "errors" + "io" +) + +// Encoding is type alias for detected UTF encoding. +type Encoding int + +// Constants to identify detected UTF encodings. +const ( + // Unknown encoding, returned when no BOM was detected + Unknown Encoding = iota + + // UTF8, BOM bytes: EF BB BF + UTF8 + + // UTF-16, big-endian, BOM bytes: FE FF + UTF16BigEndian + + // UTF-16, little-endian, BOM bytes: FF FE + UTF16LittleEndian + + // UTF-32, big-endian, BOM bytes: 00 00 FE FF + UTF32BigEndian + + // UTF-32, little-endian, BOM bytes: FF FE 00 00 + UTF32LittleEndian +) + +const maxConsecutiveEmptyReads = 100 + +// Skip creates Reader which automatically detects BOM (Unicode Byte Order Mark) and removes it as necessary. +// It also returns the encoding detected by the BOM. +// If the detected encoding is not needed, you can call the SkipOnly function. +func Skip(rd io.Reader) (*Reader, Encoding) { + // Is it already a Reader? + b, ok := rd.(*Reader) + if ok { + return b, Unknown + } + + enc, left, err := detectUtf(rd) + return &Reader{ + rd: rd, + buf: left, + err: err, + }, enc +} + +// SkipOnly creates Reader which automatically detects BOM (Unicode Byte Order Mark) and removes it as necessary. +func SkipOnly(rd io.Reader) *Reader { + r, _ := Skip(rd) + return r +} + +// Reader implements automatic BOM (Unicode Byte Order Mark) checking and +// removing as necessary for an io.Reader object. +type Reader struct { + rd io.Reader // reader provided by the client + buf []byte // buffered data + err error // last error +} + +// Read is an implementation of io.Reader interface. +// The bytes are taken from the underlying Reader, but it checks for BOMs, removing them as necessary. +func (r *Reader) Read(p []byte) (n int, err error) { + if len(p) == 0 { + return 0, nil + } + + if r.buf == nil { + if r.err != nil { + return 0, r.readErr() + } + + return r.rd.Read(p) + } + + // copy as much as we can + n = copy(p, r.buf) + r.buf = nilIfEmpty(r.buf[n:]) + return n, nil +} + +func (r *Reader) readErr() error { + err := r.err + r.err = nil + return err +} + +var errNegativeRead = errors.New("utfbom: reader returned negative count from Read") + +func detectUtf(rd io.Reader) (enc Encoding, buf []byte, err error) { + buf, err = readBOM(rd) + + if len(buf) >= 4 { + if isUTF32BigEndianBOM4(buf) { + return UTF32BigEndian, nilIfEmpty(buf[4:]), err + } + if isUTF32LittleEndianBOM4(buf) { + return UTF32LittleEndian, nilIfEmpty(buf[4:]), err + } + } + + if len(buf) > 2 && isUTF8BOM3(buf) { + return UTF8, nilIfEmpty(buf[3:]), err + } + + if (err != nil && err != io.EOF) || (len(buf) < 2) { + return Unknown, nilIfEmpty(buf), err + } + + if isUTF16BigEndianBOM2(buf) { + return UTF16BigEndian, nilIfEmpty(buf[2:]), err + } + if isUTF16LittleEndianBOM2(buf) { + return UTF16LittleEndian, nilIfEmpty(buf[2:]), err + } + + return Unknown, nilIfEmpty(buf), err +} + +func readBOM(rd io.Reader) (buf []byte, err error) { + const maxBOMSize = 4 + var bom [maxBOMSize]byte // used to read BOM + + // read as many bytes as possible + for nEmpty, n := 0, 0; err == nil && len(buf) < maxBOMSize; buf = bom[:len(buf)+n] { + if n, err = rd.Read(bom[len(buf):]); n < 0 { + panic(errNegativeRead) + } + if n > 0 { + nEmpty = 0 + } else { + nEmpty++ + if nEmpty >= maxConsecutiveEmptyReads { + err = io.ErrNoProgress + } + } + } + return +} + +func isUTF32BigEndianBOM4(buf []byte) bool { + return buf[0] == 0x00 && buf[1] == 0x00 && buf[2] == 0xFE && buf[3] == 0xFF +} + +func isUTF32LittleEndianBOM4(buf []byte) bool { + return buf[0] == 0xFF && buf[1] == 0xFE && buf[2] == 0x00 && buf[3] == 0x00 +} + +func isUTF8BOM3(buf []byte) bool { + return buf[0] == 0xEF && buf[1] == 0xBB && buf[2] == 0xBF +} + +func isUTF16BigEndianBOM2(buf []byte) bool { + return buf[0] == 0xFE && buf[1] == 0xFF +} + +func isUTF16LittleEndianBOM2(buf []byte) bool { + return buf[0] == 0xFF && buf[1] == 0xFE +} + +func nilIfEmpty(buf []byte) (res []byte) { + if len(buf) > 0 { + res = buf + } + return +} diff --git a/vendor/gopkg.in/alecthomas/kingpin.v2/README.md b/vendor/gopkg.in/alecthomas/kingpin.v2/README.md deleted file mode 100644 index cd4edeb6..00000000 --- a/vendor/gopkg.in/alecthomas/kingpin.v2/README.md +++ /dev/null @@ -1,674 +0,0 @@ -# Kingpin - A Go (golang) command line and flag parser -[![](https://godoc.org/github.com/alecthomas/kingpin?status.svg)](http://godoc.org/github.com/alecthomas/kingpin) [![Build Status](https://travis-ci.org/alecthomas/kingpin.svg?branch=master)](https://travis-ci.org/alecthomas/kingpin) [![Gitter chat](https://badges.gitter.im/alecthomas.png)](https://gitter.im/alecthomas/Lobby) - - - - - -- [Overview](#overview) -- [Features](#features) -- [User-visible changes between v1 and v2](#user-visible-changes-between-v1-and-v2) - - [Flags can be used at any point after their definition.](#flags-can-be-used-at-any-point-after-their-definition) - - [Short flags can be combined with their parameters](#short-flags-can-be-combined-with-their-parameters) -- [API changes between v1 and v2](#api-changes-between-v1-and-v2) -- [Versions](#versions) - - [V2 is the current stable version](#v2-is-the-current-stable-version) - - [V1 is the OLD stable version](#v1-is-the-old-stable-version) -- [Change History](#change-history) -- [Examples](#examples) - - [Simple Example](#simple-example) - - [Complex Example](#complex-example) -- [Reference Documentation](#reference-documentation) - - [Displaying errors and usage information](#displaying-errors-and-usage-information) - - [Sub-commands](#sub-commands) - - [Custom Parsers](#custom-parsers) - - [Repeatable flags](#repeatable-flags) - - [Boolean Values](#boolean-values) - - [Default Values](#default-values) - - [Place-holders in Help](#place-holders-in-help) - - [Consuming all remaining arguments](#consuming-all-remaining-arguments) - - [Bash/ZSH Shell Completion](#bashzsh-shell-completion) - - [Supporting -h for help](#supporting--h-for-help) - - [Custom help](#custom-help) - - - -## Overview - -Kingpin is a [fluent-style](http://en.wikipedia.org/wiki/Fluent_interface), -type-safe command-line parser. It supports flags, nested commands, and -positional arguments. - -Install it with: - - $ go get gopkg.in/alecthomas/kingpin.v2 - -It looks like this: - -```go -var ( - verbose = kingpin.Flag("verbose", "Verbose mode.").Short('v').Bool() - name = kingpin.Arg("name", "Name of user.").Required().String() -) - -func main() { - kingpin.Parse() - fmt.Printf("%v, %s\n", *verbose, *name) -} -``` - -More [examples](https://github.com/alecthomas/kingpin/tree/master/_examples) are available. - -Second to parsing, providing the user with useful help is probably the most -important thing a command-line parser does. Kingpin tries to provide detailed -contextual help if `--help` is encountered at any point in the command line -(excluding after `--`). - -## Features - -- Help output that isn't as ugly as sin. -- Fully [customisable help](#custom-help), via Go templates. -- Parsed, type-safe flags (`kingpin.Flag("f", "help").Int()`) -- Parsed, type-safe positional arguments (`kingpin.Arg("a", "help").Int()`). -- Parsed, type-safe, arbitrarily deep commands (`kingpin.Command("c", "help")`). -- Support for required flags and required positional arguments (`kingpin.Flag("f", "").Required().Int()`). -- Support for arbitrarily nested default commands (`command.Default()`). -- Callbacks per command, flag and argument (`kingpin.Command("c", "").Action(myAction)`). -- POSIX-style short flag combining (`-a -b` -> `-ab`). -- Short-flag+parameter combining (`-a parm` -> `-aparm`). -- Read command-line from files (`@`). -- Automatically generate man pages (`--help-man`). - -## User-visible changes between v1 and v2 - -### Flags can be used at any point after their definition. - -Flags can be specified at any point after their definition, not just -*immediately after their associated command*. From the chat example below, the -following used to be required: - -``` -$ chat --server=chat.server.com:8080 post --image=~/Downloads/owls.jpg pics -``` - -But the following will now work: - -``` -$ chat post --server=chat.server.com:8080 --image=~/Downloads/owls.jpg pics -``` - -### Short flags can be combined with their parameters - -Previously, if a short flag was used, any argument to that flag would have to -be separated by a space. That is no longer the case. - -## API changes between v1 and v2 - -- `ParseWithFileExpansion()` is gone. The new parser directly supports expanding `@`. -- Added `FatalUsage()` and `FatalUsageContext()` for displaying an error + usage and terminating. -- `Dispatch()` renamed to `Action()`. -- Added `ParseContext()` for parsing a command line into its intermediate context form without executing. -- Added `Terminate()` function to override the termination function. -- Added `UsageForContextWithTemplate()` for printing usage via a custom template. -- Added `UsageTemplate()` for overriding the default template to use. Two templates are included: - 1. `DefaultUsageTemplate` - default template. - 2. `CompactUsageTemplate` - compact command template for larger applications. - -## Versions - -Kingpin uses [gopkg.in](https://gopkg.in/alecthomas/kingpin) for versioning. - -The current stable version is [gopkg.in/alecthomas/kingpin.v2](https://gopkg.in/alecthomas/kingpin.v2). The previous version, [gopkg.in/alecthomas/kingpin.v1](https://gopkg.in/alecthomas/kingpin.v1), is deprecated and in maintenance mode. - -### [V2](https://gopkg.in/alecthomas/kingpin.v2) is the current stable version - -Installation: - -```sh -$ go get gopkg.in/alecthomas/kingpin.v2 -``` - -### [V1](https://gopkg.in/alecthomas/kingpin.v1) is the OLD stable version - -Installation: - -```sh -$ go get gopkg.in/alecthomas/kingpin.v1 -``` - -## Change History - -- *2015-09-19* -- Stable v2.1.0 release. - - Added `command.Default()` to specify a default command to use if no other - command matches. This allows for convenient user shortcuts. - - Exposed `HelpFlag` and `VersionFlag` for further customisation. - - `Action()` and `PreAction()` added and both now support an arbitrary - number of callbacks. - - `kingpin.SeparateOptionalFlagsUsageTemplate`. - - `--help-long` and `--help-man` (hidden by default) flags. - - Flags are "interspersed" by default, but can be disabled with `app.Interspersed(false)`. - - Added flags for all simple builtin types (int8, uint16, etc.) and slice variants. - - Use `app.Writer(os.Writer)` to specify the default writer for all output functions. - - Dropped `os.Writer` prefix from all printf-like functions. - -- *2015-05-22* -- Stable v2.0.0 release. - - Initial stable release of v2.0.0. - - Fully supports interspersed flags, commands and arguments. - - Flags can be present at any point after their logical definition. - - Application.Parse() terminates if commands are present and a command is not parsed. - - Dispatch() -> Action(). - - Actions are dispatched after all values are populated. - - Override termination function (defaults to os.Exit). - - Override output stream (defaults to os.Stderr). - - Templatised usage help, with default and compact templates. - - Make error/usage functions more consistent. - - Support argument expansion from files by default (with @). - - Fully public data model is available via .Model(). - - Parser has been completely refactored. - - Parsing and execution has been split into distinct stages. - - Use `go generate` to generate repeated flags. - - Support combined short-flag+argument: -fARG. - -- *2015-01-23* -- Stable v1.3.4 release. - - Support "--" for separating flags from positional arguments. - - Support loading flags from files (ParseWithFileExpansion()). Use @FILE as an argument. - - Add post-app and post-cmd validation hooks. This allows arbitrary validation to be added. - - A bunch of improvements to help usage and formatting. - - Support arbitrarily nested sub-commands. - -- *2014-07-08* -- Stable v1.2.0 release. - - Pass any value through to `Strings()` when final argument. - Allows for values that look like flags to be processed. - - Allow `--help` to be used with commands. - - Support `Hidden()` flags. - - Parser for [units.Base2Bytes](https://github.com/alecthomas/units) - type. Allows for flags like `--ram=512MB` or `--ram=1GB`. - - Add an `Enum()` value, allowing only one of a set of values - to be selected. eg. `Flag(...).Enum("debug", "info", "warning")`. - -- *2014-06-27* -- Stable v1.1.0 release. - - Bug fixes. - - Always return an error (rather than panicing) when misconfigured. - - `OpenFile(flag, perm)` value type added, for finer control over opening files. - - Significantly improved usage formatting. - -- *2014-06-19* -- Stable v1.0.0 release. - - Support [cumulative positional](#consuming-all-remaining-arguments) arguments. - - Return error rather than panic when there are fatal errors not caught by - the type system. eg. when a default value is invalid. - - Use gokpg.in. - -- *2014-06-10* -- Place-holder streamlining. - - Renamed `MetaVar` to `PlaceHolder`. - - Removed `MetaVarFromDefault`. Kingpin now uses [heuristics](#place-holders-in-help) - to determine what to display. - -## Examples - -### Simple Example - -Kingpin can be used for simple flag+arg applications like so: - -``` -$ ping --help -usage: ping [] [] - -Flags: - --debug Enable debug mode. - --help Show help. - -t, --timeout=5s Timeout waiting for ping. - -Args: - IP address to ping. - [] Number of packets to send -$ ping 1.2.3.4 5 -Would ping: 1.2.3.4 with timeout 5s and count 0 -``` - -From the following source: - -```go -package main - -import ( - "fmt" - - "gopkg.in/alecthomas/kingpin.v2" -) - -var ( - debug = kingpin.Flag("debug", "Enable debug mode.").Bool() - timeout = kingpin.Flag("timeout", "Timeout waiting for ping.").Default("5s").OverrideDefaultFromEnvar("PING_TIMEOUT").Short('t').Duration() - ip = kingpin.Arg("ip", "IP address to ping.").Required().IP() - count = kingpin.Arg("count", "Number of packets to send").Int() -) - -func main() { - kingpin.Version("0.0.1") - kingpin.Parse() - fmt.Printf("Would ping: %s with timeout %s and count %d\n", *ip, *timeout, *count) -} -``` - -### Complex Example - -Kingpin can also produce complex command-line applications with global flags, -subcommands, and per-subcommand flags, like this: - -``` -$ chat --help -usage: chat [] [] [ ...] - -A command-line chat application. - -Flags: - --help Show help. - --debug Enable debug mode. - --server=127.0.0.1 Server address. - -Commands: - help [] - Show help for a command. - - register - Register a new user. - - post [] [] - Post a message to a channel. - -$ chat help post -usage: chat [] post [] [] - -Post a message to a channel. - -Flags: - --image=IMAGE Image to post. - -Args: - Channel to post to. - [] Text to post. - -$ chat post --image=~/Downloads/owls.jpg pics -... -``` - -From this code: - -```go -package main - -import ( - "os" - "strings" - "gopkg.in/alecthomas/kingpin.v2" -) - -var ( - app = kingpin.New("chat", "A command-line chat application.") - debug = app.Flag("debug", "Enable debug mode.").Bool() - serverIP = app.Flag("server", "Server address.").Default("127.0.0.1").IP() - - register = app.Command("register", "Register a new user.") - registerNick = register.Arg("nick", "Nickname for user.").Required().String() - registerName = register.Arg("name", "Name of user.").Required().String() - - post = app.Command("post", "Post a message to a channel.") - postImage = post.Flag("image", "Image to post.").File() - postChannel = post.Arg("channel", "Channel to post to.").Required().String() - postText = post.Arg("text", "Text to post.").Strings() -) - -func main() { - switch kingpin.MustParse(app.Parse(os.Args[1:])) { - // Register user - case register.FullCommand(): - println(*registerNick) - - // Post message - case post.FullCommand(): - if *postImage != nil { - } - text := strings.Join(*postText, " ") - println("Post:", text) - } -} -``` - -## Reference Documentation - -### Displaying errors and usage information - -Kingpin exports a set of functions to provide consistent errors and usage -information to the user. - -Error messages look something like this: - - : error: - -The functions on `Application` are: - -Function | Purpose ----------|-------------- -`Errorf(format, args)` | Display a printf formatted error to the user. -`Fatalf(format, args)` | As with Errorf, but also call the termination handler. -`FatalUsage(format, args)` | As with Fatalf, but also print contextual usage information. -`FatalUsageContext(context, format, args)` | As with Fatalf, but also print contextual usage information from a `ParseContext`. -`FatalIfError(err, format, args)` | Conditionally print an error prefixed with format+args, then call the termination handler - -There are equivalent global functions in the kingpin namespace for the default -`kingpin.CommandLine` instance. - -### Sub-commands - -Kingpin supports nested sub-commands, with separate flag and positional -arguments per sub-command. Note that positional arguments may only occur after -sub-commands. - -For example: - -```go -var ( - deleteCommand = kingpin.Command("delete", "Delete an object.") - deleteUserCommand = deleteCommand.Command("user", "Delete a user.") - deleteUserUIDFlag = deleteUserCommand.Flag("uid", "Delete user by UID rather than username.") - deleteUserUsername = deleteUserCommand.Arg("username", "Username to delete.") - deletePostCommand = deleteCommand.Command("post", "Delete a post.") -) - -func main() { - switch kingpin.Parse() { - case "delete user": - case "delete post": - } -} -``` - -### Custom Parsers - -Kingpin supports both flag and positional argument parsers for converting to -Go types. For example, some included parsers are `Int()`, `Float()`, -`Duration()` and `ExistingFile()` (see [parsers.go](./parsers.go) for a complete list of included parsers). - -Parsers conform to Go's [`flag.Value`](http://godoc.org/flag#Value) -interface, so any existing implementations will work. - -For example, a parser for accumulating HTTP header values might look like this: - -```go -type HTTPHeaderValue http.Header - -func (h *HTTPHeaderValue) Set(value string) error { - parts := strings.SplitN(value, ":", 2) - if len(parts) != 2 { - return fmt.Errorf("expected HEADER:VALUE got '%s'", value) - } - (*http.Header)(h).Add(parts[0], parts[1]) - return nil -} - -func (h *HTTPHeaderValue) String() string { - return "" -} -``` - -As a convenience, I would recommend something like this: - -```go -func HTTPHeader(s Settings) (target *http.Header) { - target = &http.Header{} - s.SetValue((*HTTPHeaderValue)(target)) - return -} -``` - -You would use it like so: - -```go -headers = HTTPHeader(kingpin.Flag("header", "Add a HTTP header to the request.").Short('H')) -``` - -### Repeatable flags - -Depending on the `Value` they hold, some flags may be repeated. The -`IsCumulative() bool` function on `Value` tells if it's safe to call `Set()` -multiple times or if an error should be raised if several values are passed. - -The built-in `Value`s returning slices and maps, as well as `Counter` are -examples of `Value`s that make a flag repeatable. - -### Boolean values - -Boolean values are uniquely managed by Kingpin. Each boolean flag will have a negative complement: -`--` and `--no-`. - -### Default Values - -The default value is the zero value for a type. This can be overridden with -the `Default(value...)` function on flags and arguments. This function accepts -one or several strings, which are parsed by the value itself, so they *must* -be compliant with the format expected. - -### Place-holders in Help - -The place-holder value for a flag is the value used in the help to describe -the value of a non-boolean flag. - -The value provided to PlaceHolder() is used if provided, then the value -provided by Default() if provided, then finally the capitalised flag name is -used. - -Here are some examples of flags with various permutations: - - --name=NAME // Flag(...).String() - --name="Harry" // Flag(...).Default("Harry").String() - --name=FULL-NAME // flag(...).PlaceHolder("FULL-NAME").Default("Harry").String() - -### Consuming all remaining arguments - -A common command-line idiom is to use all remaining arguments for some -purpose. eg. The following command accepts an arbitrary number of -IP addresses as positional arguments: - - ./cmd ping 10.1.1.1 192.168.1.1 - -Such arguments are similar to [repeatable flags](#repeatable-flags), but for -arguments. Therefore they use the same `IsCumulative() bool` function on the -underlying `Value`, so the built-in `Value`s for which the `Set()` function -can be called several times will consume multiple arguments. - -To implement the above example with a custom `Value`, we might do something -like this: - -```go -type ipList []net.IP - -func (i *ipList) Set(value string) error { - if ip := net.ParseIP(value); ip == nil { - return fmt.Errorf("'%s' is not an IP address", value) - } else { - *i = append(*i, ip) - return nil - } -} - -func (i *ipList) String() string { - return "" -} - -func (i *ipList) IsCumulative() bool { - return true -} - -func IPList(s Settings) (target *[]net.IP) { - target = new([]net.IP) - s.SetValue((*ipList)(target)) - return -} -``` - -And use it like so: - -```go -ips := IPList(kingpin.Arg("ips", "IP addresses to ping.")) -``` - -### Bash/ZSH Shell Completion - -By default, all flags and commands/subcommands generate completions -internally. - -Out of the box, CLI tools using kingpin should be able to take advantage -of completion hinting for flags and commands. By specifying -`--completion-bash` as the first argument, your CLI tool will show -possible subcommands. By ending your argv with `--`, hints for flags -will be shown. - -To allow your end users to take advantage you must package a -`/etc/bash_completion.d` script with your distribution (or the equivalent -for your target platform/shell). An alternative is to instruct your end -user to source a script from their `bash_profile` (or equivalent). - -Fortunately Kingpin makes it easy to generate or source a script for use -with end users shells. `./yourtool --completion-script-bash` and -`./yourtool --completion-script-zsh` will generate these scripts for you. - -**Installation by Package** - -For the best user experience, you should bundle your pre-created -completion script with your CLI tool and install it inside -`/etc/bash_completion.d` (or equivalent). A good suggestion is to add -this as an automated step to your build pipeline, in the implementation -is improved for bug fixed. - -**Installation by `bash_profile`** - -Alternatively, instruct your users to add an additional statement to -their `bash_profile` (or equivalent): - -``` -eval "$(your-cli-tool --completion-script-bash)" -``` - -Or for ZSH - -``` -eval "$(your-cli-tool --completion-script-zsh)" -``` - -#### Additional API -To provide more flexibility, a completion option API has been -exposed for flags to allow user defined completion options, to extend -completions further than just EnumVar/Enum. - - -**Provide Static Options** - -When using an `Enum` or `EnumVar`, users are limited to only the options -given. Maybe we wish to hint possible options to the user, but also -allow them to provide their own custom option. `HintOptions` gives -this functionality to flags. - -``` -app := kingpin.New("completion", "My application with bash completion.") -app.Flag("port", "Provide a port to connect to"). - Required(). - HintOptions("80", "443", "8080"). - IntVar(&c.port) -``` - -**Provide Dynamic Options** -Consider the case that you needed to read a local database or a file to -provide suggestions. You can dynamically generate the options - -``` -func listHosts() []string { - // Provide a dynamic list of hosts from a hosts file or otherwise - // for bash completion. In this example we simply return static slice. - - // You could use this functionality to reach into a hosts file to provide - // completion for a list of known hosts. - return []string{"sshhost.example", "webhost.example", "ftphost.example"} -} - -app := kingpin.New("completion", "My application with bash completion.") -app.Flag("flag-1", "").HintAction(listHosts).String() -``` - -**EnumVar/Enum** -When using `Enum` or `EnumVar`, any provided options will be automatically -used for bash autocompletion. However, if you wish to provide a subset or -different options, you can use `HintOptions` or `HintAction` which will override -the default completion options for `Enum`/`EnumVar`. - - -**Examples** -You can see an in depth example of the completion API within -`examples/completion/main.go` - - -### Supporting -h for help - -`kingpin.CommandLine.HelpFlag.Short('h')` - -### Custom help - -Kingpin v2 supports templatised help using the text/template library (actually, [a fork](https://github.com/alecthomas/template)). - -You can specify the template to use with the [Application.UsageTemplate()](http://godoc.org/gopkg.in/alecthomas/kingpin.v2#Application.UsageTemplate) function. - -There are four included templates: `kingpin.DefaultUsageTemplate` is the default, -`kingpin.CompactUsageTemplate` provides a more compact representation for more complex command-line structures, -`kingpin.SeparateOptionalFlagsUsageTemplate` looks like the default template, but splits required -and optional command flags into separate lists, and `kingpin.ManPageTemplate` is used to generate man pages. - -See the above templates for examples of usage, and the the function [UsageForContextWithTemplate()](https://github.com/alecthomas/kingpin/blob/master/usage.go#L198) method for details on the context. - -#### Default help template - -``` -$ go run ./examples/curl/curl.go --help -usage: curl [] [ ...] - -An example implementation of curl. - -Flags: - --help Show help. - -t, --timeout=5s Set connection timeout. - -H, --headers=HEADER=VALUE - Add HTTP headers to the request. - -Commands: - help [...] - Show help. - - get url - Retrieve a URL. - - get file - Retrieve a file. - - post [] - POST a resource. -``` - -#### Compact help template - -``` -$ go run ./examples/curl/curl.go --help -usage: curl [] [ ...] - -An example implementation of curl. - -Flags: - --help Show help. - -t, --timeout=5s Set connection timeout. - -H, --headers=HEADER=VALUE - Add HTTP headers to the request. - -Commands: - help [...] - get [] - url - file - post [] -``` diff --git a/vendor/gopkg.in/alecthomas/kingpin.v2/values.json b/vendor/gopkg.in/alecthomas/kingpin.v2/values.json deleted file mode 100644 index 23c67448..00000000 --- a/vendor/gopkg.in/alecthomas/kingpin.v2/values.json +++ /dev/null @@ -1,25 +0,0 @@ -[ - {"type": "bool", "parser": "strconv.ParseBool(s)"}, - {"type": "string", "parser": "s, error(nil)", "format": "string(*f.v)", "plural": "Strings"}, - {"type": "uint", "parser": "strconv.ParseUint(s, 0, 64)", "plural": "Uints"}, - {"type": "uint8", "parser": "strconv.ParseUint(s, 0, 8)"}, - {"type": "uint16", "parser": "strconv.ParseUint(s, 0, 16)"}, - {"type": "uint32", "parser": "strconv.ParseUint(s, 0, 32)"}, - {"type": "uint64", "parser": "strconv.ParseUint(s, 0, 64)"}, - {"type": "int", "parser": "strconv.ParseFloat(s, 64)", "plural": "Ints"}, - {"type": "int8", "parser": "strconv.ParseInt(s, 0, 8)"}, - {"type": "int16", "parser": "strconv.ParseInt(s, 0, 16)"}, - {"type": "int32", "parser": "strconv.ParseInt(s, 0, 32)"}, - {"type": "int64", "parser": "strconv.ParseInt(s, 0, 64)"}, - {"type": "float64", "parser": "strconv.ParseFloat(s, 64)"}, - {"type": "float32", "parser": "strconv.ParseFloat(s, 32)"}, - {"name": "Duration", "type": "time.Duration", "no_value_parser": true}, - {"name": "IP", "type": "net.IP", "no_value_parser": true}, - {"name": "TCPAddr", "Type": "*net.TCPAddr", "plural": "TCPList", "no_value_parser": true}, - {"name": "ExistingFile", "Type": "string", "plural": "ExistingFiles", "no_value_parser": true}, - {"name": "ExistingDir", "Type": "string", "plural": "ExistingDirs", "no_value_parser": true}, - {"name": "ExistingFileOrDir", "Type": "string", "plural": "ExistingFilesOrDirs", "no_value_parser": true}, - {"name": "Regexp", "Type": "*regexp.Regexp", "parser": "regexp.Compile(s)"}, - {"name": "ResolvedIP", "Type": "net.IP", "parser": "resolveHost(s)", "help": "Resolve a hostname or IP to an IP."}, - {"name": "HexBytes", "Type": "[]byte", "parser": "hex.DecodeString(s)", "help": "Bytes as a hex string."} -]