From 7c9cec2f4e00a23debe303380320ca72dddfe6b8 Mon Sep 17 00:00:00 2001 From: Roland Walker Date: Thu, 13 Nov 2014 11:30:55 -0500 Subject: [PATCH 1/4] use new header form in docs --- CONTRIBUTING.md | 16 +++++++--------- doc/CASK_LANGUAGE_REFERENCE.md | 35 +++++++++++++++++++++++++++------- doc/CASK_NAMING_REFERENCE.md | 29 ++++++++-------------------- doc/cask_language_deltas.md | 23 ++++++++++++++++++++++ 4 files changed, 66 insertions(+), 37 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d7f4d14abbb01..1ad9b68510283 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 dfe528f158baf..a7dd4dd923130 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 89ae06152bfe2..9a98e76ac21fc 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 9e603531b76e6..dd94062c722cf 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) From 00747614f7c91c1076c66cbb72270559cda258e3 Mon Sep 17 00:00:00 2001 From: Roland Walker Date: Thu, 13 Nov 2014 11:32:21 -0500 Subject: [PATCH 2/4] use new header form in `create` template --- lib/cask/cli/create.rb | 3 +-- test/cask/cli/create_test.rb | 2 +- 2 files changed, 2 insertions(+), 3 deletions(-) diff --git a/lib/cask/cli/create.rb b/lib/cask/cli/create.rb index 8a5caad9e3ebe..7636521902836 100644 --- a/lib/cask/cli/create.rb +++ b/lib/cask/cli/create.rb @@ -18,9 +18,8 @@ def self.run(*args) end def self.template(cask_name); - cask_class = cask_name.split('-').map(&:capitalize).join <<-EOS.undent - class #{cask_class} < Cask + cask :v1 => '#{cask_name}' do version '' sha256 '' diff --git a/test/cask/cli/create_test.rb b/test/cask/cli/create_test.rb index d79bc417f311a..54d820325988e 100644 --- a/test/cask/cli/create_test.rb +++ b/test/cask/cli/create_test.rb @@ -36,7 +36,7 @@ def self.editor_commands Cask::CLI::Create.run('new-cask') template = File.read(Cask.path('new-cask')) template.must_equal <<-TEMPLATE.undent - class NewCask < Cask + cask :v1 => 'new-cask' do version '' sha256 '' From ffc9f769dc57b480e5f1db293831ae417cbc3209 Mon Sep 17 00:00:00 2001 From: Roland Walker Date: Thu, 13 Nov 2014 11:45:35 -0500 Subject: [PATCH 3/4] use new header form in `cask_name` devscript --- developer/bin/cask_namer | 29 +---------------------------- 1 file changed, 1 insertion(+), 28 deletions(-) diff --git a/developer/bin/cask_namer b/developer/bin/cask_namer index c0308d12ad5fc..9768903a257c1 100755 --- a/developer/bin/cask_namer +++ b/developer/bin/cask_namer @@ -340,29 +340,6 @@ class CaskFileName < String end end -class CaskClassName < String - def basename - if Pathname.new(self).exist? - CaskClassName.new(Pathname.new(self).basename.to_s) - else - self - end - end - - def remove_extension - self.sub(/#{escaped_cask_file_extension}\Z/i, '') - end - - def hyphens_to_camel_case - self.split('-').map(&:capitalize).join - end - - def from_cask_name - # or from filename - self.basename.remove_extension.hyphens_to_camel_case - end -end - ### ### methods ### @@ -398,10 +375,6 @@ def cask_name @cask_name ||= cask_file_name.remove_extension end -def class_name - @class_name ||= CaskClassName.new(cask_name).from_cask_name -end - def warnings return @warnings if @warnings @warnings = [] @@ -421,7 +394,7 @@ 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: class #{class_name} < Cask" + puts "First Line of Cask: cask :v1 => '#{cask_name}' do" if warnings.length > 0 STDERR.puts "\n" STDERR.puts warnings From 113a667fccaca252ade326771873eac0d2f4d1e7 Mon Sep 17 00:00:00 2001 From: Roland Walker Date: Thu, 13 Nov 2014 11:45:47 -0500 Subject: [PATCH 4/4] flag backward-compatibility todo --- lib/cask/source/path_base.rb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/cask/source/path_base.rb b/lib/cask/source/path_base.rb index 1587a1c911eb7..b610e16b0aea6 100644 --- a/lib/cask/source/path_base.rb +++ b/lib/cask/source/path_base.rb @@ -30,7 +30,7 @@ def load # # limitation: does not support Ruby extended quoting such as %Q{} # - # in the future, this can be pared down to an "eval" + # todo: in the future, this can be pared down to an "eval" # read Cask cask_string = File.open(path, 'rb') do |handle|