diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d7f4d14ab..1ad9b6851 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -33,7 +33,7 @@ Here's a Cask for `Alfred.app` as an example. Note that you may repeat the `app` stanza as many times as you need, to define multiple apps: ```ruby -class Alfred < Cask +cask :v1 => 'alfred' do version '2.3_264' sha256 'a32565cdb1673f4071593d4cc9e1c26bc884218b62fef8abc450daa47ba8fa92' @@ -49,7 +49,7 @@ end Here is another Cask for `Unity.pkg`: ```ruby -class Unity < Cask +cask :v1 => 'unity' do version '4.5.4' sha256 '6fb72bfacf78df072559dd9a024a9d47e49b5717c8f17d53f05e2fc74a721876' @@ -65,7 +65,7 @@ end And here is one for `Firefox.app`. Note that it has an unversioned download (the download `url` does not contain the version number, unlike the example above). It also suppresses the checksum with `sha256 :no_check` (necessary since the checksum will change when a new version is available). This combination of `version :latest` and `sha256 :no_check` is currently the preferred mechanism when an unversioned download URL is available: ```ruby -class Firefox < Cask +cask :v1 => 'firefox' do version :latest sha256 :no_check @@ -109,14 +109,12 @@ Once you know the name for your Cask, create it with the handy-dandy $ brew cask create my-new-cask ``` -This will open `$EDITOR` with a template for your new Cask. Hyphens in the -Cask name indicate case-changes in the class name, so the Cask name -'my-new-cask' becomes class `MyNewCask` stored in file `my-new-cask.rb`. -Running the `create` command above will get you a template that looks like -this: +This will open `$EDITOR` with a template for your new Cask, to be stored in +the file `my-new-cask.rb`. Running the `create` command above will get you +a template that looks like this: ```ruby -class MyNewCask < Cask +cask :v1 => 'my-new-cask' do version '' sha256 '' diff --git a/doc/CASK_LANGUAGE_REFERENCE.md b/doc/CASK_LANGUAGE_REFERENCE.md index dfe528f15..a7dd4dd92 100644 --- a/doc/CASK_LANGUAGE_REFERENCE.md +++ b/doc/CASK_LANGUAGE_REFERENCE.md @@ -3,7 +3,7 @@ This document acts as a complete specification, and covers aspects of the Cask Domain-Specific Language (DSL) which are not needed in most cases. - * [Casks Are Ruby Classes](#casks-are-ruby-classes) + * [Casks Are Ruby Blocks](#casks-are-ruby-blocks) * [The Cask Language Is Declarative](#the-cask-language-is-declarative) * [Required Stanzas](#required-stanzas) * [At Least One Artifact Stanza Is Also Required](#at-least-one-artifact-stanza-is-also-required) @@ -11,6 +11,7 @@ Cask Domain-Specific Language (DSL) which are not needed in most cases. * [Legacy Stanzas](#legacy-stanzas) * [Legacy Forms](#legacy-forms) * [Conditional Statements](#conditional-statements) + * [Header Line Details](#header-line-details) * [Caveats Stanza Details](#caveats-stanza-details) * [Checksum Stanza Details](#checksum-stanza-details) * [URL Stanza Details](#url-stanza-details) @@ -30,13 +31,13 @@ Cask Domain-Specific Language (DSL) which are not needed in most cases. * [Revisions to the Cask DSL](#revisions-to-the-cask-dsl) -## Casks Are Ruby Classes +## Casks Are Ruby Blocks -Each Cask is a Ruby class, derived from class `Cask`. The Cask definition -is always enclosed in a `class ... end` block. Example: +Each Cask is a Ruby block, beginning with a special header line. The Cask +definition itself is always enclosed in a `do ... end` block. Example: ```ruby -class Alfred < Cask +cask :v1 => 'alfred' do version '2.3_264' sha256 'a32565cdb1673f4071593d4cc9e1c26bc884218b62fef8abc450daa47ba8fa92' @@ -49,7 +50,6 @@ class Alfred < Cask end ``` - ## The Cask Language Is Declarative Each Cask contains a series of stanzas (or "fields") which *declare* how the @@ -196,6 +196,27 @@ else end ``` +## Header Line Details + +The first non-comment line in a Cask follows the form + +```ruby +cask => '' do +``` + +`` identifies the version of the Cask DSL, currently `:v1`. + +`` 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. + +There are currently some arbitrary limitations on Cask names which are +in the process of being removed. The Travis bot will catch any errors +during the transition. + + ## Caveats Stanza Details ### Caveats as a String @@ -858,7 +879,7 @@ define arbitrary Ruby variables and methods inside the Cask by creating a `Utils` namespace. Example: ```ruby -class Appname < Cask +cask :v1 => 'appname' do module Utils def self.arbitrary_method ... diff --git a/doc/CASK_NAMING_REFERENCE.md b/doc/CASK_NAMING_REFERENCE.md index 89ae06152..9a98e76ac 100644 --- a/doc/CASK_NAMING_REFERENCE.md +++ b/doc/CASK_NAMING_REFERENCE.md @@ -6,7 +6,6 @@ most cases. * [Find the Canonical Name of the Developer's Distribution](#find-the-canonical-name-of-the-developers-distribution) * [Cask Name](#cask-name) - * [Cask Class](#cask-class) * [Cask Naming Examples](#cask-naming-examples) ## Find the Canonical Name of the Developer's Distribution @@ -80,30 +79,18 @@ Casks are stored in a Ruby file matching their name. If possible, avoid creatin Cask files which differ only by the placement of hyphens. -## Cask Class - -Casks are implemented as Ruby classes, so a Cask's "class" needs to be a -valid Ruby class name. - -When converting a __Cask name__ to its corresponding __class name__: - - * convert to UpperCamelCase - * wherever a hyphen occurs in the __Cask name__, remove the hyphen and - create a case change in the __class name__ - - ## Cask Naming Examples These illustrate most of the naming rules: -App Name on Disk | Canonical App Name | Cask Name | Cask File | Cask Class ------------------------|--------------------|--------------------|-----------------------|------------------------ -`Audio Hijack Pro.app` | Audio Hijack Pro | `audio-hijack-pro` | `audio-hijack-pro.rb` | `AudioHijackPro` -`VLC.app` | VLC | `vlc` | `vlc.rb` | `Vlc` -`BetterTouchTool.app` | BetterTouchTool | `bettertouchtool` | `bettertouchtool.rb` | `Bettertouchtool` -`LPK25 Editor.app` | LPK25 Editor | `lpk25-editor` | `lpk25-editor.rb` | `Lpk25Editor` -`Sublime Text 2.app` | Sublime Text | `sublime-text` | `sublime-text.rb` | `SublimeText` -`1Password.app` | 1Password | `onepassword` | `onepassword.rb` | `Onepassword` +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` # <3 THANK YOU TO ALL CONTRIBUTORS! <3 diff --git a/doc/cask_language_deltas.md b/doc/cask_language_deltas.md index 9e603531b..dd94062c7 100644 --- a/doc/cask_language_deltas.md +++ b/doc/cask_language_deltas.md @@ -15,6 +15,7 @@ Cask DSL 1.0 specification. * [Removals (1.0)](#removals-10) * [Additions (1.0)](#additions-10) * [Renames (1.0)](#renames-10) + * [Header Line (1.0)](#header-line-10) * [All Supported Stanzas (1.0)](#all-supported-stanzas-10) @@ -79,6 +80,28 @@ This notice will be removed for the final form.** **Stub!** +## Header Line (1.0) + +The header line was changed from the form + +```ruby +class MyApp < Cask +``` + +to + +```ruby +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 +filename `my-app.rb`. + +The term `:v1` identifies the DSL version (currently 1.0), and defines the +features which are available for the current Cask. + + ## References * [DSL 1.0 transition notice](https://github.com/caskroom/homebrew-cask/issues/5890)