docker-template 0.2.0 → 0.3.0

data/lib/docker/template/cli.rb

@@ -0,0 +1,125 @@
+# ----------------------------------------------------------------------------
+# Frozen-string-literal: true
+# Copyright: 2015 - 2016 Jordon Bedwell - Apache v2.0 License
+# Encoding: utf-8
+# ----------------------------------------------------------------------------
+
+require "thor"
+
+module Docker
+  module Template
+    class CLI < Thor
+
+      # ----------------------------------------------------------------------
+      # docker-template build [repos [opts]]
+      # ----------------------------------------------------------------------
+
+      desc "build [REPOS [OPTS]]", "Build all (or some) of your repositories"
+      option :cache_only, :type => :boolean, :desc => "Only cache your repositories, don't build."
+      option :clean_only, :type => :boolean, :desc => "Only clean your repositories, don't build."
+      option :push_only,  :type => :boolean, :desc => "Only push  your repositories, don't build."
+      option :profile,    :type => :boolean, :desc => "Profile Memory."
+      option :tty,        :type => :boolean, :desc => "Enable TTY Output."
+      option :push,       :type => :boolean, :desc => "Push Repo After Building."
+      option :cache,      :type => :boolean, :desc => "Cache your repositories to cache."
+      option :mocking,    :type => :boolean, :desc => "Disable Certain Actions."
+      option :clean,      :type => :boolean, :desc => "Cleanup your caches."
+
+      # ----------------------------------------------------------------------
+
+      def build(*args)
+        repos = nil; with_profiling do
+          repos = Parser.new(args, options).parse.tap { |o| o.map( \
+            &:build) }.uniq(&:name).map(&:clean)
+        end
+
+      rescue Docker::Template::Error::StandardError => e
+        $stderr.puts Simple::Ansi.red(e.message)
+        exit e.respond_to?(:status) ? e.status : 1
+      end
+
+      # ----------------------------------------------------------------------
+      # docker-template list [options]
+      # ----------------------------------------------------------------------
+
+      desc "list [OPTS]", "List all possible builds."
+      option :grep, :type => :boolean, :desc => "Make --only a Regexp search."
+      option :only, :type => :string,  :desc => "Only a specific repo."
+
+      # ----------------------------------------------------------------------
+
+      def list
+        Parser.new([], {}).parse.each do |repo|
+          repo_s = repo_s = repo.to_s.gsub(/^[^\/]+\//, "")
+          next unless (only.is_a?(Regexp) && repo_s =~ only) \
+            || (only && repo_s == only) || !only
+
+          $stderr.print repo.to_s
+          $stderr.print " -> ", repo.aliased.to_s, "\n" if repo.alias?
+          $stderr.puts unless repo.alias?
+        end
+      rescue Docker::Template::Error::StandardError => e
+        $stderr.puts Simple::Ansi.red(e.message)
+        exit e.respond_to?(:status) \
+          ? e.status : 1
+      end
+
+      # ----------------------------------------------------------------------
+
+      no_tasks do
+        def only
+          return @only ||= begin
+            if !options.grep?
+              then options[
+                :only
+              ]
+
+            elsif options.only?
+              Regexp.new(options[
+                :only
+              ])
+            end
+          end
+        end
+
+        # --------------------------------------------------------------------
+        # When a user wishes to profile their builds to see memory being used.
+        # rubocop:disable Lint/RescueException
+        # --------------------------------------------------------------------
+
+        def with_profiling
+          if options.profile?
+            begin
+              require "memory_profiler"
+              MemoryProfiler.report(:top => 10_240) { yield }.pretty_print({\
+                :to_file => "mem.txt"
+              })
+            rescue LoadError
+              $stderr.puts "The gem 'memory_profiler' wasn't found."
+              $stderr.puts "You can install it with `gem install memory_profiler'"
+              abort "Hope you install it so you can report back."
+            end
+
+          else
+            yield
+          end
+
+        rescue Excon::Errors::SocketError
+          $stderr.puts "Unable to connect to your Docker Instance."
+          $stderr.puts "Are you absolutely sure that you have the Docker installed?"
+          abort "Unable to build your images."
+
+        rescue Exception
+          raise unless $ERROR_POSITION
+          $ERROR_POSITION.delete_if do |source|
+            source =~ %r!#{Regexp.escape(
+              __FILE__
+            )}!o
+          end
+
+          raise
+        end
+      end
+    end
+  end
+end

data/lib/docker/template/error.rb

@@ -1,20 +1,129 @@
+# ----------------------------------------------------------------------------
 # Frozen-string-literal: true
-# Copyright: 2015 Jordon Bedwell - Apache v2.0 License
+# Copyright: 2015 - 2016 Jordon Bedwell - Apache v2.0 License
 # Encoding: utf-8
+# ----------------------------------------------------------------------------
 
 module Docker
   module Template
     module Error
-      const_set :StandardError, Class.new(StandardError)
-      autoload :BadRepoName, "docker/template/error/bad_repo_name"
-      autoload :BadExitStatus, "docker/template/error/bad_exit_status"
-      autoload :InvalidTargzFile, "docker/template/error/invalid_targz_file"
-      autoload :NoSetupContextFound, "docker/template/error/no_setup_context_found"
-      autoload :NoRootfsCopyDir, "docker/template/error/no_rootfs_copy_dir"
-      autoload :InvalidRepoType, "docker/template/error/invalid_repo_type"
-      autoload :NoRootfsMkimg, "docker/template/error/no_rootfs_mkimg"
-      autoload :NotImplemented, "docker/template/error/not_implemented"
-      autoload :RepoNotFound, "docker/template/error/repo_not_found"
+      StandardError = Class.new(
+        StandardError
+      )
+
+      # ----------------------------------------------------------------------
+
+      class PlaceHolderError < StandardError
+        def initialize(error)
+          super "PLACEHOLDER ERROR: %s" % (
+            error
+          )
+        end
+      end
+
+      # ----------------------------------------------------------------------
+
+      class BadExitStatus < StandardError
+        attr_reader :status
+
+        def initialize(status)
+          super "Got bad exit status #{
+            @status = status
+          }"
+        end
+      end
+
+      # ----------------------------------------------------------------------
+
+      class BadRepoName < StandardError
+        def initialize(name)
+          super "Only a-z0-9_- are allowed. Invalid repo name: #{
+            name
+          }"
+        end
+      end
+
+      # ----------------------------------------------------------------------
+
+      class InvalidRepoType < StandardError
+        def initialize(type)
+          build_types = Template.config.build_types.join(", ")
+          super "Uknown repo type given '#{type}' not in '#{
+            build_types
+          }'"
+        end
+      end
+
+      # ----------------------------------------------------------------------
+
+      class InvalidTargzFile < StandardError
+        def initialize(tar_gz)
+          super "No data was given to the tar.gz file '#{
+            tar_gz.basename
+          }'"
+        end
+      end
+
+      # ----------------------------------------------------------------------
+
+      class InvalidYAMLFile < StandardError
+        def initialize(file)
+          super "The yaml data provided by #{file} is invalid and not a hash."
+        end
+      end
+
+      # ----------------------------------------------------------------------
+
+      class NoHookExists < StandardError
+        def initialize(base, point)
+          super "Unknown hook base '#{base}' or hook point '#{
+            point
+          }'"
+        end
+      end
+
+      # ----------------------------------------------------------------------
+
+      class NoRootMetadata < StandardError
+        def initialize
+          super "Metadata without the root flag must provide the root_metadata."
+        end
+      end
+
+      # ----------------------------------------------------------------------
+
+      class NoRootfsMkimg < StandardError
+        def initialize
+          super "Unable to find rootfs.rb in your repo folder."
+        end
+      end
+
+      # ----------------------------------------------------------------------
+
+      class NoSetupContext < StandardError
+        def initialize
+          super "No #setup_context method exists."
+        end
+      end
+
+      # ----------------------------------------------------------------------
+
+      class NotImplemented < StandardError
+        def initialize
+          super "The feature is not implemented yet, sorry about that."
+        end
+      end
+
+      # ----------------------------------------------------------------------
+
+      class RepoNotFound < StandardError
+        def initialize(repo = nil)
+          ending = repo ? "the repo '#{repo}'" : "your repo folder"
+          super "Unable to find #{
+            ending
+          }"
+        end
+      end
     end
   end
 end

data/lib/docker/template/logger.rb

@@ -0,0 +1,128 @@
+# ----------------------------------------------------------------------------
+# Frozen-string-literal: true
+# Copyright: 2015 - 2016 Jordon Bedwell - Apache v2.0 License
+# Encoding: utf-8
+# ----------------------------------------------------------------------------
+
+module Docker
+  module Template
+    class Logger
+      def initialize(builder = nil)
+        @lines = { 0 => 0 }
+        @builder = \
+          builder
+      end
+
+      # ----------------------------------------------------------------------
+
+      def increment
+        @lines.update({
+          @lines.size => @lines.size
+        })
+      end
+
+      # ----------------------------------------------------------------------
+      # A simple TTY stream that just prints out the data that it is given.
+      # This is the logger that most will use for most of their building.
+      # ----------------------------------------------------------------------
+
+      def tty(stream)
+        $stdout.print stream
+      end
+
+      # ----------------------------------------------------------------------
+      # A simple logger that accepts a multi-type stream.
+      # ----------------------------------------------------------------------
+
+      def simple(type, str)
+        type == :stderr ? $stderr.print(str) : $stdout.print(str)
+      end
+
+      # ----------------------------------------------------------------------
+      # A more complex streamer designed for the actual output of the Docker.
+      # ----------------------------------------------------------------------
+
+      def api(part, *_)
+        stream = JSON.parse(part)
+        retried ||= false
+
+        return progress_bar(stream) if stream.any_key?("progress", "progressDetail")
+        return output(stream["status"] || stream["stream"]) if stream.any_key?("status", "stream")
+        return progress_error(stream) if stream.any_key?("errorDetail", "error")
+
+        warn Simple::Ansi.red("Unhandled Stream.")
+        $stdout.puts(
+          part
+        )
+
+      # Addresses a Docker 1.9 bug.
+      rescue JSON::ParserError => e
+        if !retried
+          retried = true
+          part = "#{part}\" }"
+          retry
+        else
+          raise e
+        end
+      end
+
+      # ----------------------------------------------------------------------
+
+      def output(msg)
+        unless filter_matches?(msg)
+          $stdout.puts msg
+          increment
+        end
+      end
+
+      # ----------------------------------------------------------------------
+
+      def progress_error(stream)
+        abort Object::Simple::Ansi.red(
+          stream["errorDetail"]["message"]
+        )
+      end
+
+      # ----------------------------------------------------------------------
+
+      private
+      def progress_bar(stream)
+        id = stream["id"]
+
+        return unless id
+        before, diff = progress_diff(id)
+        $stderr.print before if before
+        str = stream["progress"] || stream["status"]
+        str = "#{id}: #{str}\r"
+
+        $stderr.print(Object::Simple::Ansi.jump(
+          str, diff
+        ))
+      end
+
+      # ----------------------------------------------------------------------
+
+      private
+      def progress_diff(id)
+        if @lines.key?(id)
+          return nil, @lines.size - @lines[id]
+        end
+
+        @lines[id] = @lines.size
+        before = "\n" unless @lines.one?
+        return before, 0
+      end
+
+      # ----------------------------------------------------------------------
+
+      private
+      def filter_matches?(msg)
+        return false unless @builder
+
+        @builder.repo.metadata["log_filters"].any? do |filter|
+          filter.is_a?(Regexp) && msg =~ filter || msg == filter
+        end
+      end
+    end
+  end
+end

data/lib/docker/template/metadata.rb

@@ -1,164 +1,627 @@
+# ----------------------------------------------------------------------------
 # Frozen-string-literal: true
-# Copyright: 2015 Jordon Bedwell - Apache v2.0 License
+# Copyright: 2015 - 2016 Jordon Bedwell - Apache v2.0 License
 # Encoding: utf-8
+# ----------------------------------------------------------------------------
+
+require "active_support/inflector"
+require "active_support/core_ext/hash/indifferent_access"
+require "yaml"
 
 module Docker
   module Template
     class Metadata
-      extend Forwardable, Routable
-
-      # Provides aliases for the root element so you can do something like:
-      #   * data["release"].fallback
-
-      ALIASES = {
-        "entry" => "entries",
-        "release" => "releases",
-        "version" => "versions",
-        "script" => "scripts",
-        "image" => "images"
-      }
-
-      def_delegator :@metadata, :keys
-      def_delegator :@metadata, :size
-      def_delegator :@metadata, :to_enum
-      def_delegator :@metadata, :has_key?
-      def_delegator :@metadata, :inspect
-      def_delegator :@metadata, :delete
-      def_delegator :@metadata, :each
-      def_delegator :@metadata, :to_h
-      def_delegator :@metadata, :key?
-      route_to_ivar :is_root, :@is_root, bool: true
-      route_to_hash :for_all, :self, :all
-
-      def initialize(metadata, root_metadata = metadata)
-        @is_root = metadata == root_metadata
-        @root_metadata = root_metadata || {}
-        @metadata = metadata || {}
-
-        return unless is_root?
-        @root_metadata = @metadata
-        @base = Template.config
+      attr_reader :data
+      extend Forwardable::Extended
+
+      # ----------------------------------------------------------------------
+      # rubocop:disable Style/MultilineBlockLayout
+      # ----------------------------------------------------------------------
+
+      OPTS_FILE = "opts.yml"
+      [Pathutil.allowed[:yaml][:classes], Array.allowed[:keys], \
+          Hash.allowed[:vals]].each do |v| v.push(
+            self, HashWithIndifferentAccess, Regexp
+          )
       end
 
+      # ----------------------------------------------------------------------
+      # rubocop:enable Style/MultilineBlockLayout
+      # ----------------------------------------------------------------------
+
+      DEFAULTS = HashWithIndifferentAccess.new({
+        "log_filters" => [],
+        "push" => false,
+        "cache" => false,
+        "type" => "normal",
+        "user" => "random_user",
+        "local_prefix" => "local",
+        "rootfs_base_img" => "envygeeks/ubuntu",
+        "maintainer" => "Random User <random.user@example.com>",
+        "name" => Template.root.basename.to_s,
+        "rootfs_template" => "alpine",
+        "cache_dir" => "cache",
+        "repos_dir" => "repos",
+        "copy_dir" => "copy",
+        "tag" => "latest",
+        "clean" => true,
+        "tty" => false,
+        "tags" => {}
+      }).freeze
+
+      # ----------------------------------------------------------------------
+      # @param data [Hash, self.class] - the main data.
+      # @param root [Hash, self.class] - the root data.
+      # Create a new instance of `self.class`.
       #
+      # @example ```
+      #   self.class.new({
+      #     :hello => :world
+      #   })
+      # ```
+      # ----------------------------------------------------------------------
+
+      def initialize(overrides, root: nil)
+        if root.is_a?(self.class)
+          then root = root.to_h({
+            :raw => true
+          })
+        end
+
+        if overrides.is_a?(self.class)
+          then overrides = overrides.to_h({
+            :raw => true
+          })
+        end
 
-      def as_gem_version
-        "#{self["repo"]}@#{self["version"].fallback}"
+        if root.nil?
+          overrides = overrides.stringify
+          gdata = Template.root.join(OPTS_FILE).read_yaml
+          @data = DEFAULTS.deep_merge(gdata.stringify).deep_merge(overrides)
+          tdata = Template.root.join(@data[:repos_dir], @data[:name], OPTS_FILE).read_yaml
+          @data = @data.deep_merge(tdata.stringify).deep_merge(overrides)
+          @data = @data.stringify.with_indifferent_access
+
+        else
+          @data = overrides.stringify.with_indifferent_access
+          @root_data = root.stringify \
+            .with_indifferent_access
+        end
       end
 
-      #
+      # ----------------------------------------------------------------------
+
+      def _shas
+        return @_shas ||= begin
+          self.class.new(Template.gem_root.join("shas.yml").read_yaml, {
+            :root => root_data
+          })
+        end
+      end
+
+      # ----------------------------------------------------------------------
+
+      def root_data
+        return @root_data || @data
+      end
+
+      # ----------------------------------------------------------------------
+
+      def root
+        Template.root.join(
+          root_data[:repos_dir], root_data[:name]
+        )
+      end
 
-      def aliased
-        tag = from_root("tag")
-        aliases = from_root("aliases")
-        return aliases[tag] if aliases.key?(tag)
-        tag
+      # ----------------------------------------------------------------------
+      # Check if a part of the hash or a value is inside.
+      # @param val [Anytning(), Hash] - The key or key => val you wish check.
+      # @example metadata.include?(:key => :val) => true|false
+      # @example metadata.include?(:key) => true|false
+      # ----------------------------------------------------------------------
+
+      def include?(val)
+        if val.is_a?(Hash)
+          then val.stringify.each do |k, v|
+            unless @data.key?(k) && @data[k] == v
+              return false
+            end
+          end
+
+          true
+        else
+          @data.include?(
+            val
+          )
+        end
       end
 
-      # Queries providing a default value if on the root repo hash otherwise
-      # returning the returned value, as a `self.class` if it's a Hash.
+      # ----------------------------------------------------------------------
+      # @param key [Anything()] the key you wish to pull.
+      # @note we make the getter slightly more indifferent because of tags.
+      # Pull an indifferent key from the hash.
+      # ----------------------------------------------------------------------
 
       def [](key)
-        key = determine_key(key)
-        val = @metadata[key]
+        val = begin
+          if key =~ /^\d+\.\d+$/
+            @data[key] || @data[
+              key.to_f
+            ]
+
+          elsif key =~ /^\d+$/
+            @data[key] || @data[
+              key.to_i
+            ]
+
+          else
+            @data[key]
+          end
+        end
+
+        if val.is_a?(Hash)
+          return self.class.new(val, {
+            :root => root_data
+          })
+        end
 
-        return try_default(key) if !val && is_root?
-        return self.class.new(val, @root_metadata) if val.is_a?(Hash)
         val
       end
 
-      #
+      # ----------------------------------------------------------------------
 
-      def tags
-        self["tags"].keys + self["aliases"].keys
+      def []=(key, val)
+        hash = { key => val }.stringify
+        @data.update(
+          hash
+        )
       end
 
-      #
+      # ----------------------------------------------------------------------
+
+      def update(hash)
+        @data.update(
+          hash.stringify
+        )
+      end
+
+      # ----------------------------------------------------------------------
+
+      def to_enum
+        @data.each_with_object({}) do |(k, v), h|
+          if v.is_a?(Hash)
+            then v = self.class.new(v, {
+              :root => root_data
+            })
+          end
+
+          h[k] = v
+        end.to_enum
+      end
+
+      # ----------------------------------------------------------------------
+      # Merge a hash into the metadata.  If you merge non-queryable data
+      # it will then get merged into the queryable data.
+      # ----------------------------------------------------------------------
 
       def merge(new_)
-        @metadata.merge!(new_)
+        if !queryable?(:query_data => new_) && queryable?
+          new_ = {
+            :all => new_
+          }
+        end
+
+        new_ = new_.stringify
+        self.class.new(@data.deep_merge(new_), {
+          :root => root_data
+        })
+      end
+
+      # ----------------------------------------------------------------------
+      # Destructive merging (@see self#merge)
+      # ----------------------------------------------------------------------
+
+      def merge!(new_)
+        if !queryable?(:query_data => new_) && queryable?
+          new_ = {
+            :all => new_
+          }
+        end
+
+        @data = @data.deep_merge(
+          new_.stringify
+        )
+
         self
       end
 
-      #
+      # --------------------------------------------------------------------
+      # Check if a hash is queryable. AKA has "all", "group", "tag".
+      # --------------------------------------------------------------------
 
-      def as_string_set
-        as_set.to_a.join(" ")
+      def queryable?(query_data: @data)
+        if query_data.is_a?(self.class)
+          then query_data \
+            .queryable?
+
+        elsif !query_data || !query_data.is_a?(Hash) || query_data.empty?
+          return false
+
+        else
+          (query_data.keys - %w(
+            group tag all
+          )).empty?
+        end
       end
 
-      #
+      # --------------------------------------------------------------------
+      # Fallback, determining which route is the best.  Tag > Group > All.
+      # --------------------------------------------------------------------
+
+      def fallback(group: current_group, tag: current_tag, query_data: @data)
+        if query_data.is_a?(self.class)
+          then query_data.fallback({
+            :group => group, :tag => tag
+          })
+
+        elsif !query_data || !query_data.is_a?(Hash) || query_data.empty?
+          return nil
+
+        else
+          by_tag(:tag => tag, :query_data => query_data) || \
+            by_parent_tag(:tag => tag, :query_data => query_data) || \
+            by_group(:group => group, :query_data => query_data) || \
+            by_parent_group(:tag => tag, :query_data => query_data) || \
+            for_all(:query_data => query_data)
+        end
+      end
+
+      # --------------------------------------------------------------------
 
-      def as_hash
-        {} \
-          .merge(for_all.to_h) \
-          .merge(by_type.to_h) \
-          .merge(by_tag. to_h)
+      def for_all(query_data: @data)
+        if query_data.is_a?(self.class)
+          then query_data \
+            .for_all
+
+        elsif !query_data || !query_data.is_a?(Hash)
+          return nil
+
+        else
+          query_data.fetch(
+            "all", nil
+          )
+        end
       end
 
-      #
+      # --------------------------------------------------------------------
 
-      def as_set
-        Set.new \
-          .merge(for_all.to_a) \
-          .merge(by_type.to_a) \
-          .merge(by_tag .to_a)
+      def by_tag(tag: current_tag, query_data: @data)
+        if query_data.is_a?(self.class)
+          then query_data.by_tag({
+            :tag => tag
+          })
+
+        elsif !query_data || !query_data.is_a?(Hash)
+          return nil
+
+        else
+          query_data.fetch("tag", {}).fetch(
+            tag, nil
+          )
+        end
       end
 
-      #
+      # ----------------------------------------------------------------------
+
+      def by_parent_tag(tag: current_tag, query_data: @data)
+        if aliased_tag == current_tag || !complex_alias?
+          return nil
 
-      def from_root(key)
-        root = self.class.new(@root_metadata)
-        root[key]
+        else
+          by_tag({
+            :query_data => query_data,
+            :tag => aliased_tag({
+              :tag => tag
+            })
+          })
+        end
       end
 
-      #
+      # --------------------------------------------------------------------
 
-      def fallback
-        by_tag || by_type || for_all
+      def by_group(group: current_group, query_data: @data)
+        if query_data.is_a?(self.class)
+          then query_data.by_group({
+            :group => group
+          })
+
+        elsif !query_data || !query_data.is_a?(Hash)
+          return nil
+
+        else
+          query_data.fetch("group", {}).fetch(
+            group, nil
+          )
+        end
       end
 
-      # Pulls data based on the given tag through anything that provides a
-      # "tag" key with the given tags. ("tags" is a `Hash`)
+      # ----------------------------------------------------------------------
 
-      def by_tag
-        return unless tag = aliased
-        return unless key?("tag")
-        hash = self["tag"]
-        hash[tag]
+      def by_parent_group(tag: current_tag, query_data: @data)
+        if aliased_tag == current_tag || !complex_alias?
+          return nil
+
+        else
+          by_group({
+            :query_data => query_data,
+            :group => aliased_group({
+              :tag => tag
+            })
+          })
+        end
       end
 
-      # Pull data based on the type given in { "tags" => { tag => type }}
-      # through anything that provides a "type" key with the type as a
-      # sub-key and the values.
+      # ----------------------------------------------------------------------
+      # Checks to see if the current metadata is an alias of another. This
+      # happens when the user has the tag in aliases but it's not complex.
+      # ----------------------------------------------------------------------
 
-      def by_type
-        return unless tag = aliased
-        type = from_root("tags")[tag]
-        return unless key?("type")
-        return unless type
+      def alias?
+        !!(aliased_tag && aliased_tag != tag)
+      end
 
-        hash = self["type"]
-        hash[type]
+      # ----------------------------------------------------------------------
+      # A complex alias happens when the user has an alias but also tries to
+      # add extra data, this allows them to use data from all parties. This
+      # allows them to reap the benefits of having shared data but sometimes
+      # independent data that diverges into it's own.
+      # ----------------------------------------------------------------------
+
+      def complex_alias?
+        if !alias?
+          return false
+
+        else
+          !!root_data.find do |_, v|
+            (v.is_a?(self.class) || v.is_a?(Hash)) && queryable?(:query_data => v) \
+              && by_tag(:query_data => v)
+          end
+        end
       end
 
-      #
+      # ----------------------------------------------------------------------
 
-      private
-      def determine_key(key)
-        if is_root? && !key?(key) && ALIASES.key?(key)
-          key = ALIASES[key]
+      def aliased_tag(tag: current_tag)
+        aliases = root_data[:aliases]
+        if aliases.nil? || !aliases.key?(tag)
+          tag
+
+        else
+          aliases[
+            tag
+          ]
         end
-        key
       end
 
-      #
+      # ----------------------------------------------------------------------
+
+      def aliased_group(tag: current_tag)
+        root_data[:tags][aliased_tag({
+          :tag => tag
+        })]
+      end
+
+      # ----------------------------------------------------------------------
+      # Converts the current meta into a string.
+      # ----------------------------------------------------------------------
+
+      def to_s(raw: false, shell: false)
+        if !raw && (mergeable_hash? || mergeable_array?)
+          to_a(:shell => shell).join(" #{
+            "\n" if shell
+          }")
+
+        elsif !raw && queryable?
+          then fallback \
+            .to_s
+
+        else
+          @data.to_s
+        end
+      end
+
+      # ----------------------------------------------------------------------
+
+      def to_a(raw: false, shell: false)
+        if raw
+          return to_h({
+            :raw => true
+          }).to_a
+
+        elsif !mergeable_array?
+          to_h.each_with_object([]) do |(k, v), a|
+            a << "#{k}=#{
+              shell ? v.to_s.shellescape : v
+            }"
+          end
+        else
+          (for_all || []) | (by_parent_group || []) | (by_group || []) | \
+            (by_parent_tag || []) | (by_tag || [])
+        end
+      end
+
+      # ----------------------------------------------------------------------
+      # Convert a `Metadata' into a normal hash. If `self' is queryable then
+      # we go and start merging values smartly.  This means that we will merge
+      # all the arrays into one another and we will merge hashes into hashes.
+      # ----------------------------------------------------------------------
+
+      def to_h(raw: false)
+        return @data.to_h if raw || !queryable? || !mergeable_hash?
+        keys = [for_all, by_group, by_parent_group, by_tag, \
+          by_parent_tag].compact.map(&:keys)
+
+        keys.reduce(:+).each_with_object({}) do |k, h|
+          vals = [for_all, by_group, by_parent_group, by_tag, \
+            by_parent_tag].compact
+
+          h[k] = \
+            if mergeable_array?(k)
+              vals.map { |v| v[k].to_a } \
+                .compact.reduce(
+                  :+
+                )
+
+            elsif mergeable_hash?(k)
+              vals.map { |v| v[k].to_h } \
+                .compact.reduce(
+                  :deep_merge
+                )
+
+            else
+              vals.find do |v|
+                v[k]
+              end \
+              [k]
+            end
+        end
+      end
+
+      # ----------------------------------------------------------------------
+
+      def mergeable_hash?(key = nil)
+        return false unless queryable?
+        vals = [by_parent_tag, by_parent_group, \
+          by_tag, for_all, by_group].compact
+
+        if key
+          vals = vals.map do |val|
+            val[key]
+          end
+        end
+
+        !vals.empty? && !vals.any? do |val|
+          !val.is_a?(Hash) && !val.is_a?(
+            self.class
+          )
+        end
+      end
+
+      # ----------------------------------------------------------------------
+
+      def mergeable_array?(key = nil)
+        return false unless queryable?
+        vals = [by_parent_tag, by_parent_group, \
+          by_tag, for_all, by_group].compact
+
+        if key
+          vals = vals.map do |val|
+            val[key]
+          end
+        end
+
+        !vals.empty? && !vals.any? do |val|
+          !val.is_a?(
+            Array
+          )
+        end
+      end
+
+      # ----------------------------------------------------------------------
+
+      def current_group
+        root_data[:tags][current_tag] ||
+          "normal"
+      end
+
+      # ----------------------------------------------------------------------
+      # HELPER: Get a list of all the tags.
+      # ----------------------------------------------------------------------
+
+      def tags
+        (root_data[:tags] || {}).keys | (root_data[:aliases] || {}).keys
+      end
+
+      # ----------------------------------------------------------------------
+      # HELPER: Get a list of all the groups.
+      # ----------------------------------------------------------------------
+
+      def groups
+        root_data["tags"].values.uniq
+      end
+
+      # ----------------------------------------------------------------------
 
       private
-      def try_default(key)
-        val = @base[key]
-        return self.class.new(val, @root_metadata) if val.is_a?(Hash)
-        val
+      def merge_or_override(val, new_val)
+        return new_val unless val
+        return val if val.is_a?(String) && !new_val || !new_val.is_a?(val.class)
+        return new_val.merge(val) if val.respond_to?(:merge)
+        return new_val | val if val.respond_to?(:|)
+      end
+
+      # ----------------------------------------------------------------------
+
+      private
+      def string_wrapper(obj, shell: false)
+        return obj if obj == true  ||  obj == false  ||  obj.nil?
+        return obj.to_s(:shell => shell) if obj.is_a?(self.class)
+        !obj.is_a?(Array) ? obj.to_s : obj.join(
+          "\s"
+        )
       end
+
+      # ----------------------------------------------------------------------
+
+      private
+      def method_missing(method, *args, shell: false, &block)
+        key = method.to_s.gsub(/\?$/, "")
+        val = self[key] || self[key.singularize] \
+           || self[key.pluralize]
+
+        if !args.empty? || block_given?
+          super
+
+        elsif method !~ /\?$/
+          string_wrapper(
+            val, :shell => shell
+          )
+
+        else
+          val != false && !val.nil? && \
+            !val.empty?
+        end
+      end
+
+      # ----------------------------------------------------------------------
+
+      alias deep_merge merge
+      alias group current_group
+      rb_delegate :for_all, :to => :self, :type => :hash, :key => :all
+      rb_delegate :current_tag, :to => :root_data, :key => :tag, :type => :hash
+      rb_delegate :tag, :to => :root_data, :type => :hash, :key => :tag
+      rb_delegate :root, :to => :@root, :type => :ivar, :bool => true
+
+      # ----------------------------------------------------------------------
+
+      rb_delegate :fetch,     :to => :@data
+      rb_delegate :delete,    :to => :@data
+      rb_delegate :empty?,    :to => :@data
+      rb_delegate :inspect,   :to => :@data
+      rb_delegate :values_at, :to => :@data
+      rb_delegate :values,    :to => :@data
+      rb_delegate :keys,      :to => :@data
+      rb_delegate :key?,      :to => :@data
+      rb_delegate :==,        :to => :@data
+
+      # ----------------------------------------------------------------------
+
+      rb_delegate :inject,            :to => :to_enum
+      rb_delegate :select,            :to => :to_enum
+      rb_delegate :each_with_object,  :to => :to_enum
+      rb_delegate :collect,           :to => :to_enum
+      rb_delegate :find,              :to => :to_enum
+      rb_delegate :each,              :to => :to_enum
     end
   end
 end