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.
Homebrew · Dec 1, 2014 · a335d3b · a335d3b
1 parent 8c82496
commit a335d3b
Show file tree

Hide file tree

Showing 49 changed files with 491 additions and 438 deletions.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -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

diff --git a/Casks/python3.rb b/Casks/python3.rb
@@ -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'
 

diff --git a/USAGE.md b/USAGE.md
@@ -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.
 

diff --git a/developer/bin/cask_namer → developer/bin/generate_cask_token b/developer/bin/cask_namer → developer/bin/generate_cask_token
@@ -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
 

diff --git a/developer/examples/brewcask-dumpcask.rb b/developer/examples/brewcask-dumpcask.rb
@@ -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
diff --git a/doc/CASK_LANGUAGE_REFERENCE.md b/doc/CASK_LANGUAGE_REFERENCE.md
@@ -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
       ...

diff --git a/doc/cask_language_deltas.md b/doc/cask_language_deltas.md
@@ -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)