rumrunner 0.2.4 → 0.2.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ccce65ebe39fca8b6c649ee4584cc97763ff0f0341434b810f92b3de7b498157
-  data.tar.gz: 1f679cd595b16cda478a2b3b416e8040c17ec84fe889f9e969807a25435d6850
+  metadata.gz: 21ff1aee760e860283bf640e87bbdd97f5e6995caa5cdce7187c829e29417a67
+  data.tar.gz: f2acce2d5a033fce78a9010395063a8f44c8a45348de6eb08728aea43d873720
 SHA512:
-  metadata.gz: c4252be1a723094c039c2a4c8b15e0bde5947c3e967f1486653b71f36af91c5be08c944f58ce2c3a7eb998f9159abb81e2b2be7642c23284bc437ba4f48d596b
-  data.tar.gz: 1a79e2c3b769db27f089c92ce90fa9ea3aebe7fd2218f5e7db5c34ac91157e5d49cff8d51e998cbad044e948204aedf9ffac115f9ab6618d19114ff7c4a955a3
+  metadata.gz: 3b04b16707b81b88364e880fd3ba15dab605853735eaa67b537a1f9f293824a341befbceea5634ef1d8b6bbcdcf9bd63be841c0dfb768af97a8d662ad0870456
+  data.tar.gz: c9116ff64a6b9f4d77e724f49ec903f3c917a81acaab9b7905d4a96c0623aae6c77a3c9503dcb7aae4597c65458ee269dbf755ff629d4208d3df9ba7a4cfaa3d

data/README.md

@@ -1,5 +1,5 @@
-<img alt="rumrunner" src="./docs/icon.png"/>
 
+![Rum Runner](https://github.com/amancevice/rumrunner/blob/master/rumrunner.png?raw=true)
 [![Build Status](https://travis-ci.com/amancevice/rumrunner.svg?branch=master)](https://travis-ci.com/amancevice/rumrunner)
 [![codecov](https://codecov.io/gh/amancevice/rumrunner/branch/master/graph/badge.svg)](https://codecov.io/gh/amancevice/rumrunner)
 [![Gem Version](https://badge.fury.io/rb/rumrunner.svg)](https://badge.fury.io/rb/rumrunner)
@@ -23,6 +23,8 @@ Rum Runner has the following features:
 
 This project was born from using Makefiles to drive multi-stage builds. For the most part this worked really well, but it became a bit of an ordeal to write for more complex projects. This tool is an attempt to recreate that general technique with minimal annotation and limited assumptions.
 
+View the docs on [rubydoc.info](https://www.rubydoc.info/github/amancevice/rumrunner)
+
 ## Installation
 
 ```bash

data/lib/rumrunner/application.rb

@@ -1,7 +1,15 @@
+# frozen_string_literal: true
 require "rake"
 
 module Rum
+
+  ##
+  # Rum main application object. When invoking +rum+ from the
+  # command line, a Rum::Application object is created and run.
   class Application < Rake::Application
+
+    ##
+    # Default names for Rum Runner manifests.
     DEFAULT_RAKEFILES = [
       "rumfile",
       "Rumfile",
@@ -9,6 +17,7 @@ module Rum
       "Rumfile.rb",
     ]
 
+    ##
     # Initialize a Rumfile::Application object.
     def initialize
       super
@@ -16,6 +25,7 @@ module Rum
       @rakefiles = DEFAULT_RAKEFILES.dup
     end
 
+    ##
     # Initialize the command line parameters and app name.
     def init(app_name="rum", argv = ARGV)
       super "rum", argv

data/lib/rumrunner/docker.rb

@@ -1,8 +1,32 @@
+# frozen_string_literal: true
 require "forwardable"
 
 module Rum
+
+  ##
+  # Docker-specific objects and mixins.
   module Docker
+
+    ##
+    # Mixin to enable adding instance methods to a class that
+    # gets or sets-and-returns the given  attr of the instance.
     module AttrCallable
+
+      ##
+      # Method to define a method-accessor for each argument supplied.
+      # When extended by a class
+      #
+      # Example:
+      #  class Fizz
+      #    extend AttrCallable
+      #    attr_method_accessor :buzz
+      #  end
+      #
+      #  fizz = Fizz.new
+      #  fizz.buzz "foo"
+      #  fizz.buzz
+      #  # => "foo"
+      #
       def attr_method_accessor(*args)
         args.each do |var|
           define_method var do |value = nil|
@@ -17,54 +41,96 @@ module Rum
       end
     end
 
+    ##
+    # Mixin to enable runtime Docker command manipulation.
     module Executable
       include Enumerable
 
+      ##
+      # The +OPTIONS+ portion of a Docker command.
       attr_reader :options
 
+      ##
+      # Initialize Docker executable with +OPTIONS+ and evaluate the
+      # <tt>&block</tt> if given.
       def initialize(options:nil, &block)
         @options = options || Options.new
         instance_eval(&block) if block_given?
       end
 
+      ##
+      # Yield Docker command word by word.
       def each
         self.class.name.split(/::/)[1..-1].each{|x| yield x.downcase }
         @options.each{|x| yield x }
       end
 
+      ##
+      # Interpret missing methods as +OPTION+.
       def method_missing(m, *args, &block)
         @options.send(m, *args, &block)
         args.any? ? self : @options[m]
       end
 
+      ##
+      # Convert Docker command to string.
       def to_s
         to_a.join(" ")
       end
 
-      def with_defaults(options = {}, &block)
+      ##
+      # Assign default values to Docker command if not explicitly set.
+      #
+      # Example:
+      #   Run.new(&block).with_defaults(user: "fizz")
+      #
+      # Unless the <tt>&block</tt> contains a directive to set a value for +user+,
+      # it will be set to "fizz".
+      def with_defaults(options = {})
         options.reject{|k,v| @options.include? k }.each{|k,v| @options[k] << v }
         self
       end
     end
 
+    ##
+    # Collection of Docker command options to be applied on execution.
     class Options
       extend Forwardable
       include Enumerable
 
-      attr_reader :data
-
       def_delegators :@data, :[], :[]=, :include?, :to_h, :update
 
+      ##
+      # Initialize a new +OPTIONS+ collection for Docker executable.
+      # Evaluates the <tt>&block</tt> if given.
       def initialize(options = {}, &block)
         @data = Hash.new{|hash, key| hash[key] = [] }.update(options)
         instance_eval(&block) if block_given?
       end
 
+      ##
+      # Missing methods are interpreted as options to be added to the
+      # underlying collection.
+      #
+      # Example:
+      #   opts = Options.new
+      #   opts.fizz "buzz"
+      #   # => @data={:fizz=>["buzz"]}
+      #
       def method_missing(m, *args, &block)
         @data[m] += args unless args.empty?
         self
       end
 
+      ##
+      # Yield each option as a CLI flag/option, with +-+ or +--+ prefix.
+      #
+      # Example:
+      #   opts = Options.new
+      #   opts.fizz "buzz"
+      #   opts.to_a
+      #   # => ["--fizz", "buzz"]
+      #
       def each
         @data.each do |name, values|
           option = name.length == 1 ? "-#{name}" : "--#{name.to_s.gsub(/_/, "-")}"
@@ -76,7 +142,7 @@ module Rum
                 yield val
               end
             elsif [true, false].include? value
-              yield option
+              yield "#{option}=#{value}"
             else
               yield option
               yield value.to_s
@@ -85,40 +151,67 @@ module Rum
         end
       end
 
+      ##
+      # Convert options to string.
+      #
+      # Example:
+      #   opts = Options.new
+      #   opts.fizz "buzz"
+      #   opts.to_s
+      #   # => "--fizz buzz"
+      #
       def to_s
         to_a.join(" ")
       end
     end
 
+    ##
+    # Docker build command object.
     class Build
       extend AttrCallable
       include Executable
 
+      ##
+      # Access +PATH+ with method.
       attr_method_accessor :path
 
+      ##
+      # Initialize Docker build command with +OPTIONS+ and +PATH+.
+      # Evaluates the <tt>&block</tt> if given.
       def initialize(options:nil, path:nil, &block)
         @path = path
         super options: options, &block
       end
 
+      ##
+      # Yield the Docker build commmand word-by-word.
       def each
         super{|x| yield x }
         yield @path || "."
       end
     end
 
+    ##
+    # Docker run command object.
     class Run
       extend AttrCallable
       include Executable
 
+      ##
+      # Access +IMAGE+ and +CMD+ with method.
       attr_method_accessor :image, :cmd
 
+      ##
+      # Initialize Docker run command with +OPTIONS+, +IMAGE+, and +CMD+.
+      # Evaluates the <tt>&block</tt> if given.
       def initialize(options:nil, image:nil, cmd:nil, &block)
         @image = image
         @cmd   = cmd
         super options: options, &block
       end
 
+      ##
+      # Yield the Docker run commmand word-by-word.
       def each
         super{|x| yield x }
         yield @image
@@ -126,12 +219,19 @@ module Rum
       end
     end
 
+    ##
+    # Docker image object.
     class Image
       extend AttrCallable
       include Enumerable
 
+      ##
+      # Access components of the image reference by method.
       attr_method_accessor :registry, :username, :name, :tag
 
+      ##
+      # Initialize image by reference component.
+      # Evaluates <tt>&block</tt> if given.
       def initialize(name:, registry:nil, username:nil, tag:nil, &block)
         @registry = registry
         @username = username
@@ -140,19 +240,37 @@ module Rum
         instance_eval(&block) if block_given?
       end
 
+      ##
+      # Yield each non-nil component of the image reference in order.
       def each
         [@registry, @username, @name, @tag].compact.each{|x| yield x }
       end
 
+      ##
+      # Get the image reference without the @tag component.
       def family
         File.join *[@registry, @username, @name].compact.map(&:to_s)
       end
 
+      ##
+      # Convert the image reference to string.
       def to_s
         "#{family}:#{@tag || :latest}"
       end
 
       class << self
+
+        ##
+        # Parse a string as a Docker image reference
+        #
+        # Example:
+        #   Image.parse("image")
+        #   Image.parse("image:tag")
+        #   Image.parse("username/image")
+        #   Image.parse("username/image:tag")
+        #   Image.parse("registry:5000/username/image")
+        #   Image.parse("registry:5000/username/image:tag")
+        #
         def parse(string_or_symbol)
           string = string_or_symbol.to_s
           if string.count("/").zero? && string.count(":").zero?

data/lib/rumrunner/dsl_definition.rb

@@ -1,15 +1,24 @@
+# frozen_string_literal: true
 require "rake"
 
 require "rumrunner/manifest"
 
 module Rum
+
+  ##
+  # Defines the DSL methods for Rum Runner.
   module DSL
 
     private
 
-    # :call-seq:
-    #   rum image_name
-    #   rum image_name: digest_dir
+    ##
+    # Rum base task block.
+    #
+    # Example
+    #   rum :amancevice/rumrunner do
+    #     tag %x(git describe --tags --always)
+    #     # ...
+    #   end
     #
     def rum(*args, &block)
       name, _, deps = Rake.application.resolve_args(args)

data/lib/rumrunner/init.rb

@@ -2,6 +2,13 @@ require "rumrunner/docker"
 
 module Rum
   class << self
+
+    ##
+    # Helper to initialize a +Rumfile+
+    #
+    # Example:
+    #   $ ruby -r rumrunner -e Rum.init > Rumfile
+    #
     def init(input = nil, stdin = $stdin, stdout = $stdout, stderr = $stderr)
       # Get image name from stdin
       stderr.write "Docker image name [#{default = File.split(Dir.pwd).last}]: "

data/lib/rumrunner/manifest.rb

@@ -2,16 +2,28 @@ require "forwardable"
 require "rake"
 
 module Rum
+
+  ##
+  # Rum Runner Manifest for managing Docker commands.
   class Manifest
     extend Forwardable
     include Rake::DSL if defined? Rake::DSL
 
+    ##
+    # Access Docker image object.
     attr_reader :image
 
     def_delegator :@env, :<<, :env
     def_delegator :@root, :to_s, :root
     def_delegators :@image, :registry, :username, :name, :tag
 
+    ##
+    # Initialize new manifest with name and root path for caching
+    # build digests. Evaluates <tt>&block</tt> if given.
+    #
+    # Example:
+    #   Manifest.new(name: "my_image", root: ".docker")
+    #
     def initialize(name:, root:nil, &block)
       @name  = name
       @root  = root || :".docker"
@@ -20,11 +32,25 @@ module Rum
       instance_eval(&block) if block_given?
     end
 
+    ##
+    # Defines the default task for +rum+ executable.
+    #
+    # Example:
+    #   default :task_or_file
+    #   default :task_or_file => [:deps]
+    #
     def default(*args, &block)
       name = Rake.application.resolve_args(args).first
       task :default => name
     end
 
+    ##
+    # Defines generic +docker build+ task.
+    #
+    # Example:
+    #   build :name
+    #   build :name => [:deps]
+    #
     def build(*args, &block)
       name, _, deps = Rake.application.resolve_args(args)
       task name => deps do
@@ -32,6 +58,13 @@ module Rum
       end
     end
 
+    ##
+    # Defines generic +docker run+ task.
+    #
+    # Example:
+    #   run :name
+    #   run :name => [:deps]
+    #
     def run(*args, &block)
       name, _, deps = Rake.application.resolve_args(args)
       task name => deps do
@@ -39,6 +72,13 @@ module Rum
       end
     end
 
+    ##
+    # Defines +docker build+ task for the given stage.
+    #
+    # Example:
+    #   stage :name
+    #   stage :name => [:deps]
+    #
     def stage(*args, &block)
       name, _, deps = Rake.application.resolve_args(args)
 
@@ -96,6 +136,14 @@ module Rum
       deps.each{|dep| task :"#{dep}:clean" => :"#{name}:clean" }
     end
 
+    ##
+    # Defines +docker run+ task for redirecting a file from a running
+    # instance of the dependent stage's container to the local file
+    # system.
+    #
+    # Example:
+    #   artifact :name => [:stage]
+    #
     def artifact(*args, &block)
       name, _, deps = Rake.application.resolve_args(args)
 
@@ -125,6 +173,13 @@ module Rum
       end
     end
 
+    ##
+    # Defines +docker run+ task for shelling into the given stage.
+    #
+    # Example:
+    #   shell :stage
+    #   shell :stage => [:deps]
+    #
     def shell(*args, &block)
       target  = Rake.application.resolve_args(args).first
       name    = :"#{target}:shell"
@@ -143,6 +198,8 @@ module Rum
       end
     end
 
+    ##
+    # Install any remaining tasks for the manifest.
     def install
       install_clean
 
@@ -151,14 +208,21 @@ module Rum
 
     private
 
+    ##
+    # Get the shared build options for the Manifest.
     def build_options
       Docker::Options.new(build_arg: @env) unless @env.empty?
     end
 
+    ##
+    # Get the shared run options for the Manifest.
     def run_options
       Docker::Options.new(env: @env) unless @env.empty?
     end
 
+    ##
+    # Install :clean task for removing temporary Docker images and
+    # iidfiles.
     def install_clean
       desc "Remove any temporary images and products"
       task :clean do

data/lib/rumrunner/version.rb

@@ -1,3 +1,5 @@
 module Rum
-  VERSION = "0.2.4"
+  ##
+  # Rum Runner gem version.
+  VERSION = "0.2.5"
 end

data/lib/rumrunner.rb

@@ -5,7 +5,6 @@ require "rumrunner/dsl_definition"
 require "rumrunner/application"
 require "rumrunner/init"
 
-module Rum
-  class Error < StandardError
-  end
-end
+##
+# Rum Runner namespace.
+module Rum; end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rumrunner
 version: !ruby/object:Gem::Version
-  version: 0.2.4
+  version: 0.2.5
 platform: ruby
 authors:
 - Alexander Mancevice
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-07-23 00:00:00.000000000 Z
+date: 2019-07-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake