Add ensure-file parser package.

cipd/client/cipd/ensure/doc.go

Index: cipd/client/cipd/ensure/doc.go
diff --git a/cipd/client/cipd/ensure/doc.go b/cipd/client/cipd/ensure/doc.go
new file mode 100644
index 0000000000000000000000000000000000000000..2647a973ac40c7a86a2f5908f6910d5cbb482420
--- /dev/null
+++ b/cipd/client/cipd/ensure/doc.go
@@ -0,0 +1,85 @@
+// Copyright 2017 The LUCI Authors. All rights reserved.
+// Use of this source code is governed under the Apache License, Version 2.0
+// that can be found in the LICENSE file.
+
+// Package ensure contains methods and types for interacting with the 'ensure
+// file format'.
+//
+// The format is used by the cipd client to describe the desired state of a cipd
+// installation. This states can be asserted with the cipd client 'ensure'
+// command. The state is essentialy a list of packages, their versions and their
+// installation subdirectories ("roots").
+//
+// Format Description
+//
+// The file is line-oriented. All statements fit on a single line.
+//
+// A line can be blank, a comment, a setting, a directive, or a package.
+//
+// A comment begins with a # and goes to the end of the line. It is ignored.
+//
+// Settings
+//
+// A setting looks like `$name value`. Settings are global and can only be set
+// once per file. The following settings are allowed:
+//   - ServiceURL is the url for the cipd service. It can be used in lieu of
+//     the -service-url command line parameter.
+//
+// Directives
+//
+// A directive looks like `@name value`. Directives are 'sticky' and apply until
+// the next same-name directive. The following directives are allowed:
+//   - Root allows you to change the root that packages are installed to.
+//     The root value is relative to the base of the cipd installation (the
+//     directory containing the .cipd folder). The value of Root before any
+//     @Root directives is "", or the base of the cipd installation.
+//
+// Package Definitions
+//
+// A package line looks like `<package_template> <version>`. Package templates
+// are cipd package names, with optional expansion parameters `${platform}` and
+// `${arch}`. These placeholders can appear anywhere in the package template
+// except for the first letter.  All other characters in the template are taken
+// verbatim.
+//
+// ${platform} will expand to one of the following, based on the value of this
+// client's runtime.GOOS value:
+//   * windows
+//   * mac
+//   * linux
+//
+// ${arch} will expand to one of the following, based on the value of this
+// client's runtime.GOARCH value:
+//   * 386
+//   * amd64
+//   * armv6l
+//
+// Both of these paramters also support the syntax ${var=possible,values}.
+// What this means is that the package line will be expanded if, and only if,
+// var equals one of the possible values. If that var does not match
+// a possible value, the line is ignored. This allows you to do, e.g.:
+//   path/to/package/${platform=windows}  windows_release
+//   path/to/package/${platform=linux}    linux_release
+//   # no version for mac
+//
+//   path/to/posix/tool/${platform=mac,linux}  some_tag:value
+//
+// That's all there is to it.
+//
+// Example
+//
+// Here is an example ensure file which demonstrates all the various features.
+//
+//   # This is an ensure file!
+//   $ServiceURL https://chrome-infra-packages.appspot.com/
+//
+//   # This is the cipd client itself
+//   infra/tools/cipd/${platform}-${arch}  latest
+//
+//   @Root python
+//   python/wheels/pip                           version:8.1.2
+//   python/wheels/coverage/${platform}-${arch}  version:4.1
+//
+//   @Root infra/support
+//   infra/some/other/package deadbeefdeadbeefdeadbeefdeadbeefdeadbeef
+package ensure