fig 0.1.77 → 0.1.79

data/lib/fig/package.rb

@@ -71,12 +71,16 @@ class Fig::Package
     return @statements.select { |statement| statement.is_a?(Fig::Statement::Retrieve) }
   end
 
-  def archive_urls
-    return @statements.select{|s| s.is_a?(Fig::Statement::Archive)}.map{|s| s.url}
+  def archive_locations
+    return @statements.
+      select{|s| s.is_a?(Fig::Statement::Archive)}.
+      map{|s| s.location}
   end
 
-  def resource_urls
-    return @statements.select{|s| s.is_a?(Fig::Statement::Resource)}.map{|s|s.url}
+  def resource_locations
+    return @statements.
+      select{|s| s.is_a?(Fig::Statement::Resource)}.
+      map{|s| s.location}
   end
 
   def applied_config_names()

data/lib/fig/package_definition_text_assembler.rb

@@ -1,3 +1,5 @@
+require 'fig/statement/grammar_version'
+require 'fig/unparser'
 require 'fig/unparser/v0'
 require 'fig/unparser/v1'
 
@@ -8,7 +10,10 @@ class Fig::PackageDefinitionTextAssembler
   attr_reader :input_statements
   attr_reader :output_statements
 
-  def initialize()
+  def initialize(emit_as_input_or_to_be_published_values)
+    @emit_as_input_or_to_be_published_values =
+      emit_as_input_or_to_be_published_values
+
     @input_statements   = []
     @output_statements  = []
     @header_text        = []
@@ -30,6 +35,9 @@ class Fig::PackageDefinitionTextAssembler
     @output_statements << statements
     @output_statements.flatten!
 
+    # Version gets determined by other statements, not by existing grammar.
+    @output_statements.reject! { |s| s.is_a? Fig::Statement::GrammarVersion }
+
     return
   end
 
@@ -52,37 +60,37 @@ class Fig::PackageDefinitionTextAssembler
   end
 
   def assemble_package_definition()
+    unparsed_statements, explanations = unparse_statements()
     definition =
-      [@header_text, unparse_statements(), @footer_text].flatten.join("\n")
+      [@header_text, unparsed_statements, @footer_text].flatten.join("\n")
     definition.gsub!(/\n{3,}/, "\n\n")
     definition.strip!
     definition << "\n"
 
-    return definition
+    return definition, explanations
   end
 
   private
 
   def unparse_statements()
-    versions = @output_statements.map {|s| s.minimum_grammar_version_required}
-    version = versions.max || 0
-
-    unparser_class = nil
-    if version == 1
-      unparser_class = Fig::Unparser::V1
-    else
-      unparser_class = Fig::Unparser::V0
-    end
-
-    unparser = unparser_class.new :emit_as_to_be_published
-    text = unparser.unparse(@output_statements)
-
-    # TODO: Until v1 grammar handling is done, ensure we don't emit anything
-    # old fig versions cannot handle.
-    if version != 0
-      raise "Reached a point where something could not be represented by the current grammar. Bailing out.\n\nWould have attempted:\n#{text}"
-    end
-
-    return text
+    unparser_class, explanations = Fig::Unparser.class_for_statements(
+      @output_statements, @emit_as_input_or_to_be_published_values
+    )
+
+    grammar_statement =
+      Fig::Statement::GrammarVersion.new(
+        nil,
+        %Q<[synthetic statement created in #{__FILE__} line #{__LINE__}]>,
+        %q<Fake grammar version that shouldn't be used because the Unparser should determine what gets emitted.>
+      )
+
+    unparser = unparser_class.new @emit_as_input_or_to_be_published_values
+    text = unparser.unparse( [grammar_statement] + @output_statements )
+
+    explanations.unshift(
+      "Publishing using the #{unparser.grammar_description} grammar."
+    )
+
+    return text, explanations
   end
 end

data/lib/fig/parser.rb

@@ -8,7 +8,7 @@ require 'fig/package_parse_error'
 require 'fig/parser_package_build_state'
 require 'fig/statement'
 require 'fig/url'
-require 'fig/url_access_error'
+require 'fig/url_access_disallowed_error'
 require 'fig/user_input_error'
 
 module Fig; end
@@ -82,9 +82,7 @@ class Fig::Parser
     return 0 if not statement
 
     version = statement.version
-    # TODO: restore v1 grammar.
-    # if version > 1
-    if version > 0
+    if version > 1
       raise Fig::PackageParseError.new(
         %Q<Don't know how to parse grammar version #{version}#{statement.position_string()}.>
       )
@@ -198,7 +196,7 @@ class Fig::Parser
       end
     end
 
-    raise Fig::URLAccessError.new(bad_urls, descriptor) if not bad_urls.empty?
+    raise Fig::URLAccessDisallowedError.new(bad_urls, descriptor) if not bad_urls.empty?
 
     return
   end

data/lib/fig/parser_package_build_state.rb

@@ -79,19 +79,22 @@ class Fig::ParserPackageBuildState
     )
   end
 
-  def new_asset_statement(statement_class, keyword_node, url_node)
-    url = url_node.text_value
+  def new_asset_statement(statement_class, keyword_node, location_node)
+    raw_location = location_node.text_value
 
-    need_to_glob = statement_class.validate_and_process_escapes_in_url!(url) {
-      |error_description|
+    tokenized_location =
+      statement_class.validate_and_process_escapes_in_location(raw_location) do
+        |error_description|
 
-      raise_invalid_value_parse_error(
-        keyword_node, url_node, 'URL/path', error_description
-      )
-    }
+        raise_invalid_value_parse_error(
+          keyword_node, location_node, 'URL/path', error_description
+        )
+      end
 
+    location = tokenized_location.to_expanded_string
+    need_to_glob = ! tokenized_location.single_quoted?
     return statement_class.new(
-      node_location(keyword_node), source_description, url, need_to_glob
+      node_location(keyword_node), source_description, location, need_to_glob
     )
   end
 
@@ -161,11 +164,9 @@ class Fig::ParserPackageBuildState
     statement_class, keyword_node, value_node
   )
     name, value = statement_class.parse_name_value(value_node.text_value) {
-      raise_invalid_value_parse_error(
-        keyword_node,
-        value_node,
-        'value',
-        statement_class.const_get(:ARGUMENT_DESCRIPTION)
+      description = statement_class.const_get(:ARGUMENT_DESCRIPTION)
+      raise Fig::PackageParseError.new(
+        %Q<Invalid #{keyword_node.text_value} statement: "#{value_node.text_value}" #{description}#{node_location_description(value_node)}>
       )
     }
     return statement_class.new(

data/lib/fig/repository.rb

@@ -6,8 +6,8 @@ require 'tmpdir'
 
 require 'fig'
 require 'fig/at_exit'
+require 'fig/file_not_found_error'
 require 'fig/logging'
-require 'fig/not_found_error'
 require 'fig/package_cache'
 require 'fig/package_descriptor'
 require 'fig/parser'
@@ -212,11 +212,13 @@ class Fig::Repository
     if @remote_repository_version.nil?
       temp_dir = base_temp_dir()
       @operating_system.delete_and_recreate_directory(temp_dir)
-      remote_version_file = "#{remote_repository_url()}/#{VERSION_FILE_NAME}"
+      remote_version_file = Fig::URL.append_path_components(
+        remote_repository_url(), [VERSION_FILE_NAME]
+      )
       local_version_file = File.join(temp_dir, "remote-#{VERSION_FILE_NAME}")
       begin
         @operating_system.download(remote_version_file, local_version_file)
-      rescue Fig::NotFoundError
+      rescue Fig::FileNotFoundError
         # The download may create an empty file, so get rid of it.
         if File.exist?(local_version_file)
           File.unlink(local_version_file)
@@ -265,17 +267,13 @@ class Fig::Repository
     temp_dir = package_download_temp_dir(descriptor)
     begin
       install_package(descriptor, temp_dir)
-    rescue Fig::NotFoundError => error
+    rescue Fig::FileNotFoundError => error
       Fig::Logging.fatal \
         "Package #{descriptor.to_string()} not found in remote repository. (Was looking for #{error.path}.)"
 
-      delete_local_package(descriptor)
-
       raise Fig::RepositoryError.new
     rescue StandardError => exception
-      Fig::Logging.fatal %Q<Install failed, cleaning up: #{exception}>
-
-      delete_local_package(descriptor)
+      Fig::Logging.fatal %Q<Install failed: #{exception}>
 
       raise Fig::RepositoryError.new
     ensure
@@ -289,28 +287,43 @@ class Fig::Repository
     remote_fig_file = remote_fig_file_for_package(descriptor)
     local_dir       = local_dir_for_package(descriptor)
     local_fig_file  = fig_file_for_package_download(local_dir)
-    return if not @operating_system.download(remote_fig_file, local_fig_file)
 
-    @operating_system.delete_and_recreate_directory(temp_dir)
+    if @operating_system.path_up_to_date? remote_fig_file, local_fig_file
+      Fig::Logging.debug \
+        "Skipping update of #{descriptor.to_string} because it looks like #{local_fig_file} is up-to-date."
+      return
+    end
+
+    temp_fig_file   = fig_file_for_package_download(temp_dir)
 
-    temp_fig_file = fig_file_for_package_download(temp_dir)
+    FileUtils.rm_rf temp_dir
+    if File.exist? local_dir
+      FileUtils.mkdir_p File.dirname(temp_dir)
+      FileUtils.cp_r local_dir, temp_dir, :preserve => true
+    else
+      FileUtils.mkdir_p temp_dir
+    end
 
-    @operating_system.download(remote_fig_file, temp_fig_file)
+    return if ! @operating_system.download(remote_fig_file, temp_fig_file)
 
     package = read_package_from_directory(temp_dir, descriptor)
 
-    package.archive_urls.each do |archive_url|
-      if not Fig::URL.is_url?(archive_url)
-        archive_url = remote_dir_for_package(descriptor) + '/' + archive_url
+    remote_package_directory = remote_dir_for_package(descriptor)
+    package.archive_locations.each do |archive_location|
+      if not Fig::URL.is_url?(archive_location)
+        archive_location = Fig::URL.append_path_components(
+          remote_package_directory, [archive_location]
+        )
       end
-      @operating_system.download_and_unpack_archive(archive_url, temp_dir)
+      @operating_system.download_and_unpack_archive(archive_location, temp_dir)
     end
-    package.resource_urls.each do |resource_url|
-      if not Fig::URL.is_url?(resource_url)
-        resource_url =
-          remote_dir_for_package(descriptor) + '/' + resource_url
+    package.resource_locations.each do |resource_location|
+      if not Fig::URL.is_url?(resource_location)
+        resource_location = Fig::URL.append_path_components(
+          remote_package_directory, [resource_location]
+        )
       end
-      @operating_system.download_resource(resource_url, temp_dir)
+      @operating_system.download_resource(resource_location, temp_dir)
     end
 
     FileUtils.rm_rf(local_dir)
@@ -346,12 +359,10 @@ class Fig::Repository
     return package
   end
 
-  def delete_local_package(descriptor)
-    FileUtils.rm_rf(local_dir_for_package(descriptor))
-  end
-
   def remote_fig_file_for_package(descriptor)
-    "#{remote_dir_for_package(descriptor)}/#{PACKAGE_FILE_IN_REPO}"
+    return Fig::URL.append_path_components(
+      remote_dir_for_package(descriptor), [PACKAGE_FILE_IN_REPO]
+    )
   end
 
   def local_fig_file_for_package(descriptor)
@@ -363,7 +374,9 @@ class Fig::Repository
   end
 
   def remote_dir_for_package(descriptor)
-    "#{remote_repository_url()}/#{descriptor.name}/#{descriptor.version}"
+    return Fig::URL.append_path_components(
+      remote_repository_url(), [descriptor.name, descriptor.version]
+    )
   end
 
   def local_dir_for_package(descriptor)

data/lib/fig/repository_package_publisher.rb

@@ -6,8 +6,8 @@ require 'tmpdir'
 
 require 'fig'
 require 'fig/at_exit'
+require 'fig/file_not_found_error'
 require 'fig/logging'
-require 'fig/not_found_error'
 require 'fig/package_cache'
 require 'fig/package_definition_text_assembler'
 require 'fig/package_descriptor'
@@ -37,7 +37,8 @@ class Fig::RepositoryPackagePublisher
   attr_writer :local_only
 
   def initialize()
-    @text_assembler = Fig::PackageDefinitionTextAssembler.new
+    @text_assembler =
+      Fig::PackageDefinitionTextAssembler.new :emit_as_to_be_published
 
     return
   end
@@ -111,7 +112,11 @@ class Fig::RepositoryPackagePublisher
     add_output_statements_and_create_resource_archive()
     add_unparsed_text()
 
-    file_content = @text_assembler.assemble_package_definition()
+    file_content, explanations = @text_assembler.assemble_package_definition()
+    if Fig::Logging.debug?
+      explanations.each {|explanation| Fig::Logging.debug explanation}
+    end
+
     begin
       Fig::Parser.new(nil, false).parse_package(
         @descriptor,
@@ -161,17 +166,6 @@ class Fig::RepositoryPackagePublisher
   def assemble_output_statements()
     @resource_paths = []
 
-    if (
-          @text_assembler.input_statements.empty? \
-      ||  ! @text_assembler.input_statements[0].is_a?(Fig::Statement::GrammarVersion)
-    )
-      @text_assembler.add_output Fig::Statement::GrammarVersion.new(
-        nil,
-        %Q<[synthetic statement created in #{__FILE__} line #{__LINE__}]>,
-        0 # Grammar version
-      )
-    end
-
     @text_assembler.input_statements.each do
       |statement|
 
@@ -186,11 +180,11 @@ class Fig::RepositoryPackagePublisher
   end
 
   def add_asset_to_output_statements(asset_statement)
-    if Fig::URL.is_url? asset_statement.url
+    if Fig::URL.is_url? asset_statement.location
       @text_assembler.add_output asset_statement
     elsif asset_statement.is_a? Fig::Statement::Archive
       if asset_statement.requires_globbing?
-        expand_globs_from( [asset_statement.url] ).each do
+        expand_globs_from( [asset_statement.location] ).each do
           |file|
 
           @text_assembler.add_output(
@@ -206,9 +200,9 @@ class Fig::RepositoryPackagePublisher
         @text_assembler.add_output asset_statement
       end
     elsif asset_statement.requires_globbing?
-      @resource_paths.concat expand_globs_from( [asset_statement.url] )
+      @resource_paths.concat expand_globs_from( [asset_statement.location] )
     else
-      @resource_paths << asset_statement.url
+      @resource_paths << asset_statement.location
     end
 
     return
@@ -220,7 +214,7 @@ class Fig::RepositoryPackagePublisher
 
       file = Fig::Repository::RESOURCES_FILE
       @operating_system.create_archive(file, @resource_paths)
-      Fig::AtExit.add { File.delete(file) }
+      Fig::AtExit.add { FileUtils.rm_f(file) }
 
       @text_assembler.add_output(
         Fig::Statement::Archive.new(
@@ -249,19 +243,20 @@ class Fig::RepositoryPackagePublisher
 
   def publish_asset(asset_statement)
     asset_name = asset_statement.asset_name()
-    asset_remote = "#{@remote_dir_for_package}/#{asset_name}"
+    asset_remote =
+      Fig::URL.append_path_components @remote_dir_for_package, [asset_name]
 
-    if Fig::URL.is_url? asset_statement.url
+    if Fig::URL.is_url? asset_statement.location
       asset_local = File.join(publish_temp_dir(), asset_name)
 
       begin
-        @operating_system.download(asset_statement.url, asset_local)
-      rescue Fig::NotFoundError
-        Fig::Logging.fatal "Could not download #{asset_statement.url}."
+        @operating_system.download(asset_statement.location, asset_local)
+      rescue Fig::FileNotFoundError
+        Fig::Logging.fatal "Could not download #{asset_statement.location}."
         raise Fig::RepositoryError.new
       end
     else
-      asset_local = asset_statement.url
+      asset_local = asset_statement.location
       check_asset_path(asset_local)
     end
 

data/lib/fig/runtime_environment.rb

@@ -9,7 +9,7 @@ require 'fig/statement/include'
 require 'fig/statement/path'
 require 'fig/statement/set'
 require 'fig/user_input_error'
-require 'fig/unparser/v0'
+require 'fig/unparser'
 
 module Fig; end
 
@@ -99,37 +99,31 @@ class Fig::RuntimeEnvironment
     return
   end
 
-  def execute_shell(command)
+  def execute_command_line(base_package, base_config, descriptor, command_line)
+    package, * =
+      determine_package_for_execution(base_package, base_config, descriptor)
+
+    expanded_command_line =
+      command_line.map {
+        |argument| expand_command_line_argument(argument, base_package)
+      }
+
     @variables.with_environment do
-      yield command.map{|arg| expand_command_line_argument(arg, nil, nil)}
+      yield expanded_command_line
     end
 
     return
   end
 
-  def execute_config(base_package, base_config, descriptor, args, &block)
-    config_name =
-      determine_config_to_executed(base_package, base_config, descriptor)
-
-    package = nil
-
-    if descriptor
-      name    = descriptor.name || base_package.name
-      package = lookup_package(
-        name,
-        descriptor.version,
-        Fig::IncludeBacktrace.new(
-          nil,
-          Fig::PackageDescriptor.new(name, descriptor.version, config_name)
-        )
-      )
-    else
-      package = base_package
-    end
+  def execute_config(
+    base_package, base_config, descriptor, extra_arguments, &block
+  )
+    package, config_name =
+      determine_package_for_execution(base_package, base_config, descriptor)
 
     command_statement = package[config_name].command_statement
     if command_statement
-      execute_command(command_statement, args, package, nil, &block)
+      execute_command(command_statement, extra_arguments, package, &block)
     else
       raise Fig::UserInputError.new(
         %Q<The "#{package.to_s}" package with the "#{config_name}" configuration does not contain a command.>
@@ -140,35 +134,35 @@ class Fig::RuntimeEnvironment
   end
 
   # In order for this to work correctly, any Overrides need to be processed
-  # before any other kind of Statement.  The Configuration class guarantees
-  # that those come first in its set of Statements.
-  def apply_config_statement(base_package, statement, backtrace)
+  # before any other kind of Statement.  The Statement::Configuration class
+  # guarantees that those come first in its set of Statements.
+  def apply_config_statement(package, statement, backtrace)
     case statement
     when Fig::Statement::Path
-      prepend_variable(base_package, statement.name, statement.value, backtrace)
+      prepend_variable(package, statement, backtrace)
     when Fig::Statement::Set
-      set_variable(base_package, statement.name, statement.value, backtrace)
+      set_variable(package, statement, backtrace)
     when Fig::Statement::Include
-      include_config(base_package, statement.descriptor, backtrace)
+      include_config(package, statement.descriptor, backtrace)
     when Fig::Statement::Override
       backtrace.add_override(statement)
     when Fig::Statement::Command
       # Skip - has no effect on environment.
     else
-      unparser = Fig::Unparser::V0.new :emit_as_to_be_published
-      text = unparser.unparse([statement]).strip
-      raise "Unexpected statement in a config block: #{text}"
+      text, * =
+        Fig::Unparser.determine_version_and_unparse(statement, :emit_as_input)
+      raise "Unexpected statement in a config block: #{text.strip}"
     end
 
     return
   end
 
-  def include_config(base_package, descriptor, backtrace)
+  def include_config(starting_package, descriptor, backtrace)
     resolved_descriptor = nil
 
     # Check to see if this include has been overridden.
     if backtrace
-      override_package_name = descriptor.name || base_package.name
+      override_package_name = descriptor.name || starting_package.name
       override = backtrace.get_override(override_package_name)
       if override
         resolved_descriptor =
@@ -181,7 +175,7 @@ class Fig::RuntimeEnvironment
 
     new_backtrace = Fig::IncludeBacktrace.new(backtrace, resolved_descriptor)
     package = lookup_package(
-      resolved_descriptor.name || base_package.name,
+      resolved_descriptor.name || starting_package.name,
       resolved_descriptor.version,
       new_backtrace
     )
@@ -200,24 +194,26 @@ class Fig::RuntimeEnvironment
 
       statement = @retrieves[name]
       if statement.loaded_but_not_referenced?
-        unparser = Fig::Unparser::V0.new :emit_as_to_be_published
-        text = unparser.unparse([statement]).strip
+        text, * = Fig::Unparser.determine_version_and_unparse(
+          [statement], :emit_as_input
+        )
         Fig::Logging.warn \
-          %Q<The #{name} variable was never referenced or didn't need expansion, so "#{text}"#{statement.position_string} was ignored.>
+          %Q<The #{name} variable was never referenced or didn't need expansion, so "#{text.strip}"#{statement.position_string} was ignored.>
       end
     end
   end
 
   private
 
-  def set_variable(base_package, name, value, backtrace)
-    expanded_value =
-      expand_variable_as_path_and_process_retrieves(
-        name, value, base_package, backtrace
-      )
+  def set_variable(package, statement, backtrace)
+    expanded_value = expand_variable_as_path_and_process_retrieves(
+      statement, package, backtrace
+    )
+    name = statement.name
     @variables[name] = expanded_value
 
     if Fig::Logging.debug?
+      value = statement.value
       expanded_message =
         expanded_value == value ? ''  \
                                 : %Q< (expanded from "#{value}")>
@@ -230,14 +226,15 @@ class Fig::RuntimeEnvironment
     return
   end
 
-  def prepend_variable(base_package, name, value, backtrace)
-    expanded_value =
-      expand_variable_as_path_and_process_retrieves(
-        name, value, base_package, backtrace
-      )
+  def prepend_variable(package, statement, backtrace)
+    expanded_value = expand_variable_as_path_and_process_retrieves(
+      statement, package, backtrace
+    )
+    name = statement.name
     @variables.prepend_variable(name, expanded_value)
 
     if Fig::Logging.debug?
+      value = statement.value
       expanded_message =
         expanded_value == value ? ''  \
                                 : %Q< ("#{value}" expanded to "#{expanded_value}")>
@@ -275,6 +272,31 @@ class Fig::RuntimeEnvironment
     return package
   end
 
+  def determine_package_for_execution(base_package, base_config, descriptor)
+    config_name =
+      determine_config_to_executed(base_package, base_config, descriptor)
+
+    package = nil
+
+    if descriptor
+      package_name = descriptor.name || base_package.name
+      package      = lookup_package(
+        package_name,
+        descriptor.version,
+        Fig::IncludeBacktrace.new(
+          nil,
+          Fig::PackageDescriptor.new(
+            package_name, descriptor.version, config_name
+          )
+        )
+      )
+    else
+      package = base_package
+    end
+
+    return [package, config_name]
+  end
+
   def determine_config_to_executed(base_package, base_config, descriptor)
     return base_config if base_config
 
@@ -301,44 +323,44 @@ class Fig::RuntimeEnvironment
     return package.primary_config_name || Fig::Package::DEFAULT_CONFIG
   end
 
-  def execute_command(command_statement, args, package, backtrace)
+  def execute_command(command_statement, extra_arguments, package)
     @variables.with_environment do
       argument =
         expand_command_line_argument(
-          "#{command_statement.command} #{args.join(' ')}", backtrace, package
+          "#{command_statement.command} #{extra_arguments.join(' ')}", package
         )
 
-      yield expand_at_signs_in_path(argument, package, backtrace).split(' ')
+      yield argument.split(' ')
     end
 
     return
   end
 
   def expand_variable_as_path_and_process_retrieves(
-    variable_name, variable_value, base_package, backtrace
+    statement, package, backtrace
   )
-    return variable_value unless base_package && base_package.name
+    return statement.value unless package && package.name
 
     variable_value =
-      expand_at_signs_in_path(variable_value, base_package, backtrace)
+      expand_at_signs_in_path(statement.value, package, backtrace)
 
-    return variable_value if not @retrieves.member?(variable_name)
+    return variable_value if not @retrieves.member?(statement.name)
 
     return retrieve_files(
-      variable_name, variable_value, base_package, backtrace
+      statement.name, variable_value, package, backtrace
     )
   end
 
-  def retrieve_files(variable_name, variable_value, base_package, backtrace)
+  def retrieve_files(variable_name, variable_value, package, backtrace)
     check_source_existence(
-      variable_name, variable_value, base_package, backtrace
+      variable_name, variable_value, package, backtrace
     )
 
     destination_path =
-      derive_retrieve_destination(variable_name, variable_value, base_package)
+      derive_retrieve_destination(variable_name, variable_value, package)
 
     @working_directory_maintainer.switch_to_package_version(
-      base_package.name, base_package.version
+      package.name, package.version
     )
     @working_directory_maintainer.retrieve(variable_value, destination_path)
 
@@ -346,20 +368,20 @@ class Fig::RuntimeEnvironment
   end
 
   def check_source_existence(
-    variable_name, variable_value, base_package, backtrace
+    variable_name, variable_value, package, backtrace
   )
     return if File.exists?(variable_value) || File.symlink?(variable_value)
 
     raise_repository_error(
-      %Q<In #{base_package}, the #{variable_name} variable points to a path that does not exist ("#{variable_value}", after expansion).>,
+      %Q<In #{package}, the #{variable_name} variable points to a path that does not exist ("#{variable_value}", after expansion).>,
       backtrace,
-      base_package
+      package
     )
   end
 
-  def derive_retrieve_destination(variable_name, variable_value, base_package)
+  def derive_retrieve_destination(variable_name, variable_value, package)
     retrieve_path =
-      get_retrieve_path_with_substitution(variable_name, base_package)
+      get_retrieve_path_with_substitution(variable_name, package)
 
     # A '//' in the variable value tells us to preserve path
     # information after the '//' when doing a retrieve.
@@ -376,56 +398,83 @@ class Fig::RuntimeEnvironment
     return File.join(retrieve_path, File.basename(variable_value))
   end
 
-  def expand_at_signs_in_path(path, base_package, backtrace)
+  def expand_at_signs_in_path(path, package, backtrace)
     expanded_path =
-      replace_at_signs_with_package_references(path, base_package)
-    check_for_bad_escape(expanded_path, path, base_package, backtrace)
+      replace_at_signs_with_package_references(path, package)
+    check_for_bad_escape(expanded_path, path, package, backtrace)
 
     return collapse_backslashes_for_escaped_at_signs(expanded_path)
   end
 
-  def replace_at_signs_with_package_references(arg, base_package)
-    return arg.gsub(
+  def replace_at_signs_with_package_references(argument, package)
+    return argument.gsub(
       %r<
         (?: ^ | \G)           # Zero-width anchor.
-        ( [^\\@]* (?:\\{2})*) # An even number of leading backslashes
+        ( [^\\@]* )           # A bunch of not-slashes-or-at-signs
+        ( \\* )               # Any leading backslashes
         \@                    # The package indicator
       >x
     ) do |match|
-      backslashes = $1 || ''
-      backslashes + base_package.directory
+      frontmatter, backslashes = $1, $2
+
+      replacement = backslashes.length % 2 == 1 ? '@' : package.directory
+
+      "#{frontmatter}#{backslashes}#{replacement}"
     end
   end
 
-  def expand_command_line_argument(arg, backtrace, package)
-    package_substituted = expand_named_package_references(arg, backtrace)
-    check_for_bad_escape(package_substituted, arg, package, backtrace)
+  def expand_command_line_argument(argument, package)
+    package_substituted = expand_package_references(argument, package)
+    check_for_bad_escape(package_substituted, argument, package, nil)
 
     return collapse_backslashes_for_escaped_at_signs(package_substituted)
   end
 
-  def expand_named_package_references(arg, backtrace)
-    return arg.gsub(
+  def expand_package_references(argument, package)
+    return argument.gsub(
       # TODO: Refactor package name regex into PackageDescriptor constant.
       %r<
         (?: ^ | \G)           # Zero-width anchor.
-        ( [^\\@]* (?:\\{2})*) # An even number of leading backslashes
+        ( [^\\@]* )           # A bunch of not-slashes-or-at-signs
+        ( \\* )               # Any leading backslashes
         \@                    # The package indicator
-        ( [a-zA-Z0-9_.-]+ )   # Package name
+        ( [a-zA-Z0-9_.-]* )   # Package name
       >x
     ) do |match|
-      backslashes = $1 || ''
-      package_name = $2
+      frontmatter, backslashes, package_name = $1, $2, $3
+
+      expand_package_reference(
+        frontmatter, backslashes, package_name, package
+      )
+    end
+  end
+
+  def expand_package_reference(
+    frontmatter, backslashes, package_name, starting_package
+  )
+    if backslashes.length % 2 == 1
+      return "#{frontmatter}#{backslashes}@#{package_name}"
+    end
+
+    package = nil
+    if ! package_name.empty?
       package = get_package(package_name)
       if package.nil?
         raise_repository_error(
           %Q<Command-line referenced the "#{package_name}" package, which has not been referenced by any other package, so there's nothing to substitute with.>,
-          backtrace,
+          nil,
           nil
         )
       end
-      backslashes + package.directory
+    else
+      package = starting_package
     end
+
+    if package && package.directory
+      return "#{frontmatter}#{backslashes}#{package.directory}"
+    end
+
+    return "#{frontmatter}#{backslashes}@"
   end
 
   # The value is expected to have had any @ substitution already done, but
@@ -450,11 +499,11 @@ class Fig::RuntimeEnvironment
     return string.gsub(%r< \\ ([\\@]) >x, '\1')
   end
 
-  def get_retrieve_path_with_substitution(name, base_package)
-    retrieve_statement = @retrieves[name]
+  def get_retrieve_path_with_substitution(variable_name, package)
+    retrieve_statement = @retrieves[variable_name]
     retrieve_statement.referenced(true)
 
-    return retrieve_statement.path.gsub(/ \[package\] /x, base_package.name)
+    return retrieve_statement.path.gsub(/ \[package\] /x, package.name)
   end
 
   def raise_repository_error(message, backtrace, package)