unify and recast "Cask name" & "title" as "token"

* "Canonical App Name" becomes "Simplified App Name" * devscript `cask_namer` renamed to `generate_cask_token` * doc file `CASK_NAMING_REFERENCE.md` renamed to `cask_token_reference.md` * DSL uses `"#{token}"` for interpolation instead of `"#{title}"` * documentation text * backend code (variables, method, class names) * error message text * tests * code comments * Cask comments * emphasize `tags :name` * doc: use "vendor" consistently instead of "developer" * doc: many man page argument descriptions were incorrect * incidental clarifications Many backend variables similar to `cask_name` or `cask` have been standardized to `cask_token`, `token`, etc, resolving a long- standing ambiguity in which variables named `cask` might contain a Cask instance or a string token. In many places the docs could be shortened from "Cask name" to simply "token", which is desirable because we use the term "Cask" in too many contexts.
2026-08-05 13:43:24 -07:00 · 2014-12-01 11:00:23 -05:00
parent 8c824963e3
commit a335d3b06d
49 changed files with 491 additions and 438 deletions
@@ -78,32 +78,30 @@ cask :v1 => 'firefox' do
 end
 ```

-### Naming the Cask
+### Generating a Token for the Cask

-We try to maintain consistent naming for the benefit of our users.
+The Cask **token** is the mnemonic string people will use to interact with
+the Cask via `brew cask install`, `brew cask search`, etc.  The name of the
+Cask **file** is simply the token with the extension `.rb` appended.

-The Cask **name** is the string people will use to interact with the Cask
-via `brew cask install`, `brew cask search`, etc.  The Cask **file**
-is simply the Cask name with the extension `.rb` appended.
-
-The easiest way to name a Cask is to run this command:
+The easiest way to generate a token for a Cask is to run this command:
 ```bash
-$ "$(brew --repository)/Library/Taps/caskroom/homebrew-cask/developer/bin/cask_namer" '/full/path/to/new/software.app'
+$ "$(brew --repository)/Library/Taps/caskroom/homebrew-cask/developer/bin/generate_cask_token" '/full/path/to/new/software.app'
 ```

 If the software you wish to Cask is not installed, or does not have an
 associated App bundle, just give the full proper name of the software
 instead of a pathname:
 ```bash
-$ "$(brew --repository)/Library/Taps/caskroom/homebrew-cask/developer/bin/cask_namer" 'Google Chrome'
+$ "$(brew --repository)/Library/Taps/caskroom/homebrew-cask/developer/bin/generate_cask_token" 'Google Chrome'
 ```

-If the `cask_namer` script does not work for you, see [Cask Naming Details](#cask-naming-details).
+If the `generate_cask_token` script does not work for you, see [Cask Token Details](#cask-token-details).


 ### The `brew cask create` Command

-Once you know the name for your Cask, create it with the handy-dandy
+Once you know the token, create your Cask with the handy-dandy
 `brew cask create` command.

 ```bash
@@ -213,16 +211,17 @@ When possible, it is best to use a download URL from the original developer
 or vendor, rather than an aggregator such as macupdate.com.


-### Cask Naming Details
+### Cask Token Details

-If a Cask name conflicts with an already-existing Cask, authors should manually
-make the new Cask name unique by prepending the vendor name.  Example:
+If a token conflicts with an already-existing Cask, authors should manually
+make the new token unique by prepending the vendor name.  Example:
 [unison.rb](../Casks/unison.rb) and [panic-unison.rb](../Casks/panic-unison.rb).

-If possible, avoid creating Cask names which differ only by the placement of
+If possible, avoid creating tokens which differ only by the placement of
 hyphens.

-To name a Cask manually, or to learn about exceptions for unusual cases, see [CASK_NAMING_REFERENCE.md](doc/CASK_NAMING_REFERENCE.md).
+To generate a token manually, or to learn about exceptions for unusual cases,
+see [CASK_TOKEN_REFERENCE.md](doc/CASK_TOKEN_REFERENCE.md).


 ### Archives With Subfolders
@@ -1,6 +1,6 @@
 cask :v1 => 'python3' do
-  # note: "3" is a trailing version number on the Cask name, which
-  # breaks our own naming standards, for consistency with Homebrew
+  # note: "3" is a trailing version number on the Cask token, which
+  # breaks our own token conventions, for consistency with Homebrew
  version '3.4.2'
  sha256 '5a4edfac31efd4ecd2efb4cb7203c0c36e488f1d0a20755b674b04dcb3c21e1b'

@@ -28,8 +28,9 @@ commands are:

 ## Searching for Casks

-The `brew cask search` command accepts a series of substring arguments.
-Let's see if there's a Cask for Google Chrome:
+The `brew cask search` command accepts a series of substring arguments,
+and returns tokens representing matching Casks.  Let's see if there's a
+Cask for Google Chrome:

 ```bash
 $ brew cask search chrome
@@ -45,7 +46,7 @@ $ brew cask search

 ## Installing Casks

-The command `brew cask install` accepts a Cask name as returned by `brew cask search`.
+The command `brew cask install` accepts a Cask token as returned by `brew cask search`.
 Let's try to install Google Chrome:

 ```bash
@@ -163,7 +164,7 @@ $ brew tap <tap_name>
 after which, Casks from the new Tap will be available to `search` or `install` just like Casks from the main Tap.
 `brew update` will automatically keep your new Tap up to date.

-You may also specify a fully-qualified Cask name (which includes the Tap) for any `brew cask` command.  This will implicitly add the Tap if you have not previously added it with `brew tap`:
+You may also specify a fully-qualified Cask token (which includes the Tap) for any `brew cask` command.  This will implicitly add the Tap if you have not previously added it with `brew tap`:

 ```bash
 $ brew cask install caskroom/fonts/font-symbola
@@ -230,19 +231,20 @@ google-chrome

 ## Other Ways to Specify a Cask

-Most `brew cask` commands can accept a Cask name as an argument. As described
-above, a Cask name on the command line can take the form of:
+Most `brew cask` commands can accept a Cask token as an argument. As described
+above, the token on the command line can take the form of:

-* a Cask name as returned by `brew cask search`, _eg_: `google-chrome`
-* a fully-qualified Cask name which includes the Tap, _eg_: `caskroom/fonts/font-symbola`
+ * a token as returned by `brew cask search`, _eg_: `google-chrome`
+ * a fully-qualified token which includes the Tap, _eg_: `caskroom/fonts/font-symbola`

-`brew cask` also accepts three other forms for Cask names:
+`brew cask` also accepts three other forms as arguments

-* a path to a Cask file, _eg_: `/usr/local/Cellar/brew-cask/0.25.0/Casks/google-chrome.rb`
-* a `curl`-retrievable URI to a Cask file, _eg_: `https://raw.github.com/caskroom/homebrew-cask/f54bbfaae0f2fa7210484f46313a459cb8a14d2f/Casks/google-chrome.rb`
-* a file in the current working directory, _eg_: `my-modfied-google-chrome.rb`.  Note
-  that Tapped Casks names will be preferred over this form.  To force the use of a Cask
-  file in the current directory, specify a pathname with slashes, _eg_: `./google-chrome.rb`.
+ * a path to a Cask file, _eg_: `/usr/local/Cellar/brew-cask/0.25.0/Casks/google-chrome.rb`
+ * a `curl`-retrievable URI to a Cask file, _eg_: `https://raw.github.com/caskroom/homebrew-cask/f54bbfaae0f2fa7210484f46313a459cb8a14d2f/Casks/google-chrome.rb`
+ * a file in the current working directory, _eg_: `my-modfied-google-chrome.rb`.  Note
+   that matching Tapped Cask tokens will be preferred over this form when there is a
+   conflict.  To force the use of a Cask file in the current directory, specify a
+   pathname with slashes, _eg_: `./google-chrome.rb`.

 The last three forms are intended for users who wish to maintain private Casks.

@@ -1,6 +1,6 @@
 #!/usr/bin/env ruby
 #
-# cask_namer
+# generate_cask_token
 #
 # todo:
 #
@@ -45,18 +45,23 @@ CASK_FILE_EXTENSION = '.rb'

 # Hardcode App names that cannot be transformed automatically.
 # Example: in "x48.app", "x48" is not a version number.
-# The value in the hash should be a valid Cask name.
+# The value in the hash should be a valid Cask token.
 APP_EXCEPTION_PATS = {
+                      # looks like a trailing version, but is not.
                      %r{\Aiterm\Z}i               => 'iterm2',
+                      %r{\Aiterm2\Z}i              => 'iterm2',
                      %r{\Apgadmin3\Z}i            => 'pgadmin3',
                      %r{\Ax48\Z}i                 => 'x48',
                      %r{\Avitamin-r[\s\d\.]*\Z}i  => 'vitamin-r',
                      %r{\Aimagealpha\Z}i          => 'imagealpha',
+                      # upstream is in the midst of changing branding
+                      %r{\Abitcoin-?qt\Z}i         => 'bitcoin-core',
+                      # "mac" cannot be separated from the name because it is in an English phrase
                      %r{\Aplayonmac\Z}i           => 'playonmac',
+                      %r{\Acleanmymac[\s\d\.]*\Z}i => 'cleanmymac',
+                      # arguably we should not have kept these two exceptions
                      %r{\Akismac\Z}i              => 'kismac',
                      %r{\Avoicemac\Z}i            => 'voicemac',
-                      %r{\Acleanmymac[\s\d\.]*\Z}i => 'cleanmymac',
-                      %r{\Abitcoin-?qt\Z}i         => 'bitcoin-core',
                     }

 # Preserve trailing patterns on App names that could be mistaken
@@ -265,14 +270,14 @@ class AppName < String
    app_name.clean_up_vertical_tabs
  end

-  def canonical
-    return @canonical if @canonical
-    @canonical = self.english_from_app_bundle
-                     .basename
-                     .decompose_to_ascii
-                     .remove_extension
-    name_exception = @canonical.hardcoded_exception
-    @canonical = name_exception ? name_exception : @canonical.remove_trailing_strings_and_versions
+  def simplified
+    return @simplified if @simplified
+    @simplified = self.english_from_app_bundle
+                      .basename
+                      .decompose_to_ascii
+                      .remove_extension
+    @simplified = @simplified.hardcoded_exception || @simplified.remove_trailing_strings_and_versions
+    @simplified
  end
 end

@@ -321,9 +326,9 @@ class CaskFileName < String
    self.sub(/#{escaped_cask_file_extension}\Z/i, '')
  end

-  def from_canonical_name
-    return @from_canonical_name if @from_canonical_name
-    @from_canonical_name = if APP_EXCEPTION_PATS.rassoc(self.remove_extension)
+  def from_simplified_app_name
+    return @from_simplified_app_name if @from_simplified_app_name
+    @from_simplified_app_name = if APP_EXCEPTION_PATS.rassoc(self.remove_extension)
      self.remove_extension
    else
      self.remove_extension
@@ -336,8 +341,8 @@ class CaskFileName < String
          .delete_hyphens_before_numbers
          .spell_out_leading_numbers
    end
-    raise "Could not determine Cask name" unless @from_canonical_name.length > 0
-    @from_canonical_name.add_extension
+    raise "Could not determine Simplified App name" unless @from_simplified_app_name.length > 0
+    @from_simplified_app_name.add_extension
  end
 end

@@ -364,24 +369,24 @@ def escaped_cask_file_extension
  @escaped_cask_file_extension ||= Regexp.escape(CASK_FILE_EXTENSION)
 end

-def canonical_name
-  @canonical_name ||= AppName.new("#{ARGV.first}".force_encoding("UTF-8")).canonical
+def simplified_app_name
+  @simplified_app_name ||= AppName.new("#{ARGV.first}".force_encoding("UTF-8")).simplified
 end

 def cask_file_name
-  @cask_file_name ||= CaskFileName.new(canonical_name).from_canonical_name
+  @cask_file_name ||= CaskFileName.new(simplified_app_name).from_simplified_app_name
 end

-def cask_name
-  @cask_name ||= cask_file_name.remove_extension
+def cask_token
+  @cask_token ||= cask_file_name.remove_extension
 end

 def warnings
  return @warnings if @warnings
  @warnings = []
-  unless APP_EXCEPTION_PATS.rassoc(cask_name)
-    if %r{\d}.match(cask_name)
-      @warnings.push "WARNING: '#{cask_name}' contains digits. Digits which are version numbers should be removed."
+  unless APP_EXCEPTION_PATS.rassoc(cask_token)
+    if %r{\d}.match(cask_token)
+      @warnings.push "WARNING: '#{cask_token}' contains digits. Digits which are version numbers should be removed."
    end
  end
  filename = project_root.join('Casks', cask_file_name)
@@ -392,10 +397,10 @@ def warnings
 end

 def report
-  puts "Proposed canonical App name: #{canonical_name}" if $debug
-  puts "Proposed Cask name:          #{cask_name}"
-  puts "Proposed file name:          #{cask_file_name}"
-  puts "First Line of Cask:          cask :v1 => '#{cask_name}' do"
+  puts "Proposed Simplified App name: #{simplified_app_name}" if $debug
+  puts "Proposed token:               #{cask_token}"
+  puts "Proposed file name:           #{cask_file_name}"
+  puts "Cask Header Line:             cask :v1 => '#{cask_token}' do"
  if warnings.length > 0
    STDERR.puts "\n"
    STDERR.puts warnings
@@ -409,12 +414,12 @@ end
 ###

 usage = <<-EOS
-Usage: cask_namer [ -debug ] <application.app>
+Usage: generate_cask_token [ -debug ] <application.app>

-Given an Application name or a path to an Application,
-propose a Cask name, filename and class name.
+Given an Application name or a path to an Application, propose a
+Cask token, filename, and header line.

-With -debug, provide the internal Canonical App Name.
+With -debug, also provide the internal "Simplified App Name".

 EOS

@@ -8,9 +8,9 @@
 #

 command_name = ARGV.shift
-cask_name = ARGV.shift
+cask_token = ARGV.shift

-cask = Cask.load(cask_name)
+cask = Cask.load(cask_token)

 Cask.debug = true
 cask.dumpcask
@@ -172,18 +172,18 @@ end
 The first non-comment line in a Cask follows the form

 ```ruby
-cask <dsl-version> => '<cask-name>' do
+cask <dsl-version> => '<cask-token>' do
 ```

 `<dsl-version>` identifies the version of the Cask DSL, currently `:v1`.

-`<cask-name>` should match the Cask filename, without the `.rb` extension,
+`<cask-token>` should match the Cask filename, without the `.rb` extension,
 enclosed in single quotes.

 The header line is not entirely strict Ruby: no comma is required after
-the Cask name.
+the Cask token.

-There are currently some arbitrary limitations on Cask names which are
+There are currently some arbitrary limitations on Cask tokens which are
 in the process of being removed.  The Travis bot will catch any errors
 during the transition.

@@ -198,7 +198,7 @@ position at the end of the Cask:

 | method             | description |
 | ------------------ | ----------- |
-| `title`            | the Cask title
+| `token`            | the Cask token
 | `version`          | the Cask version
 | `homepage`         | the Cask homepage
 | `caskroom_path`    | the containing directory for all staged Casks, typically `/opt/homebrew-cask/Caskroom`
@@ -207,7 +207,7 @@ position at the end of the Cask:
 Example:

 ```ruby
-caveats "Using #{title} is hazardous to your health."
+caveats "Using #{token} is hazardous to your health."
 ```

 ### Caveats as a Block
@@ -386,7 +386,7 @@ using the information stored in the `tags` stanza.

 | key           | meaning
 | ------------- | -----------------------------
-| `:name`       | alternate name for the Cask. (example [smlnj.rb](../Casks/smlnj.rb))
+| `:name`       | the full name of the Cask. (example [smlnj.rb](../Casks/smlnj.rb))
 | `:vendor`     | the full-text official name of the producer of the software: an author or corporate name, as appropriate.  As the value is intended as a search target, commonly shared abbreviations such as `Dr.` or `Inc.` should be omitted. (example [google-chrome.rb](../Casks/google-chrome.rb))


@@ -856,7 +856,7 @@ define arbitrary Ruby variables and methods inside the Cask by creating a
 `Utils` namespace.  Example:

 ```ruby
-cask :v1 => 'appname' do
+cask :v1 => 'myapp' do
  module Utils
    def self.arbitrary_method
      ...
@@ -41,7 +41,7 @@ cask :v1 => 'my-app' do
 ```

 Legacy rules for mapping Cask filenames to header class names are no longer
-needed.  The name `'my-app'` in the header corresponds directly to the
+needed.  The token `'my-app'` in the header corresponds directly to the
 filename `my-app.rb`.

 The term `:v1` identifies the DSL version (currently 1.0), and defines the
@@ -92,6 +92,7 @@ features which are available for the current Cask.
 | `link`                                      | [`app`](CASK_LANGUAGE_REFERENCE.md#app-stanza-details) (or sometimes `suite` or `artifact`)
 | `manual_installer(path)` (within `caveats`) | [`installer :manual`](CASK_LANGUAGE_REFERENCE.md#installer-stanza-details)
 | `nested_container`                          | [`container :nested =>`](CASK_LANGUAGE_REFERENCE.md#optional-stanzas)
+| `title` (in interpolations)                 | [`token`](CASK_LANGUAGE_REFERENCE.md#caveats-as-a-string)
 | `uninstall :files`                          | [`uninstall :delete`](CASK_LANGUAGE_REFERENCE.md#uninstall-stanza-details)
 | `version 'latest'`                          | [`version :latest`](CASK_LANGUAGE_REFERENCE.md#required-stanzas)

@@ -140,7 +141,7 @@ For use in *eg* interpolation:

 * [`caskroom_path`](CASK_LANGUAGE_REFERENCE.md#caveats-as-a-string)
 * [`staged_path`](CASK_LANGUAGE_REFERENCE.md#caveats-as-a-string)
- * [`title`](CASK_LANGUAGE_REFERENCE.md#caveats-as-a-string)
+ * [`token`](CASK_LANGUAGE_REFERENCE.md#caveats-as-a-string)


 ## Caveats Mini-DSL (1.0)
@@ -1,30 +1,37 @@
-# Cask Naming Reference
+# Cask Token Reference

-This document describes the algorithm implemented in the `cask_namer`
+This document describes the algorithm implemented in the `generate_cask_token`
 script, and covers detailed rules and exceptions which are not needed in
 most cases.

 * [Purpose](#purpose)
- * [Finding the Canonical Name of the Developer's Distribution](#finding-the-canonical-name-of-the-developers-distribution)
- * [Cask Name](#cask-name)
- * [Cask Naming Examples](#cask-naming-examples)
+ * [Finding the Simplified Name of the Vendor's Distribution](#finding-the-simplified-name-of-the-vendors-distribution)
+ * [Converting the Simplified Name To a Token](#converting-the-simplified-name-to-a-token)
+ * [Cask Filenames](#cask-filenames)
+ * [Cask Headers](#cask-headers)
+ * [Cask Token Examples](#cask-token-examples)

 ## Purpose

 The purpose of these stringent conventions is to

- * unambiguously boil down the name of the software into a unique token
-   suitable for use as a filename
+ * unambiguously boil down the name of the software into a unique identifier
 * minimize renaming events
 * prevent duplicate submissions

-Details of various names and brands will inevitably be lost in the
-conversion to a Cask name.  To capture the vendor's full name for a
+The token itself should be
+
+ * suitable for use as a filename
+ * mnemonic
+
+Details of software names and brands will inevitably be lost in the
+conversion to a minimal token.  To capture the vendor's full name for a
 distribution, use [`tags :name`](CASK_LANGUAGE_REFERENCE.md#tags-stanza-details) within a Cask.
+`tags :name` accepts an unrestricted UTF-8 string.

-## Finding the Canonical Name of the Developer's Distribution
+## Finding the Simplified Name of the Vendor's Distribution

-### Canonical Names of Apps
+### Simplified Names of Apps

  * Start with the exact name of the Application bundle as it appears on disk,
    such as `Google Chrome.app`.
@@ -34,7 +41,7 @@ distribution, use [`tags :name`](CASK_LANGUAGE_REFERENCE.md#tags-stanza-details)

  * Remove `.app` from the end.

-  * Remove from the end: the string "app", if the developer styles the name
+  * Remove from the end: the string "app", if the vendor styles the name
    like "Software App.app".  Exception: when "app" is an inseparable part of the
    name, without which the name would be inherently nonsensical, as in [rcdefaultapp.rb](../Casks/rcdefaultapp.rb).

@@ -66,7 +73,7 @@ distribution, use [`tags :name`](CASK_LANGUAGE_REFERENCE.md#tags-stanza-details)
  * If the result of that process is a generic term, such as "Macintosh Installer",
    try prepending the name of the vendor or developer, followed by a hyphen.
    If that doesn't work, then just create the best name you can, based on the
-    developer's web page.
+    vendor's web page.

  * If the result conflicts with the name of an existing Cask, make yours unique
    by prepending the name of the vendor or developer, followed by a hyphen.
@@ -101,30 +108,31 @@ distribution, use [`tags :name`](CASK_LANGUAGE_REFERENCE.md#tags-stanza-details)
  * When there is no vendor localization string, romanize the name by
    transliteration or decomposition.

-  * As a last resort, translate the name of the app bundle.
+  * As a last resort, translate the name of the app bundle into English.

-### Canonical Names of `pkg`-based Installers
+### Simplified Names of `pkg`-based Installers

-  * The Canonical Name of a `pkg` may be more tricky to determine than that
+  * The Simplified Name of a `pkg` may be more tricky to determine than that
    of an App.  If a `pkg` installs an App, then use that App name with the
    rules above.  If not, just create the best name you can, based on the
-    developer's web page.
+    vendor's web page.

-### Canonical Names of non-App Software
+### Simplified Names of non-App Software

-  * Currently, naming rules are not well-defined for Preference Panes,
-    QuickLook plugins, and other types of software installable by
-    homebrew-cask.  Just create the best name you can, based on the filename
-    on disk or the developer's web page.  Watch out for duplicates.
+  * Currently, rules for generating a token are not well-defined for
+    Preference Panes, QuickLook plugins, and several other types of software
+    installable by homebrew-cask.  Just create the best name you can, based
+    on the filename on disk or the vendor's web page.  Watch out for
+    duplicates.

-    Non-app Cask names should become more standardized in the future.
+    Non-app tokens should become more standardized in the future.

-## Cask Name
+## Converting the Simplified Name To a Token

-The "Cask name" is the primary identifier for a package in our project. It's
-the token users will refer to when operating on the Cask.
+The token is the primary identifier for a package in our project. It's
+the unique string users refer to when operating on the Cask.

-To convert the App's canonical name (above) to a Cask name:
+To convert the App's Simplified Name (above) to a token:

  * convert all letters to lower case
  * expand the `+` symbol into a separated English word: `-plus-`
@@ -136,22 +144,31 @@ To convert the App's canonical name (above) to a Cask name:
  * delete a leading hyphen
  * a leading number gets spelled out into English: `1password` becomes `onepassword`

-Casks are stored in a Ruby file matching their name.  If possible, avoid
-creating Cask files which differ only by the placement of hyphens.
+We avoid defining Cask tokens in the repository which differ only by the
+placement of hyphens.  Prepend the vendor name if needed to disambiguate
+the token.

+## Cask Filenames

-## Cask Naming Examples
+Casks are stored in a Ruby file named after the token, with the file
+extension `.rb`.

-These illustrate most of the naming rules:
+## Cask Headers

-App Name on Disk       | Canonical App Name | Cask Name        | Cask File
-----------------------|--------------------|------------------|----------------------
-`Audio Hijack Pro.app` | Audio Hijack Pro   | audio-hijack-pro | `audio-hijack-pro.rb`
-`VLC.app`              | VLC                | vlc              | `vlc.rb`
-`BetterTouchTool.app`  | BetterTouchTool    | bettertouchtool  | `bettertouchtool.rb`
-`LPK25 Editor.app`     | LPK25 Editor       | lpk25-editor     | `lpk25-editor.rb`
-`Sublime Text 2.app`   | Sublime Text       | sublime-text     | `sublime-text.rb`
-`1Password.app`        | 1Password          | onepassword      | `onepassword.rb`
+The token is also given in the header line for each Cask.
+
+## Cask Token Examples
+
+These illustrate most of the rules for generating a token:
+
+App Name on Disk       | Simplified App Name | Cask Token       | Filename
+-----------------------|---------------------|------------------|----------------------
+`Audio Hijack Pro.app` | Audio Hijack Pro    | audio-hijack-pro | `audio-hijack-pro.rb`
+`VLC.app`              | VLC                 | vlc              | `vlc.rb`
+`BetterTouchTool.app`  | BetterTouchTool     | bettertouchtool  | `bettertouchtool.rb`
+`LPK25 Editor.app`     | LPK25 Editor        | lpk25-editor     | `lpk25-editor.rb`
+`Sublime Text 2.app`   | Sublime Text        | sublime-text     | `sublime-text.rb`
+`1Password.app`        | 1Password           | onepassword      | `onepassword.rb`


 # <3 THANK YOU TO ALL CONTRIBUTORS! <3
@@ -3,7 +3,7 @@ homebrew-cask(1) -- A friendly binary installer for OS X

 ## SYNOPSIS

-`brew cask` command [options] [<Cask> ...]
+`brew cask` command [options] [<token> ...]

 ## DESCRIPTION

@@ -19,74 +19,77 @@ names, and other aspects of this manual are still subject to change.

 ## FREQUENTLY USED COMMANDS

-  * `install [--force]` <Cask>:
-    Install <Cask>.
+  * `install [--force]` <token> [ <token> ... ]:
+    Install Cask identified by <token>.

-  * `uninstall [--force]` <Cask>:
-    Uninstall <Cask>.
+  * `uninstall [--force]` <token> [ <token> ... ]:
+    Uninstall Cask identified by <token>.

  * `search` <text> | /<regexp>/:
-    Perform a substring search of Cask names for <text>.  If the text is
-    delimited by slashes, it is interpreted as a Ruby regular expression.
+    Perform a substring search of known Cask tokens for <text>.  If the text
+    is delimited by slashes, it is interpreted as a Ruby regular expression.

-    The Cask names returned by `search` are suitable as arguments for most
-    other commands, such as `install` or `uninstall`.
+    The tokens returned by `search` are suitable as arguments for most other
+    commands, such as `install` or `uninstall`.

 ## COMMANDS

-  * `audit` [<Casks>]:
-   Check <Casks> for installability.
-   If no <Casks> are given on the command line, all Casks are audited.
+  * `audit` [ <token> ... ]:
+   Check the given Casks for installability.
+   If no tokens are given on the command line, all Casks are audited.

  * `alfred`:
    Modify Alfred's search scope to include the Caskroom directory where
    Applications are stored.

-  * `cat` <Cask>:
+  * `cat` <token> [ <token> ... ]:
    Dump the given Cask definition file to the standard output.

  * `cleanup` [--outdated]:
-    Clean up cached downloads and tracker symlinks.  With `--outdated`, only
-    clean up cached downloads older than 10 days old.
+    Clean up cached downloads and tracker symlinks.  With `--outdated`,
+    only clean up cached downloads older than 10 days old.

-  * `create` <Cask>:
-    Generate a Cask definition file for the Cask named <Cask> and open a
-    template for it in your favorite editor.
+  * `create` <token>:
+    Generate a Cask definition file for the Cask identified by <token>
+    and open a template for it in your favorite editor.

  * `doctor` or `dr`:
    Check for configuration issues.  Can be useful to upload as a gist for
    developers along with a bug report.

-  * `edit` <Cask>:
+  * `edit` <token>:
    Open the given Cask definition file for editing.

-  * `fetch` <Cask> [--force]:
+  * `fetch` [--force] <token> [ <token> ... ]:
    Fetch remote resources for the given Cask to the local cache.  With
    `--force`, force re-download even if the resources are already cached.

-  * `home` or `homepage`:
-    Open the project page <http://caskroom.io> in a browser.
+  * `home` or `homepage` [<token>]:
+    Display the homepage associated with a given Cask in a browser.

-  * `info` or `abv` <Cask>:
-    Display information about <Cask>.
+    With no arguments, display the project page <http://caskroom.io>.

-  * `install [--force]` <Cask>:
-    Install <Cask>.  With `--force`, re-install even if the Cask appears to
-    be already present.
+  * `info` or `abv` <token> [ <token> ... ]:
+    Display information about the given Cask.

-    <Cask> is usually the name of a Cask as returned by `brew cask search`,
+  * `install [--force]` <token> [ <token> ... ]:
+    Install the given Cask.  With `--force`, re-install even if the Cask
+    appears to be already present.
+
+    <token> is usually the ID of a Cask as returned by `brew cask search`,
    but see [OTHER WAYS TO SPECIFY A CASK][] for variations.

-  * `list` or `ls` [-1 | -l] [<Casks>]:
+  * `list` or `ls` [-1 | -l] [ <token> ... ]:
    Without any arguments, list all installed Casks.  With `-1`, always
    format the output in a single column.  With `-l`, give a more detailed
    listing.

-    If <Casks> are given, list the staged files for <Casks>.
+    If <token> is given, summarize the staged files associated with the
+    given Cask.

-  * `uninstall [--force]` or `rm` or `remove` <Cask>:
-    Uninstall <Cask>.  With `--force`, uninstall even if the Cask does
-    not appear to be present.
+  * `uninstall [--force]` or `rm` or `remove` <token> [ <token> ... ]:
+    Uninstall the given Cask.  With `--force`, uninstall even if the Cask
+    does not appear to be present.

    Note that `uninstall --force` is currently imperfect.  It will follow
    the `uninstall` instructions from *newest* Cask definition, even if
@@ -100,14 +103,14 @@ names, and other aspects of this manual are still subject to change.
    perform an `uninstall` operation if the given Cask has changed since you
    installed it.  This issue is being addressed.

-  * `zap` <Cask>:
-    Unconditionally remove _all_ files associated with <Cask>.
+  * `zap` <token> [ <token> ... ]:
+    Unconditionally remove _all_ files associated with the given Cask.

    Implicitly performs all actions associated with `uninstall`, even if
    the Cask does not appear to be currently installed.

    Removes all staged versions of the Cask distribution found under
-    `/opt/homebrew-cask/Caskroom/<Cask>`
+    `/opt/homebrew-cask/Caskroom/<token>`

    If the Cask definition contains a `zap` stanza, performs additional
    `zap` actions as defined there, such as removing local preference
@@ -120,9 +123,8 @@ names, and other aspects of this manual are still subject to change.
    Display all Casks available for install.

  * `search` or `-S` <text> | /<regexp>/:
-    Perform a substring search of Cask names for <text>.  If the text
-    is delimited by slashes, it is interpreted as a Ruby regular
-    expression.
+    Perform a substring search of known Cask tokens for <text>.  If the text
+    is delimited by slashes, it is interpreted as a Ruby regular expression.

  * `update`:
    For convenience, `brew cask update` is a synonym for `brew update`.
@@ -196,14 +198,14 @@ the Homebrew command:

 ## OTHER WAYS TO SPECIFY A CASK

-Most homebrew-cask commands can accept a Cask name as an argument.  As
-described above, a Cask name on the command line can take the form of:
+Most homebrew-cask commands can accept a Cask token as an argument.  As
+described above, the argument can take the form of:

-  * A Cask name as returned by `brew cask search`, _eg_ `google-chrome`
+  * A token as returned by `brew cask search`, _eg_ `google-chrome`

-Homebrew-cask also accepts three other forms for Cask names:
+Homebrew-cask also accepts three other forms in place of plain tokens:

-  * A fully-qualified Cask name which includes the Tap name, _eg_
+  * A fully-qualified token which includes the Tap name, _eg_
    `caskroom/fonts/font-symbola`

  * A fully-qualified pathname to a Cask file, _eg_
@@ -22,7 +22,7 @@ require 'cask/locations'
 require 'cask/options'
 require 'cask/pkg'
 require 'cask/pretty_listing'
-require 'cask/qualified_cask_name'
+require 'cask/qualified_token'
 require 'cask/scopes'
 require 'cask/source'
 require 'cask/staged'
@@ -80,10 +80,15 @@ class Cask
    cask
  end

-  def self.title
+  def self.token
    self.name.gsub(/([a-zA-Z\d])([A-Z])/,'\1-\2').gsub(/([a-zA-Z\d])([A-Z])/,'\1-\2').downcase
  end

+  # todo removeme transitional backward-compatibility
+  def self.title
+    self.token
+  end
+
  def self.nowstamp_metadata_path(container_path)
    @timenow ||= Time.now.gmtime
    if container_path.respond_to?(:join)
@@ -95,13 +100,18 @@ class Cask
    end
  end

-  attr_reader :title
-  def initialize(title=self.class.title)
-    @title = title
+  attr_reader :token
+  def initialize(token=self.class.token)
+    @token = token
+  end
+
+  # todo removeme transitional backward-compatibility
+  def title
+    @token
  end

  def caskroom_path
-    self.class.caskroom.join(title)
+    self.class.caskroom.join(token)
  end

  def staged_path
@@ -159,6 +169,6 @@ class Cask
  end

  def to_s
-    @title
+    @token
  end
 end
@@ -20,8 +20,13 @@ class Cask::CaveatsDSL
  end

  # helpers
+  def token
+    @cask.token
+  end
+
+  # todo removeme transitional backward compatibility
  def title
-    @cask.title
+    @cask.token
  end

  def version
@@ -29,7 +34,7 @@ class Cask::CaveatsDSL
  end

  def caskroom_path
-    @cask.class.caskroom.join(title)
+    @cask.class.caskroom.join(token)
  end

  def staged_path
@@ -132,21 +132,21 @@ class Cask::CLI
  end

  def self.nice_listing(cask_list)
-    casks = {}
-    cask_list.each { |c|
-      user, repo, name = c.split '/'
+    cask_taps = {}
+    cask_list.each do |c|
+      user, repo, token = c.split '/'
      repo.sub!(/^homebrew-/i, '')
-      casks[name] ||= []
-      casks[name].push "#{user}/#{repo}"
-    }
+      cask_taps[token] ||= []
+      cask_taps[token].push "#{user}/#{repo}"
+    end
    list = []
-    casks.each { |name,taps|
+    cask_taps.each do |token,taps|
      if taps.length == 1
-        list.push name
+        list.push token
      else
-        taps.each { |r| list.push [r,name].join '/' }
+        taps.each { |r| list.push [r,token].join '/' }
      end
-    }
+    end
    list.sort
  end

@@ -223,18 +223,18 @@ class Cask::CLI
  end

  class NullCommand
-    def initialize(attempted_name)
-      @attempted_name = attempted_name
+    def initialize(attempted_verb)
+      @attempted_verb = attempted_verb
    end

    def run(*args)
-      if args.include?('--version') or @attempted_name == '--version'
+      if args.include?('--version') or @attempted_verb == '--version'
        puts HOMEBREW_CASK_VERSION
      else
        purpose
-        if @attempted_name and @attempted_name != "help"
+        if @attempted_verb and @attempted_verb != "help"
          puts "!! "
-          puts "!! no command with name: #{@attempted_name}"
+          puts "!! no command verb: #{@attempted_verb}"
          puts "!! \n\n"
        end
        usage
@@ -36,14 +36,14 @@ class Cask::CLI::Audit < Cask::CLI::Base
  end

  def casks_to_audit
-    if cask_list.empty?
+    if cask_tokens.empty?
      Cask.all
    else
-      cask_list.map { |arg| Cask.load(arg) }
+      cask_tokens.map { |token| Cask.load(token) }
    end
  end

-  def cask_list
-    @cask_list ||= @args.reject { |a| a == '--download' }
+  def cask_tokens
+    @cask_tokens ||= @args.reject { |a| a == '--download' }
  end
 end
@@ -7,7 +7,7 @@ class Cask::CLI::Base
    true
  end

-  def self.cask_names_from(args)
+  def self.cask_tokens_from(args)
    args.reject { |a| a.chars.first == '-' }
  end

@@ -1,11 +1,11 @@
 class Cask::CLI::Cat < Cask::CLI::Base
  def self.run(*args)
-    cask_names = cask_names_from(args)
-    raise CaskUnspecifiedError if cask_names.empty?
+    cask_tokens = cask_tokens_from(args)
+    raise CaskUnspecifiedError if cask_tokens.empty?
    # only respects the first argument
-    cask_name = cask_names.first.sub(/\.rb$/i, '')
-    cask_path = Cask.path(cask_name)
-    raise CaskUnavailableError, cask_name.to_s unless cask_path.exist?
+    cask_token = cask_tokens.first.sub(/\.rb$/i, '')
+    cask_path = Cask.path(cask_token)
+    raise CaskUnavailableError, cask_token.to_s unless cask_path.exist?
    puts File.open(cask_path) { |f| f.read }
  end

@@ -1,25 +1,25 @@
 class Cask::CLI::Create < Cask::CLI::Base
  def self.run(*args)
-    cask_names = cask_names_from(args)
-    raise CaskUnspecifiedError if cask_names.empty?
-    cask_name = cask_names.first.sub(/\.rb$/i,'')
-    cask_path = Cask.path(cask_name)
-    odebug "Creating Cask #{cask_name}"
+    cask_tokens = cask_tokens_from(args)
+    raise CaskUnspecifiedError if cask_tokens.empty?
+    cask_token = cask_tokens.first.sub(/\.rb$/i,'')
+    cask_path = Cask.path(cask_token)
+    odebug "Creating Cask #{cask_token}"

    if cask_path.exist?
-      raise CaskAlreadyCreatedError.new cask_name
+      raise CaskAlreadyCreatedError.new cask_token
    end

    File.open(cask_path, 'w') do |f|
-      f.write template(cask_name)
+      f.write template(cask_token)
    end

    exec_editor cask_path
  end

-  def self.template(cask_name);
+  def self.template(cask_token)
    <<-EOS.undent
-      cask :v1 => '#{cask_name}' do
+      cask :v1 => '#{cask_token}' do
        version ''
        sha256 ''

@@ -33,6 +33,6 @@ class Cask::CLI::Create < Cask::CLI::Base
  end

  def self.help
-    "creates a Cask of the given name and opens it in an editor"
+    "creates the given Cask and opens it in an editor"
  end
 end
@@ -1,18 +1,18 @@
 class Cask::CLI::Edit < Cask::CLI::Base
  def self.run(*args)
-    cask_names = cask_names_from(args)
-    raise CaskUnspecifiedError if cask_names.empty?
+    cask_tokens = cask_tokens_from(args)
+    raise CaskUnspecifiedError if cask_tokens.empty?
    # only respects the first argument
-    cask_name = cask_names.first.sub(/\.rb$/i, '')
-    cask_path = Cask.path(cask_name)
-    odebug "Opening editor for Cask #{cask_name}"
+    cask_token = cask_tokens.first.sub(/\.rb$/i, '')
+    cask_path = Cask.path(cask_token)
+    odebug "Opening editor for Cask #{cask_token}"
    unless cask_path.exist?
-      raise CaskUnavailableError, %Q{#{cask_name}, run "brew cask create #{cask_name}" to create a new Cask with this name}
+      raise CaskUnavailableError, %Q{#{cask_token}, run "brew cask create #{cask_token}" to create a new Cask}
    end
    exec_editor cask_path
  end

  def self.help
-    "edits the Cask of the given name"
+    "edits the given Cask"
  end
 end
@@ -1,12 +1,12 @@
 class Cask::CLI::Fetch < Cask::CLI::Base
  def self.run(*args)
-    cask_names = cask_names_from(args)
-    raise CaskUnspecifiedError if cask_names.empty?
+    cask_tokens = cask_tokens_from(args)
+    raise CaskUnspecifiedError if cask_tokens.empty?
    force = args.include? '--force'

-    cask_names.each do |cask_name|
-      ohai "Fetching resources for Cask #{cask_name}"
-      cask = Cask.load(cask_name)
+    cask_tokens.each do |cask_token|
+      ohai "Fetching resources for Cask #{cask_token}"
+      cask = Cask.load(cask_token)
      @downloaded_path = Cask::Download.new(cask).perform force
      ohai "Success! Downloaded to -> #{@downloaded_path}"
    end
@@ -1,18 +1,18 @@
 class Cask::CLI::Home < Cask::CLI::Base
-  def self.run(*cask_names)
-    if cask_names.empty?
+  def self.run(*cask_tokens)
+    if cask_tokens.empty?
      odebug "Opening project homepage"
      system "/usr/bin/open", '--', 'http://caskroom.io/'
    else
-      cask_names.each do |cask_name|
-        odebug "Opening homepage for Cask #{cask_name}"
-        cask = Cask.load(cask_name)
+      cask_tokens.each do |cask_token|
+        odebug "Opening homepage for Cask #{cask_token}"
+        cask = Cask.load(cask_token)
        system "/usr/bin/open", '--', cask.homepage
      end
    end
  end

  def self.help
-    "opens the homepage of the Cask of the given name"
+    "opens the homepage of the given Cask"
  end
 end
@@ -1,17 +1,17 @@
 class Cask::CLI::Info < Cask::CLI::Base
  def self.run(*args)
-    cask_names = cask_names_from(args)
-    raise CaskUnspecifiedError if cask_names.empty?
-    cask_names.each do |cask_name|
-      odebug "Getting info for Cask #{cask_name}"
-      cask = Cask.load(cask_name)
+    cask_tokens = cask_tokens_from(args)
+    raise CaskUnspecifiedError if cask_tokens.empty?
+    cask_tokens.each do |cask_token|
+      odebug "Getting info for Cask #{cask_token}"
+      cask = Cask.load(cask_token)
      puts info(cask)
      Cask::Installer.print_caveats(cask)
    end
  end

  def self.help
-    "displays information about the Cask of the given name"
+    "displays information about the given Cask"
  end

  def self.info(cask)
@@ -31,23 +31,23 @@ PURPOSE
  end

  def self.github_info(cask)
-    title = cask.title
-    title = cask.class.all_titles.detect { |t| t.split("/").last == title } unless title =~ /\//
-    return nil unless title.respond_to?(:length) and title.length > 0
-    path_elements = title.split '/'
+    cask_token = cask.token
+    cask_token = cask.class.all_tokens.detect { |t| t.split("/").last == cask_token } unless cask_token =~ /\//
+    return nil unless cask_token.respond_to?(:length) and cask_token.length > 0
+    path_elements = cask_token.split '/'
    if path_elements.count == 2
      # eg caskroom-cask/google-chrome.
      # Not certain this form is needed, but it was supported in the past.
-      name = path_elements[1]
+      token = path_elements[1]
      dash_elements = path_elements[0].split('-')
      repo = dash_elements.pop
      dash_elements.pop if dash_elements.count > 1 and dash_elements[-1] + '-' == repo_prefix
      user = dash_elements.join('-')
    else
-      user, repo, name = path_elements
+      user, repo, token = path_elements
    end
    repo.sub!(/^homebrew-/i, '')
-    "https://github.com/#{user}/homebrew-#{repo}/blob/master/Casks/#{name}.rb"
+    "https://github.com/#{user}/homebrew-#{repo}/blob/master/Casks/#{token}.rb"
  end

  def self.artifact_info(cask)
--- a/Show More
+++ b/Show More