scriptster 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 717f92265d71abf28271c0da1d1c743d642d7c0d
-  data.tar.gz: b7c73d085a0686d41f40a18649264f9396515bc8
+  metadata.gz: 29ca137ce4703b707c5f4f423e16a52ad0f20fc0
+  data.tar.gz: 1188b577e385809ff3408006ec80cacf3ef4f97a
 SHA512:
-  metadata.gz: be02f5207e7ea2e71c87e1543628f9ffe40514ee72960e696af84e3277d4d7f780d544af1ec063195a39f4401bec540c1d0b98ed4a251436a92a368f37da2c17
-  data.tar.gz: f623e30ac8bf6ab3c371fb720c741770f96902787f5b02ad73c8b6790a10aad47ff537bbf9edf5e46089887d3a9d85c23645f45c3cd796d2fde787ad2be207ba
+  metadata.gz: 61d9c1c7b7713cee0d0f15b9734daa9b9bf171e613d4fcd4dd522104ddda9eb03efb3298aaea1d7e2e42782a2514ff48bfaa730e61e4d111a02937a8ae67a8c7
+  data.tar.gz: 2725686e52306e57082efe967a2ec5576c6cc2e72eb75cc189d985a303d26c8b4878f258abfb9ddb48f73ffeee10776b692f66affe6f40e2af9fa30ef6c826ab

data/.travis.yml

@@ -0,0 +1,15 @@
+language: ruby
+cache: bundler
+
+env:
+  global:
+    - RUBY_GC_MALLOC_LIMIT=90000000
+    - RUBY_GC_HEAP_FREE_SLOTS=200000
+
+matrix:
+  fast_finish: true
+
+before_install:
+  - cp gemrc ~/.gemrc
+
+script: "bundle exec rspec"

data/CHANGELOG.md

@@ -0,0 +1,6 @@
+## 0.1.0 (2014-10-26)
+
+Features:
+
+  - the first relatively stable release
+

data/README.md

@@ -1,39 +1,67 @@
 # Scriptster
 
-A small library to make your scripts hip ;-).
+[![Gem Version](https://badge.fury.io/rb/scriptster.png)](http://badge.fury.io/rb/scriptster)
+[![Inline docs](http://inch-ci.org/github/pazdera/scriptster.png)](http://inch-ci.org/github/pazdera/scriptster)
+[![Build Status](https://travis-ci.org/pazdera/scriptster.svg)](https://travis-ci.org/pazdera/scriptster)
 
-## Installation
+Scriptster is a small library to help you writing scripts in Ruby. It
+is only consists of two functions and it's especially useful for apps
+that uses many external tools through the shell.
 
-Add this line to your application's Gemfile:
+The two basic things this library focuses on are
+ * Running shell commands
+ * Providing nice logs/status messages about what happened
 
-    gem 'scriptster'
-
-And then execute:
-
-    $ bundle
-
-Or install it yourself as:
-
-    $ gem install scriptster
+See the examples bellow.
 
 ## Usage
 
-TODO: Write usage instructions here
-
 ```ruby
 require 'scriptster'
+```
 
+It is not necessary to configure scriptster before using it, in case you're
+fine with the default settings. But if not, the configure method offers
+many options to change. For the full list of options, please refer to
+the [docs](http://www.rubydoc.info/github/pazdera/scriptster/master/frames).
+
+```ruby
 Scriptster::configure do |conf|
-  conf[:name] = "my-script"
+  conf.name = "my-script"
+  conf.theme = :dark
 end
+```
+
+The following snippet demonstrates exactly how would you use **scriptster**
+in practice:
 
+```ruby
 Scriptster::log :info, "Starting ..."
 
-Scriptster::ShellCmd.new "git branch",
+Scriptster::cmd.new "git branch",
   :show_out = true,
   :show_err = true,
 ```
 
+The `log` method has one more argument available and the `cmd` method
+has other options that you can use. Again, you will find more in the
+[docs](http://www.rubydoc.info/github/pazdera/scriptster/master/frames).
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'scriptster'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install scriptster
+
+
 ## Contributing
 
 1. Fork it ( https://github.com/[my-github-username]/scriptster/fork )

data/gemrc

@@ -0,0 +1,2 @@
+install: --no-rdoc --no-ri
+update:  --no-rdoc --no-ri

data/lib/scriptster.rb

@@ -25,23 +25,49 @@ require "scriptster/logger"
 require "scriptster/shellcmd"
 require "scriptster/configuration"
 
+# The public interface of scriptster is simple. It consists of two
+# functions, cmd and log. The module can be used directly or included
+# in your class.
 module Scriptster
+  # Pass a message to the logger.
+  #
+  # @see Logger.log
   def self.log(*args)
     Logger::log *args
   end
 
+  # The same as {Scriptster.log}.
+  #
+  # @see .log
   def log(*args)
-    Logger::log *args
+    self.log *args
   end
 
+  # Execute a shell command
+  #
+  # @see ShellCmd
   def self.cmd(*args)
     ShellCmd.new *args
   end
 
+  # The same as {Scriptster.cmd}.
+  #
+  # @see .cmd
   def cmd(*args)
-    ShellCmd.new *args
+    self.cmd *args
   end
 
+  # Use this method to reconfigure the library.
+  #
+  # @example
+  #   Scriptster::configure do |conf|
+  #     conf.name = "my-script"
+  #     conf.colours = :light
+  #     conf.timestamps = false
+  #   end
+  #
+  # @yield [c] An instance of the {Configuration} class.
+  # @see Configuration
   def self.configure
     c = Configuration.new
     yield c

data/lib/scriptster/configuration.rb

@@ -23,30 +23,52 @@
 require "scriptster/logger"
 require "scriptster/shellcmd"
 
+
 module Scriptster
+  # The configuration obejct used in the {Scriptster.configure} method.
+  #
+  # @attr [String] name  The name of the script to be displayed in the logs.
+  # @attr [Symbol] verbosity  The minimum verbosity to of messages to be displayed.
+  # @attr [String, File, StringIO] file  A log file that all messages will be written to.
+  # @attr [Boolean] timestamps  Include timestamps in log messages.
+  # @attr [Symbol, Proc] colours  Desired colour theme (either predefined or custom Proc).
+  #                               @see ColourThemes
+  # @attr [String] log_format  Template for each line in the logs
   class Configuration
-    attr_writer :name, :verbosity, :file, :timestamps, :scheme
+    attr_writer :name, :verbosity, :file, :colours, :log_format, :theme
 
     def initialize
       @name = File.basename($0)
       @verbosity = :verbose
       @file = nil
       @timestamps = true
-      @scheme = :dark
+      @colours = :dark
+      @log_format = "%{timestamp} %{name} %{type} %{message}"
     end
 
-    # Put the settings from this object in effect
+    # Put the settings from this object in effect.
+    #
+    # This function will distribute the configuration to the
+    # appropriate objects and modules.
     def apply
       Logger.set_name @name if @name
       Logger.set_verbosity @verbosity if @verbosity
       Logger.set_file @file if @file
-      Logger.show_timestamps if @timestamps
+      Logger.set_format @log_format if @log_format
 
-      ColourSchemes.send @scheme
+      if @colours.is_a? Proc
+        @colours.call
+      else
+        ColourThemes.send @colours.to_sym
+      end
     end
   end
 
-  module ColourSchemes
+  # A collection of predefined colour settings.
+  #
+  # It's basically a just configuring the tco library.
+  module ColourThemes
+    # The colour theme for dark terminals.
     def self.dark
       Tco::configure do |conf|
         conf.names["green"] = "#99ad6a"
@@ -114,6 +136,7 @@ module Scriptster
       end
     end
 
+    # The colour scheme for dark terminals.
     def self.light
       Tco::configure do |conf|
         conf.names["green"] = "#99ad6a"

data/lib/scriptster/logger.rb

@@ -24,11 +24,18 @@
 require "tco"
 
 module Scriptster
+  # This module contains the logging function and related configuration.
   module Logger
+    # The name of the script.
     @@name = nil
+
+    # The IO object to log to.
     @@file = nil
+
+    # Show timestamps flag.
     @@timestamps = false
 
+    # Supported message types.
     @@message_types = {
       :info => "info",
       :warn => "WARN",
@@ -36,7 +43,10 @@ module Scriptster
       :debug => "dbg?"
     }
 
+    # The default verobosity level.
     @@verbosity = :verbose
+
+    # Supported verbosity levels.
     @@verbosity_levels = {
       :quiet => 0,
       :essential => 1,
@@ -45,10 +55,18 @@ module Scriptster
       :verbose => 4
     }
 
+    @@format = "%{timestamp} %{name} %{type} %{message}"
+
+    # A setter for the script name.
+    #
+    # @param [String] name  Desired script name.
     def self.set_name(name)
       @@name = name
     end
 
+    # A setter for for logger verbosity.
+    #
+    # @param [Symbol] level  Desired verbosity level.
     def self.set_verbosity(level)
       msg = "Message verbosity level not recognised (#{})."
       raise msg unless @@verbosity_levels.has_key? level.to_sym
@@ -56,26 +74,60 @@ module Scriptster
       @@verbosity = level.to_sym
     end
 
+    # A setter for the log file.
+    #
+    # @param [String, StringIO, File] file  A path or an IO object.
     def self.set_file(file)
       @@file.close if @@file
       @@file = nil
-      @@file = File.open file, "w" if file
+
+      case
+        when file.is_a?(String) then @@file = File.open file, "w"
+        when file.is_a?(File) then @@file = file
+        when file.is_a?(StringIO) then @@file = file
+        else
+          raise "Not a vailid file"
+      end
     end
 
-    def self.show_timestamps
-      @@timestamps = true
+    # Specify the format of each line in the logs.
+    #
+    # The template can reference the following keys:
+    #   * timestamp
+    #   * name
+    #   * type
+    #   * message
+    #
+    # @example
+    #   Logger::set_format "%{timestamp} %{name} %{type} %{message}"
+    #
+    # @param [String] format  The format template.
+    def self.set_format(format)
+      @@format = format
     end
 
+    # Log a string.
+    #
+    # The message will be written to both stdout and the log file if configured.
+    #
+    # @param [Symbol] msg_type  Type of the message.
+    # @param [String] msg  The contents of the log message.
+    # @param [Symbol] verbosity  Desired verbosity level of this message.
     def self.log(msg_type, msg, verbosity=:informative)
+      # arguments sanity checks
+      unless @@message_types.include? msg_type
+        raise ArgumentError, "Unknown message type :#{msg_type}"
+      end
+
+      unless @@verbosity_levels.include?(verbosity) and verbosity != :quiet
+        raise ArgumentError, "You can't use the :#{verbosity.to_s} verbosity level"
+      end
+
       if @@verbosity_levels[verbosity] <= @@verbosity_levels[@@verbosity]
-        ts = if @@timestamps
-          Time.now.strftime("%Y-%m-%d %H:%M").style("timestamp") + " "
-        else
-          ""
-        end
+          ts = Time.now.strftime("%Y-%m-%d %H:%M:%S").style("timestamp")
 
         name = if @@name != nil && @@name.length > 0
-          @@name.style("name") + " "
+          @@name.style("name")
         else
           ""
         end
@@ -83,9 +135,13 @@ module Scriptster
         msg.chomp!
         msg = Tco::parse msg, Tco::get_style("#{msg_type.to_s}-message")
 
-        line = ts << name.style("name") <<
-               @@message_types[msg_type].style(msg_type.to_s) <<
-               " " << msg
+        line = @@format % {
+          timestamp: ts,
+          name: name,
+          type: @@message_types[msg_type].style(msg_type.to_s),
+          message: msg
+        }
+
         puts line
         STDOUT.flush
 
@@ -96,6 +152,9 @@ module Scriptster
       end
     end
 
+    # Instance method wrapper for when the module is included.
+    #
+    # @see Logger.log
     def log(msg_type, msg, verbosity=:informative)
       Logger::log msg_type, msg, verbosity
     end

data/lib/scriptster/shellcmd.rb

@@ -26,11 +26,31 @@ require "tco"
 require "scriptster/logger"
 
 module Scriptster
+  # Represent an executed shell command.
+  #
+  # The command will be executed in the constructor. It runs in the
+  # foreground, so your application will block until it's finished
+  # executing. The logs, however, will be printed real-time as the
+  # command prints its output.
+  #
+  # @attr [Process::status] status  The exit status of the command.
+  # @attr [String] out  The content of the STDOUT of the command.
+  # @attr [String] err  The content of the STDERR of the command.
   class ShellCmd
     attr_reader :status, :out, :err
 
     include Logger
 
+    # Initialise the object and run the command
+    #
+    # @param [String] cmd  The command line to be run.
+    # @param [Hash] opts  Various options of the command.
+    # @option opts [Boolean] :show_out  Care about STDOUT flag.
+    # @option opts [Boolean] :show_err  Care about STDERR flag.
+    # @option opts [Boolean] :raise  Raise on error flag.
+    # @option opts [String] :tag  Logger tag (defaults to the first
+    #                             word of the command line).
+    # @option opts [Integer, Array<Integer>] :expect  Expected return values.
     def initialize(cmd, opts={})
       @out = ""
       @err = ""
@@ -52,6 +72,9 @@ module Scriptster
     end
 
     private
+    # Execute the command and collect all the data from it.
+    #
+    # The function will blog until the command has finished.
     def run
       Open3.popen3(@cmd) do |stdin, stdout, stderr, wait_thr|
         stdout_buffer=""

data/lib/scriptster/version.rb

@@ -1,3 +1,4 @@
 module Scriptster
-  VERSION = "0.1.0"
+  # The version of this library
+  VERSION = "0.2.0"
 end

data/scriptster.gemspec

@@ -22,4 +22,5 @@ Gem::Specification.new do |spec|
 
   spec.add_development_dependency "bundler", "~> 1.6"
   spec.add_development_dependency "rake", "~> 10.1"
+  spec.add_development_dependency "rspec", "~> 3.1"
 end

data/spec/scriptster_spec.rb

@@ -0,0 +1,221 @@
+# scriptster - A small library to make your scipts a bit nicer
+# Copyright (c) 2014 Radek Pazdera
+
+# MIT License
+
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+
+require 'stringio'
+require 'scriptster'
+require 'utils'
+require 'tmpdir'
+
+describe Scriptster do
+  describe "#log" do
+    before :all do
+      @out = StringIO.new
+      Scriptster::configure do |conf|
+        conf.file = @out
+      end
+
+      @stdout = StringIO.new
+    end
+
+    before :each do
+      @out.truncate 0
+
+      @stdout.truncate 0
+      @orig_stdout = $stdout
+      $stdout = @stdout
+    end
+
+    after :each do
+      $stdout = @orig_stdout
+    end
+
+    it "logs to info" do
+      Scriptster::log :info, "Hello there"
+      expect(@out.string.strip).to match /info Hello there/
+    end
+
+    it "logs to warning" do
+      Scriptster::log :warn, "Hello there"
+      expect(@out.string.strip).to match /WARN Hello there/
+    end
+
+    it "logs to error" do
+      Scriptster::log :err, "Hello there"
+      expect(@out.string.strip).to match /ERR\! Hello there/
+    end
+
+    it "logs to debug" do
+      Scriptster::log :debug, "Hello there"
+      expect(@out.string.strip).to match /dbg\? Hello there/
+    end
+
+    it "raises on bad message type" do
+      expect {
+        Scriptster::log(:abcd, "Hello there")
+      }.to raise_exception ArgumentError
+    end
+
+    it "raises on bad verbosity type" do
+      expect {
+        Scriptster::log(:info, "Hello there", :quiet)
+      }.to raise_exception ArgumentError
+    end
+
+    it "is quiet" do
+      Scriptster::configure do |conf|
+        conf.verbosity = :quiet
+      end
+
+      Scriptster::log :info, "Hello there"
+      expect(@out.string.strip).not_to match /info Hello there/
+    end
+
+    it "default verbosity is less than :essential" do
+      Scriptster::configure do |conf|
+        conf.verbosity = :essential
+      end
+
+      Scriptster::log :info, "Hello there"
+      expect(@out.string.strip).not_to match /info Hello there/
+    end
+
+    it "default verbosity is :informative" do
+      Scriptster::configure do |conf|
+        conf.verbosity = :informative
+      end
+
+      Scriptster::log :info, "Hello there"
+      expect(@out.string.strip).to match /info Hello there/
+    end
+  end
+
+  describe "#cmd" do
+    before :all do
+      # Set up a temporary test directory
+      @dir = Dir.mktmpdir
+
+      File.open("#{@dir}/file.txt", "w") do |f|
+        f.puts "Multi-line"
+        f.puts "File contents"
+      end
+
+      # Set up the dummy stdout/stderr
+      @out = StringIO.new
+      @err = StringIO.new
+    end
+
+    after :all do
+      FileUtils.remove_entry_secure @dir
+    end
+
+    before :each do
+      @out.truncate 0
+      @orig_stdout = $stdout
+      $stdout = @out
+
+      @err.truncate 0
+      @orig_stderr = $stderr
+      $stderr = @err
+    end
+
+    after :each do
+      $stdout = @orig_stdout
+
+      $stderr = @orig_stderr
+    end
+
+    it "shows output" do
+      Scriptster::cmd "cat #{@dir}/file.txt", :show_out => true
+
+      line1, line2 = remove_colours(@out.string.strip).split "\n"
+      expect(line1).to match "Multi-line"
+      expect(line2).to match "File contents"
+    end
+
+    it "hides output" do
+      Scriptster::cmd "cat #{@dir}/file.txt", :show_out => false
+      expect(@out.string).to eq ""
+    end
+
+    it "captures output" do
+      cat = Scriptster::cmd "cat #{@dir}/file.txt", :show_out => false
+      expect(cat.out).to eq "Multi-line\nFile contents\n"
+    end
+
+    it "shows error" do
+      Scriptster::cmd "cat #{@dir}/nonexistent.txt",
+        :show_err => true,
+        :raise => false
+
+      expect(@out.string.strip).to match "No such file or directory"
+    end
+
+    it "hides error" do
+      Scriptster::cmd "cat #{@dir}/nonexistent.txt",
+        :show_err => false,
+        :raise => false
+
+      expect(@out.string.strip).to match ""
+    end
+
+    it "captures error" do
+      cat = Scriptster::cmd "cat #{@dir}/nonexistent.txt",
+        :show_err => true,
+        :raise => false
+
+      expect(cat.err.strip).to match "No such file or directory"
+    end
+
+    it "collects status (no error)" do
+      cat = Scriptster::cmd "cat #{@dir}/file.txt",
+        :show_err => true,
+        :raise => false
+
+      expect(cat.status.exitstatus).to eq 0
+    end
+
+    it "collects status (fail)" do
+      cat = Scriptster::cmd "cat #{@dir}/nonexistent.txt",
+        :show_err => true,
+        :raise => false
+
+      expect(cat.status.exitstatus).to eq 1
+    end
+
+    it "does raise" do
+      expect {
+        Scriptster::cmd "cat #{@dir}/nonexistent.txt"
+      }.to raise_exception RuntimeError
+    end
+
+    it "expects correct return value" do
+        cat = Scriptster::cmd "cat #{@dir}/nonexistent.txt", :expect => 1
+        expect(cat.status.exitstatus).to eq 1
+    end
+
+    it "expects incorrect return value" do
+      expect {
+        Scriptster::cmd "cat #{@dir}/nonexistent.txt", :expect => 10
+      }.to raise_exception RuntimeError
+    end
+  end
+end

data/spec/utils.rb

@@ -0,0 +1,26 @@
+# scriptster - A small library to make your scipts a bit nicer
+# Copyright (c) 2014 Radek Pazdera
+
+# MIT License
+
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+
+
+def remove_colours(string)
+  string.gsub(/\033\[[0-9]+(;[0-9]+){0,2}m/, "")
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: scriptster
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Radek Pazdera
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-10-26 00:00:00.000000000 Z
+date: 2014-10-31 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: tco
@@ -52,6 +52,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '10.1'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
 description: A simple library for making your scipts a bit nicer.
 email:
 - radek@pazdera.co.uk
@@ -60,16 +74,21 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".gitignore"
+- ".travis.yml"
+- CHANGELOG.md
 - Gemfile
 - LICENSE.txt
 - README.md
 - Rakefile
+- gemrc
 - lib/scriptster.rb
 - lib/scriptster/configuration.rb
 - lib/scriptster/logger.rb
 - lib/scriptster/shellcmd.rb
 - lib/scriptster/version.rb
 - scriptster.gemspec
+- spec/scriptster_spec.rb
+- spec/utils.rb
 homepage: https://github.com/pazdera/scriptster
 licenses:
 - MIT
@@ -94,4 +113,7 @@ rubygems_version: 2.2.2
 signing_key: 
 specification_version: 4
 summary: Making your Ruby scipts hip.
-test_files: []
+test_files:
+- spec/scriptster_spec.rb
+- spec/utils.rb
+has_rdoc: