Class: Cask::DSL Private

Inherits:
Object show all
Extended by:
Attrable
Includes:
OnSystem::MacOSOnly
Defined in:
cask/dsl.rb,
cask/dsl/base.rb,
cask/dsl/caveats.rb,
cask/dsl/version.rb,
cask/dsl/container.rb,
cask/dsl/preflight.rb,
cask/dsl/depends_on.rb,
cask/dsl/postflight.rb,
cask/dsl/conflicts_with.rb,
cask/dsl/uninstall_preflight.rb,
cask/dsl/uninstall_postflight.rb,
sorbet/rbi/dsl/cask/dsl.rbi

Overview

This class is part of a private API. This class may only be used in the Homebrew/brew repository. Third parties should avoid using this class if possible, as it may be removed or changed without warning.

Class representing the domain-specific language used for casks.

Defined Under Namespace

Classes: Base, Caveats, ConflictsWith, Container, DependsOn, Postflight, Preflight, UninstallPostflight, UninstallPreflight, Version

Constant Summary collapse

ORDINARY_ARTIFACT_CLASSES =

This constant is part of a private API. This constant may only be used in the Homebrew/brew repository. Third parties should avoid using this constant if possible, as it may be removed or changed without warning. 

[
  Artifact::Installer,
  Artifact::App,
  Artifact::Artifact,
  Artifact::AudioUnitPlugin,
  Artifact::Binary,
  Artifact::Colorpicker,
  Artifact::Dictionary,
  Artifact::Font,
  Artifact::InputMethod,
  Artifact::InternetPlugin,
  Artifact::KeyboardLayout,
  Artifact::Manpage,
  Artifact::Pkg,
  Artifact::Prefpane,
  Artifact::Qlplugin,
  Artifact::Mdimporter,
  Artifact::ScreenSaver,
  Artifact::Service,
  Artifact::StageOnly,
  Artifact::Suite,
  Artifact::VstPlugin,
  Artifact::Vst3Plugin,
  Artifact::Uninstall,
  Artifact::Zap,
].freeze
ACTIVATABLE_ARTIFACT_CLASSES =

This constant is part of a private API. This constant may only be used in the Homebrew/brew repository. Third parties should avoid using this constant if possible, as it may be removed or changed without warning. 

(ORDINARY_ARTIFACT_CLASSES - [Artifact::StageOnly]).freeze
ARTIFACT_BLOCK_CLASSES =

This constant is part of a private API. This constant may only be used in the Homebrew/brew repository. Third parties should avoid using this constant if possible, as it may be removed or changed without warning. 

[
  Artifact::PreflightBlock,
  Artifact::PostflightBlock,
].freeze
DSL_METHODS =

This constant is part of a private API. This constant may only be used in the Homebrew/brew repository. Third parties should avoid using this constant if possible, as it may be removed or changed without warning. 

Set.new([
  :appcast,
  :arch,
  :artifacts,
  :auto_updates,
  :caveats,
  :conflicts_with,
  :container,
  :desc,
  :depends_on,
  :homepage,
  :language,
  :name,
  :sha256,
  :staged_path,
  :url,
  :version,
  :appdir,
  :deprecate!,
  :deprecated?,
  :deprecation_date,
  :deprecation_reason,
  :deprecation_replacement,
  :disable!,
  :disabled?,
  :disable_date,
  :disable_reason,
  :disable_replacement,
  :discontinued?, # TODO: remove once discontinued? is removed (4.5.0)
  :livecheck,
  :livecheck_defined?,
  :livecheckable?, # TODO: remove once `#livecheckable?` is removed
  :on_system_blocks_exist?,
  :on_system_block_min_os,
  :depends_on_set_in_block?,
  *ORDINARY_ARTIFACT_CLASSES.map(&:dsl_key),
  *ACTIVATABLE_ARTIFACT_CLASSES.map(&:dsl_key),
  *ARTIFACT_BLOCK_CLASSES.flat_map { |klass| [klass.dsl_key, klass.uninstall_dsl_key] },
]).freeze

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from Attrable

attr_predicate, attr_rw

Methods included from OnSystem::MacOSOnly

included, #on_arch_conditional

Constructor Details

#initialize(cask) ⇒ DSL

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

Returns a new instance of DSL.



116
117
118
119
 
# File 'cask/dsl.rb', line 116

def initialize(cask)
  @cask = cask
  @token = cask.token
end

Dynamic Method Handling

This class handles dynamic methods through the method_missing method

#method_missing(method) ⇒ Object

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning. 



510
511
512
513
514
515
516
517
 
# File 'cask/dsl.rb', line 510

def method_missing(method, *)
  if method
    Utils.method_missing_message(method, token)
    nil
  else
    super
  end
end

Instance Attribute Details

#cask ⇒ Object (readonly)

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning. 



111
112
113
 
# File 'cask/dsl.rb', line 111

def cask
  @cask
end

#deprecation_date ⇒ Object (readonly)

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning. 



111
112
113
 
# File 'cask/dsl.rb', line 111

def deprecation_date
  @deprecation_date
end

#deprecation_reason ⇒ Object (readonly)

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning. 



111
112
113
 
# File 'cask/dsl.rb', line 111

def deprecation_reason
  @deprecation_reason
end

#deprecation_replacement ⇒ Object (readonly)

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning. 



111
112
113
 
# File 'cask/dsl.rb', line 111

def deprecation_replacement
  @deprecation_replacement
end

#disable_date ⇒ Object (readonly)

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning. 



111
112
113
 
# File 'cask/dsl.rb', line 111

def disable_date
  @disable_date
end

#disable_reason ⇒ Object (readonly)

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning. 



111
112
113
 
# File 'cask/dsl.rb', line 111

def disable_reason
  @disable_reason
end

#disable_replacement ⇒ Object (readonly)

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning. 



111
112
113
 
# File 'cask/dsl.rb', line 111

def disable_replacement
  @disable_replacement
end

#on_system_block_min_os ⇒ Object (readonly)

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning. 



111
112
113
 
# File 'cask/dsl.rb', line 111

def on_system_block_min_os
  @on_system_block_min_os
end

#token ⇒ Object (readonly)

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning. 



111
112
113
 
# File 'cask/dsl.rb', line 111

def token
  @token
end

Instance Method Details

#appdir ⇒ Object

The directory apps are installed into.



526
527
528
529
530
 
# File 'cask/dsl.rb', line 526

def appdir
  return HOMEBREW_CASK_APPDIR_PLACEHOLDER if Cask.generating_hash?

  cask.config.appdir
end

#arch(arm: nil, intel: nil) ⇒ Object

Sets the cask's architecture strings.

Example

arch arm: "darwin-arm64", intel: "darwin"



345
346
347
348
349
350
351
352
353
 
# File 'cask/dsl.rb', line 345

def arch(arm: nil, intel: nil)
  should_return = arm.nil? && intel.nil?

  set_unique_stanza(:arch, should_return) do
    @on_system_blocks_exist = true

    on_arch_conditional(arm:, intel:)
  end
end

#artifacts ⇒ Object

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning. 



381
382
383
 
# File 'cask/dsl.rb', line 381

def artifacts
  @artifacts ||= ArtifactSet.new
end

#auto_updates(auto_updates = nil) ⇒ Object

Asserts that the cask artifacts auto-update.



424
425
426
 
# File 'cask/dsl.rb', line 424

def auto_updates(auto_updates = nil)
  set_unique_stanza(:auto_updates, auto_updates.nil?) { auto_updates }
end

#caskroom_path ⇒ Object

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning. 



385
386
387
 
# File 'cask/dsl.rb', line 385

def caskroom_path
  cask.caskroom_path
end

#caveats(*strings, &block) ⇒ Object

Provide the user with cask-specific information at install time.



402
403
404
405
406
407
408
409
410
411
412
413
414
 
# File 'cask/dsl.rb', line 402

def caveats(*strings, &block)
  @caveats ||= DSL::Caveats.new(cask)
  if block
    @caveats.eval_caveats(&block)
  elsif strings.any?
    strings.each do |string|
      @caveats.eval_caveats { string }
    end
  else
    return @caveats.to_s
  end
  @caveats
end

#conflicts_with(**kwargs) ⇒ Object

Declare conflicts that keep a cask from installing or working correctly.



376
377
378
379
 
# File 'cask/dsl.rb', line 376

def conflicts_with(**kwargs)
  # TODO: Remove this constraint and instead merge multiple `conflicts_with` stanzas
  set_unique_stanza(:conflicts_with, kwargs.empty?) { DSL::ConflictsWith.new(**kwargs) }
end

#container(**kwargs) ⇒ Object

Sets the cask's container type or nested container path.

Examples

The container is a nested disk image:

container nested: "orca-#{version}.dmg"

The container should not be unarchived:

container type: :naked



274
275
276
277
278
 
# File 'cask/dsl.rb', line 274

def container(**kwargs)
  set_unique_stanza(:container, kwargs.empty?) do
    DSL::Container.new(**kwargs)
  end
end

#depends_on(**kwargs) ⇒ Object

Note:

Multiple dependencies can be specified.

Declare dependencies and requirements for a cask.



360
361
362
363
364
365
366
367
368
369
370
371
 
# File 'cask/dsl.rb', line 360

def depends_on(**kwargs)
  @depends_on ||= DSL::DependsOn.new
  @depends_on_set_in_block = true if @called_in_on_system_block
  return @depends_on if kwargs.empty?

  begin
    @depends_on.load(**kwargs)
  rescue RuntimeError => e
    raise CaskInvalidError.new(cask, e)
  end
  @depends_on
end

#depends_on_set_in_block? ⇒ Boolean

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

Returns:

  • (Boolean) 


10
 
# File 'sorbet/rbi/dsl/cask/dsl.rbi', line 10

def depends_on_set_in_block?; end

#deprecate!(date:, because:, replacement: nil) ⇒ Object

Note:

A warning will be shown when trying to install this cask.

Declare that a cask is no longer functional or supported.



456
457
458
459
460
461
462
463
 
# File 'cask/dsl.rb', line 456

def deprecate!(date:, because:, replacement: nil)
  @deprecation_date = Date.parse(date)
  return if @deprecation_date > Date.today

  @deprecation_reason = because
  @deprecation_replacement = replacement
  @deprecated = true
end

#deprecated? ⇒ Boolean

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

Returns:

  • (Boolean) 


13
 
# File 'sorbet/rbi/dsl/cask/dsl.rbi', line 13

def deprecated?; end

#desc(description = nil) ⇒ Object

Describes the cask.

Example

desc "Open-source code editor"



148
149
150
 
# File 'cask/dsl.rb', line 148

def desc(description = nil)
  set_unique_stanza(:desc, description.nil?) { description }
end

#disable!(date:, because:, replacement: nil) ⇒ Object

Note:

An error will be thrown when trying to install this cask.

Declare that a cask is no longer functional or supported.



470
471
472
473
474
475
476
477
478
479
480
481
482
483
 
# File 'cask/dsl.rb', line 470

def disable!(date:, because:, replacement: nil)
  @disable_date = Date.parse(date)

  if @disable_date > Date.today
    @deprecation_reason = because
    @deprecation_replacement = replacement
    @deprecated = true
    return
  end

  @disable_reason = because
  @disable_replacement = replacement
  @disabled = true
end

#disabled? ⇒ Boolean

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

Returns:

  • (Boolean) 


16
 
# File 'sorbet/rbi/dsl/cask/dsl.rbi', line 16

def disabled?; end

#discontinued? ⇒ Boolean

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

Returns:

  • (Boolean) 


416
417
418
419
 
# File 'cask/dsl.rb', line 416

def discontinued?
  odisabled "`discontinued?`", "`deprecated?` or `disabled?`"
  @caveats&.discontinued? == true
end

#homepage(homepage = nil) ⇒ Object

Sets the cask's homepage.

Example

homepage "https://code.visualstudio.com/"



182
183
184
 
# File 'cask/dsl.rb', line 182

def homepage(homepage = nil)
  set_unique_stanza(:homepage, homepage.nil?) { homepage }
end

#language(*args, default: false, &block) ⇒ Object

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning. 



186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
 
# File 'cask/dsl.rb', line 186

def language(*args, default: false, &block)
  if args.empty?
    language_eval
  elsif block
    @language_blocks ||= {}
    @language_blocks[args] = block

    return unless default

    if !@cask.allow_reassignment && @language_blocks.default.present?
      raise CaskInvalidError.new(cask, "Only one default language may be defined.")
    end

    @language_blocks.default = block
  else
    raise CaskInvalidError.new(cask, "No block given to language stanza.")
  end
end

#language_eval ⇒ Object

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

Raises:



205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
 
# File 'cask/dsl.rb', line 205

def language_eval
  return @language_eval if defined?(@language_eval)

  return @language_eval = nil if @language_blocks.blank?

  raise CaskInvalidError.new(cask, "No default language specified.") if @language_blocks.default.nil?

  locales = cask.config.languages
                .filter_map do |language|
                  Locale.parse(language)
                rescue Locale::ParserError
                  nil
                end

  locales.each do |locale|
    key = locale.detect(@language_blocks.keys)

    next if key.nil?

    return @language_eval = @language_blocks[key].call
  end

  @language_eval = @language_blocks.default.call
end

#languages ⇒ Object

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning. 



230
231
232
233
234
 
# File 'cask/dsl.rb', line 230

def languages
  return [] if @language_blocks.nil?

  @language_blocks.keys.flatten
end

#livecheck(&block) ⇒ Object

Automatically fetch the latest version of a cask from changelogs.



431
432
433
434
435
436
437
438
439
440
441
 
# File 'cask/dsl.rb', line 431

def livecheck(&block)
  @livecheck ||= Livecheck.new(cask)
  return @livecheck unless block

  if !@cask.allow_reassignment && @livecheck_defined
    raise CaskInvalidError.new(cask, "'livecheck' stanza may only appear once.")
  end

  @livecheck_defined = true
  @livecheck.instance_eval(&block)
end

#livecheck_defined? ⇒ Boolean

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

Returns:

  • (Boolean) 


19
 
# File 'sorbet/rbi/dsl/cask/dsl.rbi', line 19

def livecheck_defined?; end

#livecheckable? ⇒ Boolean

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

Deprecated.

Calling #livecheckable? is deprecated, use #livecheck_defined? instead.

Whether the cask contains a livecheck block. This is a legacy alias for #livecheck_defined?.

Returns:

  • (Boolean) 


446
447
448
449
 
# File 'cask/dsl.rb', line 446

def livecheckable?
  # odeprecated "`livecheckable?`", "`livecheck_defined?`"
  @livecheck_defined == true
end

#name(*args) ⇒ Object

Note:

Multiple names can be specified.

Specifies the cask's name.

Example

name "Visual Studio Code"



132
133
134
135
136
137
 
# File 'cask/dsl.rb', line 132

def name(*args)
  @name ||= []
  return @name if args.empty?

  @name.concat(args.flatten)
end

#on_system_blocks_exist? ⇒ Boolean

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

Returns:

  • (Boolean) 


22
 
# File 'sorbet/rbi/dsl/cask/dsl.rbi', line 22

def on_system_blocks_exist?; end

#respond_to_missing? ⇒ Boolean

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

Returns:

  • (Boolean) 


519
520
521
 
# File 'cask/dsl.rb', line 519

def respond_to_missing?(*)
  true
end

#set_unique_stanza(stanza, should_return) ⇒ Object

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning. 



152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
 
# File 'cask/dsl.rb', line 152

def set_unique_stanza(stanza, should_return)
  return instance_variable_get(:"@#{stanza}") if should_return

  unless @cask.allow_reassignment
    if instance_variable_defined?(:"@#{stanza}") && !@called_in_on_system_block
      raise CaskInvalidError.new(cask, "'#{stanza}' stanza may only appear once.")
    end

    if instance_variable_defined?(:"@#{stanza}_set_in_block") && @called_in_on_system_block
      raise CaskInvalidError.new(cask, "'#{stanza}' stanza may only be overridden once.")
    end
  end

  instance_variable_set(:"@#{stanza}_set_in_block", true) if @called_in_on_system_block
  instance_variable_set(:"@#{stanza}", yield)
rescue CaskInvalidError
  raise
rescue => e
  raise CaskInvalidError.new(cask, "'#{stanza}' stanza failed with: #{e}")
end

#sha256(arg = nil, arm: nil, intel: nil) ⇒ Object

Sets the cask's download checksum.

Example

For universal or single-architecture downloads:

sha256 "7bdb497080ffafdfd8cc94d8c62b004af1be9599e865e5555e456e2681e150ca"

For architecture-dependent downloads:

sha256 arm:   "7bdb497080ffafdfd8cc94d8c62b004af1be9599e865e5555e456e2681e150ca",
        intel: "b3c1c2442480a0219b9e05cf91d03385858c20f04b764ec08a3fa83d1b27e7b2"



318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
 
# File 'cask/dsl.rb', line 318

def sha256(arg = nil, arm: nil, intel: nil)
  should_return = arg.nil? && arm.nil? && intel.nil?

  set_unique_stanza(:sha256, should_return) do
    @on_system_blocks_exist = true if arm.present? || intel.present?

    val = arg || on_arch_conditional(arm:, intel:)
    case val
    when :no_check
      val
    when String
      Checksum.new(val)
    else
      raise CaskInvalidError.new(cask, "invalid 'sha256' value: #{val.inspect}")
    end
  end
end

#staged_path ⇒ Object

The staged location for this cask, including version number.



392
393
394
395
396
397
 
# File 'cask/dsl.rb', line 392

def staged_path
  return @staged_path if @staged_path

  cask_version = version || :unknown
  @staged_path = caskroom_path.join(cask_version.to_s)
end

#url(*args, **options, &block) ⇒ Object

Sets the cask's download URL.

Example

url "https://update.code.visualstudio.com/#{version}/#{arch}/stable"



245
246
247
248
249
250
251
252
253
254
255
 
# File 'cask/dsl.rb', line 245

def url(*args, **options, &block)
  caller_location = T.must(caller_locations).fetch(0)

  set_unique_stanza(:url, args.empty? && options.empty? && !block) do
    if block
      URL.new(*args, **options, caller_location:, dsl: self, &block)
    else
      URL.new(*args, **options, caller_location:)
    end
  end
end

#version(arg = nil) ⇒ Object

Sets the cask's version.

Example

version "1.88.1"

See Also:



290
291
292
293
294
295
296
297
298
 
# File 'cask/dsl.rb', line 290

def version(arg = nil)
  set_unique_stanza(:version, arg.nil?) do
    if !arg.is_a?(String) && arg != :latest
      raise CaskInvalidError.new(cask, "invalid 'version' value: #{arg.inspect}")
    end

    DSL::Version.new(arg)
  end
end