puppet 4.0.0 → 5.0.0

data/lib/puppet/file_system/uniquefile.rb

@@ -106,7 +106,7 @@ class Puppet::FileSystem::Uniquefile < DelegateClass(File)
         prefix = prefix_suffix[0]
         suffix = prefix_suffix[1]
       else
-        raise ArgumentError, "unexpected prefix_suffix: #{prefix_suffix.inspect}"
+        raise ArgumentError, _("unexpected prefix_suffix: %{value}") % { value: prefix_suffix.inspect }
     end
     t = Time.now.strftime("%Y%m%d")
     path = "#{prefix}#{t}-#{$$}-#{rand(0x100000000).to_s(36)}"
@@ -136,7 +136,7 @@ class Puppet::FileSystem::Uniquefile < DelegateClass(File)
       n ||= 0
       n += 1
       retry if !max_try or n < max_try
-      raise "cannot generate temporary name using `#{basename}' under `#{tmpdir}'"
+      raise _("cannot generate temporary name using `%{basename}' under `%{tmpdir}'") % { basename: basename, tmpdir: tmpdir }
     end
     path
   end
@@ -156,7 +156,7 @@ class Puppet::FileSystem::Uniquefile < DelegateClass(File)
     if $SAFE > 0
       tmp = @@systmpdir
     else
-      for dir in [ENV['TMPDIR'], ENV['TMP'], ENV['TEMP'], @@systmpdir, '/tmp']
+      for dir in [ Puppet::Util.get_env('TMPDIR'), Puppet::Util.get_env('TMP'), Puppet::Util.get_env('TEMP'), @@systmpdir, '/tmp']
         if dir and stat = File.stat(dir) and stat.directory? and stat.writable?
           tmp = dir
           break
@@ -175,7 +175,7 @@ class Puppet::FileSystem::Uniquefile < DelegateClass(File)
       mkdir(lock)
       yield
     ensure
-      rmdir(lock) if lock
+      rmdir(lock) if Puppet::FileSystem.exist?(lock)
     end
 
     def mkdir(*args)
@@ -187,4 +187,4 @@ class Puppet::FileSystem::Uniquefile < DelegateClass(File)
     end
   end
 
-end
+end

data/lib/puppet/file_system/windows.rb

@@ -3,22 +3,35 @@ require 'puppet/util/windows'
 
 class Puppet::FileSystem::Windows < Puppet::FileSystem::Posix
 
-  def exist?(path)
-    if ! Puppet.features.manages_symlinks?
-      return ::File.exist?(path)
-    end
+  def open(path, mode, options, &block)
+    # PUP-6959 mode is explicitly ignored until it can be implemented
+    # Ruby on Windows uses mode for setting file attributes like read-only and
+    # archived, not for setting permissions like POSIX
+    raise TypeError.new('mode must be specified as an Integer') if mode && !mode.is_a?(Numeric)
+    ::File.open(path, options, nil, &block)
+  end
 
-    path = path.to_str if path.respond_to?(:to_str) # support WatchedFile
-    path = path.to_s # support String and Pathname
+  def expand_path(path, dir_string = nil)
+    # ensure `nil` values behave like underlying File.expand_path
+    string_path = ::File.expand_path(path.nil? ? nil : path_string(path), dir_string)
+    # if no tildes, nothing to expand, no need to call Windows API, return original string
+    return string_path if !string_path.index('~')
 
     begin
-      if Puppet::Util::Windows::File.symlink?(path)
-        path = Puppet::Util::Windows::File.readlink(path)
-      end
-      ! Puppet::Util::Windows::File.stat(path).nil?
-    rescue # generally INVALID_HANDLE_VALUE which means 'file not found'
-      false
+      # no need to do existence check up front as GetLongPathName implies that check is performed
+      # and it should be the exception that files aren't actually present
+      string_path = Puppet::Util::Windows::File.get_long_pathname(string_path)
+    rescue Puppet::Util::Windows::Error => e
+      # preserve original File.expand_path behavior for file / path not found by returning string
+      raise if (e.code != Puppet::Util::Windows::File::ERROR_FILE_NOT_FOUND &&
+        e.code != Puppet::Util::Windows::File::ERROR_PATH_NOT_FOUND)
     end
+
+    string_path
+  end
+
+  def exist?(path)
+    return Puppet::Util::Windows::File.exist?(path)
   end
 
   def symlink(path, dest, options = {})
@@ -31,7 +44,7 @@ class Puppet::FileSystem::Windows < Puppet::FileSystem::Posix
     return 0 if dest_exists && dest_stat.ftype == 'directory'
 
     if dest_exists && dest_stat.ftype == 'file' && options[:force] != true
-      raise(Errno::EEXIST, "#{dest} already exists and the :force option was not specified")
+      raise(Errno::EEXIST, _("%{dest} already exists and the :force option was not specified") % { dest: dest })
     end
 
     if options[:noop] != true
@@ -62,7 +75,9 @@ class Puppet::FileSystem::Windows < Puppet::FileSystem::Posix
       stat = Puppet::Util::Windows::File.stat(file_name) rescue nil
 
       # sigh, Ruby + Windows :(
-      if stat && stat.ftype == 'directory'
+      if !stat
+        ::File.unlink(file_name) rescue Dir.rmdir(file_name)
+      elsif stat.ftype == 'directory'
         if Puppet::Util::Windows::File.symlink?(file_name)
           Dir.rmdir(file_name)
         else
@@ -91,16 +106,24 @@ class Puppet::FileSystem::Windows < Puppet::FileSystem::Posix
     Puppet::Util::Windows::Security.set_mode(mode, path.to_s)
   end
 
+  def read_preserve_line_endings(path)
+    contents = path.read( :mode => 'rb', :encoding => Encoding::UTF_8)
+    contents = path.read( :mode => 'rb', :encoding => Encoding::default_external) unless contents.valid_encoding?
+    contents = path.read unless contents.valid_encoding?
+
+    contents
+  end
+
   private
 
   def raise_if_symlinks_unsupported
     if ! Puppet.features.manages_symlinks?
-      msg = "This version of Windows does not support symlinks.  Windows Vista / 2008 or higher is required."
+      msg = _("This version of Windows does not support symlinks.  Windows Vista / 2008 or higher is required.")
       raise Puppet::Util::Windows::Error.new(msg)
     end
 
     if ! Puppet::Util::Windows::Process.process_privilege_symlink?
-      Puppet.warning "The current user does not have the necessary permission to manage symlinks."
+      Puppet.warning _("The current user does not have the necessary permission to manage symlinks.")
     end
   end
 

data/lib/puppet/file_system.rb

@@ -1,4 +1,5 @@
 module Puppet::FileSystem
+  require 'puppet/util'
   require 'puppet/file_system/path_pattern'
   require 'puppet/file_system/file_impl'
   require 'puppet/file_system/memory_file'
@@ -31,6 +32,15 @@ module Puppet::FileSystem
 
   # Opens the given path with given mode, and options and optionally yields it to the given block.
   #
+  # @param path [String, Pathname] the path to the file to operate on
+  # @param mode [Integer] The mode to apply to the file if it is created
+  # @param options [String] Extra file operation mode information to use
+  #   This is the standard mechanism Ruby uses in the IO class, and therefore
+  #   encoding may be specified explicitly as fmode : encoding or fmode : "BOM|UTF-*"
+  #   for example, a:ASCII or w+:UTF-8
+  # @yield The file handle, in the mode given by options, else read-write mode
+  # @return [Void]
+  #
   # @api public
   #
   def self.open(path, mode, options, &block)
@@ -97,10 +107,13 @@ module Puppet::FileSystem
   #
   # @param path [Pathname] the path to the file to operate on
   # @param mode [Integer] The mode to apply to the file if it is created
-  # @param options [Integer] Extra file operation mode information to use
-  #   (defaults to read-only mode)
+  # @param options [String] Extra file operation mode information to use
+  #   (defaults to read-only mode 'r')
+  #   This is the standard mechanism Ruby uses in the IO class, and therefore
+  #   encoding may be specified explicitly as fmode : encoding or fmode : "BOM|UTF-*"
+  #   for example, a:ASCII or w+:UTF-8
   # @param timeout [Integer] Number of seconds to wait for the lock (defaults to 300)
-  # @yield The file handle, in read-write mode
+  # @yield The file handle, in the mode given by options, else read-write mode
   # @return [Void]
   # @raise [Timeout::Error] If the timeout is exceeded while waiting to acquire the lock
   #
@@ -122,8 +135,21 @@ module Puppet::FileSystem
   #
   # @api public
   #
-  def self.read(path)
-    @impl.read(assert_path(path))
+  def self.read(path, opts = {})
+    @impl.read(assert_path(path), opts)
+  end
+
+  # Read a file keeping the original line endings intact. This
+  # attempts to open files using binary mode using some encoding
+  # overrides and falling back to IO.read when none of the
+  # encodings are valid.
+  #
+  # @return [String] The contents of the file
+  #
+  # @api public
+  #
+  def self.read_preserve_line_endings(path)
+    @impl.read_preserve_line_endings(assert_path(path))
   end
 
   # @return [String] The binary contents of the file
@@ -316,6 +342,21 @@ module Puppet::FileSystem
     @impl.pathname(path)
   end
 
+  # Produces a string representation of the opaque path handle, with expansions
+  # performed on ~.  For Windows, this means that C:\Users\Admini~1\AppData will
+  # be expanded to C:\Users\Administrator\AppData.  On POSIX filesystems, the
+  # value ~ will be expanded to something like /Users/Foo
+  #
+  # This method exists primarlily to resolve a Ruby deficiency where
+  # File.expand_path doesn't handle ~ in each segment on a Windows path
+  #
+  # @param path [Object] a path handle produced by {#pathname}
+  # @return [String] a string representation of the path
+  #
+  def self.expand_path(path, dir_string = nil)
+    @impl.expand_path(path, dir_string)
+  end
+
   # Asserts that the given path is of the expected type produced by #pathname
   #
   # @raise [ArgumentError] when path is not of the expected type

data/lib/puppet/forge/cache.rb

@@ -24,6 +24,7 @@ class Puppet::Forge
         uri = url.is_a?(::URI) ? url : ::URI.parse(url)
         unless cached_file.file?
           if uri.scheme == 'file'
+            # CGI.unescape butchers Uris that are escaped properly
             FileUtils.cp(URI.unescape(uri.path), cached_file)
           else
             # TODO: Handle HTTPS; probably should use repository.contact

data/lib/puppet/forge/errors.rb

@@ -25,15 +25,15 @@ module Puppet::Forge::Errors
       @uri     = options[:uri]
       original = options[:original]
 
-      super("Unable to verify the SSL certificate at #{@uri}", original)
+      super(_("Unable to verify the SSL certificate at %{uri}") % { uri: @uri }, original)
     end
 
     # Return a multiline version of the error message
     #
     # @return [String] the multiline version of the error message
     def multiline
-      <<-EOS.chomp
-Could not connect via HTTPS to #{@uri}
+      _(<<-EOS).chomp % { uri: @uri }
+Could not connect via HTTPS to %{uri}
   Unable to verify the SSL certificate
     The certificate may not be signed by a valid CA
     The CA bundle included with OpenSSL may not be valid or up to date
@@ -51,7 +51,7 @@ Could not connect via HTTPS to #{@uri}
       original = options[:original]
       @detail  = original.message
 
-      message = "Unable to connect to the server at #{@uri}. Detail: #{@detail}."
+      message = _("Unable to connect to the server at %{uri}. Detail: %{detail}.") % { uri: @uri, detail: @detail }
       super(message, original)
     end
 
@@ -59,10 +59,10 @@ Could not connect via HTTPS to #{@uri}
     #
     # @return [String] the multiline version of the error message
     def multiline
-      <<-EOS.chomp
-Could not connect to #{@uri}
+      _(<<-EOS).chomp % { uri: @uri, detail: @detail }
+Could not connect to %{uri}
   There was a network communications problem
-    The error we caught said '#{@detail}'
+    The error we caught said '%{detail}'
     Check your network connection and try again
       EOS
     end
@@ -89,7 +89,7 @@ Could not connect to #{@uri}
       rescue JSON::ParserError
       end
 
-      message = "Request to Puppet Forge failed. Detail: "
+      message = _("Request to Puppet Forge failed. Detail: ")
       message << @message << " / " if @message
       message << @response << "."
       super(message, original)
@@ -99,12 +99,12 @@ Could not connect to #{@uri}
     #
     # @return [String] the multiline version of the error message
     def multiline
-      message = <<-EOS.chomp
+      message = _(<<-EOS).chomp % { uri: @uri, response: @response }
 Request to Puppet Forge failed.
-  The server being queried was #{@uri}
-  The HTTP response we received was '#{@response}'
+  The server being queried was %{uri}
+  The HTTP response we received was '%{response}'
       EOS
-      message << "\n  The message we received said '#{@message}'" if @message
+      message << _("\n  The message we received said '%{message}'") % { message: @message } if @message
       message
     end
   end

data/lib/puppet/forge/repository.rb

@@ -45,7 +45,7 @@ class Puppet::Forge
     # Return a Net::HTTPResponse read for this +path+.
     def make_http_request(path, io = nil)
       Puppet.debug "HTTP GET #{@host}#{path}"
-      request = get_request_object(path)
+      request = get_request_object(@uri.path.chomp('/')+path)
       return read_response(request, io)
     end
 
@@ -57,6 +57,7 @@ class Puppet::Forge
       end
     end
 
+    # responsible for properly encoding a URI
     def get_request_object(path)
       headers = {
         "User-Agent" => user_agent,
@@ -72,7 +73,7 @@ class Puppet::Forge
         headers = headers.merge({"Authorization" => forge_authorization})
       end
 
-      request = Net::HTTP::Get.new(URI.escape(path), headers)
+      request = Net::HTTP::Get.new(Puppet::Util.uri_encode(path), headers)
 
       unless @uri.user.nil? || @uri.password.nil? || forge_authorization
         request.basic_auth(@uri.user, @uri.password)
@@ -90,7 +91,7 @@ class Puppet::Forge
     # @raise [Puppet::Forge::Errors::SSLVerifyError] if there is a problem
     #  verifying the remote SSL certificate
     def read_response(request, io = nil)
-      http_object = get_http_object
+      http_object = Puppet::Util::HttpProxy.get_http_object(uri)
 
       http_object.start do |http|
         response = http.request(request)
@@ -121,37 +122,6 @@ class Puppet::Forge
       end
     end
 
-    # Return a Net::HTTP::Proxy object constructed from the settings provided
-    # accessing the repository.
-    #
-    # This method optionally configures SSL correctly if the URI scheme is
-    # 'https', including setting up the root certificate store so remote server
-    # SSL certificates can be validated.
-    #
-    # @return [Net::HTTP::Proxy] object constructed from repo settings
-    def get_http_object
-      proxy_class = Net::HTTP::Proxy(Puppet::Util::HttpProxy.http_proxy_host, Puppet::Util::HttpProxy.http_proxy_port, Puppet::Util::HttpProxy.http_proxy_user, Puppet::Util::HttpProxy.http_proxy_password)
-      proxy = proxy_class.new(@uri.host, @uri.port)
-
-      if @uri.scheme == 'https'
-        cert_store = OpenSSL::X509::Store.new
-        cert_store.set_default_paths
-
-        proxy.use_ssl = true
-        proxy.verify_mode = OpenSSL::SSL::VERIFY_PEER
-        proxy.cert_store = cert_store
-      end
-
-      if Puppet[:http_debug]
-        proxy.set_debug_output($stderr)
-      end
-
-      proxy.open_timeout = Puppet[:http_connect_timeout]
-      proxy.read_timeout = Puppet[:http_read_timeout]
-
-      proxy
-    end
-
     # Return the local file name containing the data downloaded from the
     # repository at +release+ (e.g. "myuser-mymodule").
     def retrieve(release)
@@ -178,8 +148,7 @@ class Puppet::Forge
     def user_agent
       @user_agent ||= [
         @agent,
-        "Puppet/#{Puppet.version}",
-        "Ruby/#{RUBY_VERSION}-p#{RUBY_PATCHLEVEL} (#{RUBY_PLATFORM})",
+        Puppet[:http_user_agent]
       ].join(' ').freeze
     end
   end

data/lib/puppet/forge.rb

@@ -6,9 +6,9 @@ require 'tempfile'
 require 'uri'
 require 'pathname'
 require 'json'
-require 'semantic'
+require 'semantic_puppet'
 
-class Puppet::Forge < Semantic::Dependency::Source
+class Puppet::Forge < SemanticPuppet::Dependency::Source
   require 'puppet/forge/cache'
   require 'puppet/forge/repository'
   require 'puppet/forge/errors'
@@ -38,7 +38,7 @@ class Puppet::Forge < Semantic::Dependency::Source
   #     "releases"    => [{"version"=>"0.0.1"}, {"version"=>"0.0.2"}],
   #     "full_name"   => "puppetlabs/bacula",
   #     "version"     => "0.0.2",
-  #     "project_url" => "http://github.com/puppetlabs/puppetlabs-bacula",
+  #     "project_url" => "https://github.com/puppetlabs/puppetlabs-bacula",
   #     "desc"        => "bacula"
   #   }
   # ]
@@ -53,12 +53,13 @@ class Puppet::Forge < Semantic::Dependency::Source
   #   bad HTTP response
   def search(term)
     matches = []
-    uri = "/v3/modules?query=#{URI.escape(term)}"
+    uri = "/v3/modules?query=#{term}"
     if Puppet[:module_groups]
-      uri += "&module_groups=#{Puppet[:module_groups]}"
+      uri += "&module_groups=#{Puppet[:module_groups].gsub('+', ' ')}"
     end
 
     while uri
+      # make_http_request URI encodes parameters
       response = make_http_request(uri)
 
       if response.code == '200'
@@ -83,18 +84,19 @@ class Puppet::Forge < Semantic::Dependency::Source
   # Fetches {ModuleRelease} entries for each release of the named module.
   #
   # @param input [String] the module name to look up
-  # @return [Array<Semantic::Dependency::ModuleRelease>] a list of releases for
+  # @return [Array<SemanticPuppet::Dependency::ModuleRelease>] a list of releases for
   #         the given name
-  # @see Semantic::Dependency::Source#fetch
+  # @see SemanticPuppet::Dependency::Source#fetch
   def fetch(input)
     name = input.tr('/', '-')
     uri = "/v3/releases?module=#{name}"
     if Puppet[:module_groups]
-      uri += "&module_groups=#{Puppet[:module_groups]}"
+      uri += "&module_groups=#{Puppet[:module_groups].gsub('+', ' ')}"
     end
     releases = []
 
     while uri
+      # make_http_request URI encodes parameters
       response = make_http_request(uri)
 
       if response.code == '200'
@@ -114,22 +116,22 @@ class Puppet::Forge < Semantic::Dependency::Source
     @repository.make_http_request(*args)
   end
 
-  class ModuleRelease < Semantic::Dependency::ModuleRelease
+  class ModuleRelease < SemanticPuppet::Dependency::ModuleRelease
     attr_reader :install_dir, :metadata
 
-    def initialize(source, data)
+    def initialize(source, data, strict_semver = true)
       @data = data
       @metadata = meta = data['metadata']
 
       name = meta['name'].tr('/', '-')
-      version = Semantic::Version.parse(meta['version'])
+      version = SemanticPuppet::Version.parse(meta['version'])
       release = "#{name}@#{version}"
 
       if meta['dependencies']
         dependencies = meta['dependencies'].collect do |dep|
           begin
             Puppet::ModuleTool::Metadata.new.add_dependency(dep['name'], dep['version_requirement'], dep['repository'])
-            Puppet::ModuleTool.parse_module_dependency(release, dep)[0..1]
+            Puppet::ModuleTool.parse_module_dependency(release, dep, strict_semver)[0..1]
           rescue ArgumentError => e
             raise ArgumentError, "Malformed dependency: #{dep['name']}. Exception was: #{e}"
           end
@@ -195,7 +197,7 @@ class Puppet::Forge < Semantic::Dependency::Source
 
     def validate_checksum(file, checksum)
       if Digest::MD5.file(file.path).hexdigest != checksum
-        raise RuntimeError, "Downloaded release for #{name} did not match expected checksum"
+        raise RuntimeError, _("Downloaded release for %{name} did not match expected checksum") % { name: name }
       end
     end
 
@@ -203,7 +205,7 @@ class Puppet::Forge < Semantic::Dependency::Source
       begin
         Puppet::ModuleTool::Applications::Unpacker.unpack(file.path, destination)
       rescue Puppet::ExecutionFailure => e
-        raise RuntimeError, "Could not extract contents of module archive: #{e.message}"
+        raise RuntimeError, _("Could not extract contents of module archive: %{message}") % { message: e.message }
       end
     end
   end
@@ -216,7 +218,7 @@ class Puppet::Forge < Semantic::Dependency::Source
       begin
         ModuleRelease.new(self, release)
       rescue ArgumentError => e
-        Puppet.warning "Cannot consider release #{metadata['name']}-#{metadata['version']}: #{e}"
+        Puppet.warning _("Cannot consider release %{name}-%{version}: %{error}") % { name: metadata['name'], version: metadata['version'], error: e }
         false
       end
     end

data/lib/puppet/functions/alert.rb

@@ -0,0 +1,14 @@
+# Log a message on the server at level alert.
+Puppet::Functions.create_function(:alert, Puppet::Functions::InternalFunction) do
+  # @param values The values to log.
+  # @return [Undef]
+  dispatch :alert do
+    scope_param
+    repeated_param 'Any', :values
+    return_type 'Undef'
+  end
+
+  def alert(scope, *values)
+    Puppet::Util::Log.log_func(scope, :alert, values)
+  end
+end

data/lib/puppet/functions/annotate.rb

@@ -0,0 +1,108 @@
+# Handles annotations on objects. The function can be used in four different ways.
+#
+# With two arguments, an `Annotation` type and an object, the function returns the annotation
+# for the object of the given type, or `undef` if no such annotation exists.
+#
+# @example Using `annotate` with two arguments
+#
+# ~~~ puppet
+# $annotation = Mod::NickNameAdapter.annotate(o)
+#
+# $annotation = annotate(Mod::NickNameAdapter.annotate, o)
+# ~~~
+#
+# With three arguments, an `Annotation` type, an object, and a block, the function returns the
+# annotation for the object of the given type, or annotates it with a new annotation initialized
+# from the hash returned by the given block when no such annotation exists. The block will not
+# be called when an annotation of the given type is already present.
+#
+# @example Using `annotate` with two arguments and a block
+#
+# ~~~ puppet
+# $annotation = Mod::NickNameAdapter.annotate(o) || { { 'nick_name' => 'Buddy' } }
+#
+# $annotation = annotate(Mod::NickNameAdapter.annotate, o) || { { 'nick_name' => 'Buddy' } }
+# ~~~
+#
+# With three arguments, an `Annotation` type, an object, and an `Hash`, the function will annotate
+# the given object with a new annotation of the given type that is initialized from the given hash.
+# An existing annotation of the given type is discarded.
+#
+# @example Using `annotate` with three arguments where third argument is a Hash
+#
+# ~~~ puppet
+# $annotation = Mod::NickNameAdapter.annotate(o, { 'nick_name' => 'Buddy' })
+#
+# $annotation = annotate(Mod::NickNameAdapter.annotate, o, { 'nick_name' => 'Buddy' })
+# ~~~
+#
+# With three arguments, an `Annotation` type, an object, and an the string `clear`, the function will
+# clear the annotatation of the given type in the given object. The old annotation is returned if
+# it existed.
+#
+# @example Using `annotate` with three arguments where third argument is the string 'clear'
+#
+# ~~~ puppet
+# $annotation = Mod::NickNameAdapter.annotate(o, clear)
+#
+# $annotation = annotate(Mod::NickNameAdapter.annotate, o, clear)
+# ~~~
+#
+# With three arguments, the type `Pcore`, an object, and a Hash of hashes keyed by `Annotation` types,
+# the function will annotate the given object with all types used as keys in the given hash. Each annotation
+# is initialized with the nested hash for the respective type. The annotated object is returned.
+#
+# @example Add multiple annotations to a new instance of `Mod::Person` using the `Pcore` type.
+#
+# ~~~ puppet
+#   $person = Pcore.annotate(Mod::Person({'name' => 'William'}), {
+#     Mod::NickNameAdapter >= { 'nick_name' => 'Bill' },
+#     Mod::HobbiesAdapter => { 'hobbies' => ['Ham Radio', 'Philatelist'] }
+#   })
+# ~~~
+#
+# @since 5.0.0
+#
+Puppet::Functions.create_function(:annotate) do
+  dispatch :annotate do
+    param 'Type[Annotation]', :type
+    param 'Any', :value
+    optional_block_param 'Callable[0, 0]', :block
+  end
+
+  dispatch :annotate_new do
+    param 'Type[Annotation]', :type
+    param 'Any', :value
+    param 'Variant[Enum[clear],Hash[Pcore::MemberName,Any]]', :annotation_hash
+  end
+
+  dispatch :annotate_multi do
+    param 'Type[Pcore]', :type
+    param 'Any', :value
+    param 'Hash[Type[Annotation], Hash[Pcore::MemberName,Any]]', :annotations
+  end
+
+  # @param type [Annotation] the annotation type
+  # @param value [Object] the value to annotate
+  # @param block [Proc] optional block to produce the annotation hash
+  #
+  def annotate(type, value, &block)
+    type.implementation_class.annotate(value, &block)
+  end
+
+  # @param type [Annotation] the annotation type
+  # @param value [Object] the value to annotate
+  # @param annotation_hash [Hash{String => Object}] the annotation hash
+  #
+  def annotate_new(type, value, annotation_hash)
+    type.implementation_class.annotate_new(value, annotation_hash)
+  end
+
+  # @param type [Type] the Pcore type
+  # @param value [Object] the value to annotate
+  # @param annotations [Hash{Annotation => Hash{String => Object}}] hash of annotation hashes
+  #
+  def annotate_multi(type, value, annotations)
+    type.implementation_class.annotate(value, annotations)
+  end
+end