mergit 0.1.0 → 1.0.0

data/.yardopts

@@ -0,0 +1,5 @@
+lib/**/*.rb
+**/.md
+--markup markdown
+--protected
+--private

data/README.md

@@ -6,20 +6,28 @@
 
 Mergit is a way to merge a bunch of `require`d files into one file.
 
-This is useful to distribute single-file ruby executables, such as administration scripts, simple tools, etc.  Yet allows you to break
-files out for easy design, programming and testing.
+This allows you develop, design, and test your ruby script using normal ruby best practices (rspec, etc.) and then
+distribute them as a single-file ruby script.
+
+Some use cases include:
+
+* Administration scripts
+* Simple tools
+* Programs that need to work on any ruby without installing gems
 
 ## Limitations
 
 Mergit uses simple text processing, therefore it can be tripped up.  Some known problems include:
 
-* `require` statements nested in code instead of at outermost scope of a file.
+* `require` statements nested in code instead of at outermost scope of a file will expand in-place. This probably isn't what you want.
+* The order `require`d files are pulled in may be different than ruby.
+* The replacement feature is very brute force.  Be careful using it.
 
 ## Installation
 
 Add this line to your application's Gemfile:
 
-    gem 'mergit'
+    gem 'mergit', '~> 1.0'
 
 And then execute:
 
@@ -29,6 +37,8 @@ Or install it yourself as:
 
     $ gem install mergit
 
+Note: Mergit uses [Semantic Versioning](http://semver.org/).
+
 ## Usage
 
 ### Command Line Tool
@@ -40,26 +50,56 @@ you want `require`d from.
 
 You can specify the `--lib` flag multiple times.
 
+There is also a `--replace` flag that lets you specify a string or regular expression (a string surrounded by `/`) that should be replaced.
+
+Example:
+
+    bin/mergit --replace mouse=cat filename
+
+This will replace all occurances of "mouse" with "cat".
+
+You can specify the `--replace` flag multiple times.
+
 Use the `--output` flag to send the resulting output to someplace other than stdout.
 
+#### MERGIT directives
+
+You can also cause any line to be skipped by adding a Mergit directive in a comment at the end of the line.
+
+Example:
+
+    raise "This won't be in the merged output." # MERGIT: skip
+
 ### Library API
 
 Simple usage:
 
-```
-search_path = [ '/path/to/lib', '/path/to/other/lib' ]
-mergit = Mergit.new(:search_path => search_path)
+    search_path = [ '/path/to/lib', '/path/to/other/lib' ]
+    mergit = Mergit.new(:search_path => search_path)
 
-string_of_merged_file = mergit.process_file('/path/to/file')
-# or
-string_of_merged_string = mergit.process(some_string)
+    string_of_merged_file = mergit.process_file('/path/to/file')
+    # or
+    string_of_merged_string = mergit.process(some_string)
 
-```
+For more detailed information, see the [documentation](http://rubydoc.info/gems/mergit/frames).
 
 ## Contributing
 
-1. Fork it
+### Level 1 -- Apprentice
+
+File an [issue](https://github.com/docwhat/mergit/issues).
+
+Make sure it includes the steps needed to reproduce it as well as what you expected to happen.
+
+### Level 2 -- Journeyman
+
+1. [Fork it](https://help.github.com/articles/fork-a-repo)
 2. Create your feature branch (`git checkout -b my-new-feature`)
 3. Commit your changes (`git commit -am 'Add some feature'`)
 4. Push to the branch (`git push origin my-new-feature`)
 5. Create new Pull Request
+
+### Level 3 -- Master
+
+Repeat Level 2 until I give you write access on github. :-)
+

data/Rakefile

@@ -1,6 +1,11 @@
 require "bundler/gem_tasks"
 require "rspec/core/rake_task"
+require 'yard'
 
 RSpec::Core::RakeTask.new(:spec)
 
 task :default => :spec
+
+YARD::Rake::YardocTask.new do |t|
+  t.files = ['lib/**/*.rb', '**/*.md']
+end

data/bin/mergit

@@ -1,7 +1,7 @@
 #!/usr/bin/env ruby
 # -*- coding: utf-8 -*-
 
-$: << File.expand_path('../../lib/', __FILE__) if File.directory?(File.expand_path('../../lib/', __FILE__))
+$: << File.expand_path('../../lib/', __FILE__) if File.directory?(File.expand_path('../../lib/', __FILE__)) # MERGIT: skip
 require 'mergit'
 require 'optparse'
 
@@ -42,6 +42,13 @@ class MergitProgram
         end
       end
 
+      opts.on('-r', '--replace MATCH=REPLACEMENT', String,
+             "Replaces all occurrences of MATCH with REPLACEMENT. If MATCH is between / characters, then it'll be used as a case-sensitive regexp. Can be specified multiple times.") do |m|
+        match, replace = m.split(/=/)
+        match = Regexp.new(match.slice(1..-2)) if match.start_with?('/') && match.end_with?('/')
+        mergit.replacements[match] = replace
+      end
+
       opts.on('-d', '--debug', "Turn on debugging.") do
         @debug = true
       end

data/lib/mergit/errors.rb

@@ -1,5 +1,8 @@
 class Mergit
+  # The superclass for all errors raised by {Mergit}
   class MergitError < StandardError; end
+
+  # This is raised whenever a required library isn't found.
   class RequirementNotFound < MergitError; end
 end
 

data/lib/mergit/processor.rb

@@ -1,12 +1,24 @@
+# coding: utf-8
 require 'mergit/errors'
 require 'pathname'
 require 'stringio'
 
 class Mergit
+  # The class that actually does the merge processing.
   class Processor
+
+    # @return {Array<Pathname>} A frozen array of {http://rubydoc.info/stdlib/pathname/frames Pathname}s
+    attr_reader :search_path
+
+    # @return {Hash} A frozen hash with the rules for replacements.
+    attr_reader :replacements
+
+    # @param [Array<Pathname, String>] search_path The list of directories to search.
+    # @param [Hash] replacements A list of keywords to replace.
+    # @param [Hash] options Either `:filename` or `:string` should be set.
     def initialize search_path, replacements, options
-      @search_path = search_path.map{|p| Pathname.new p}
-      @replacements = replacements
+      @search_path = search_path.map{|p| Pathname.new p}.freeze
+      @replacements = replacements.freeze
       @visited_files = []
 
       @output = StringIO.new
@@ -21,6 +33,10 @@ class Mergit
       end
     end
 
+    # Finds a library using the {#search_path}
+    #
+    # @param [String] lib_name The name of the library to look for.
+    # @return [Nil, Pathname] Returns `nil` if it isn't found or a {http://rubydoc.info/stdlib/pathname/frames Pathname} if it is found.
     def find_requirement lib_name
       @search_path.each do |directory|
         possible_path = directory + "#{lib_name}.rb"
@@ -29,15 +45,34 @@ class Mergit
       nil
     end
 
+
+    # Finds a library using the {#search_path}
+    #
+    # This is identical to {#find_requirement} except it raises {Mergit::RequirementNotFound} if
+    # it fails to find the library.
+    #
+    # @raise [Mergit::RequirementNotFound] if it can't find the library.
+    # @param (see #find_requirement)
+    # @return [Pathname] Returns the {http://rubydoc.info/stdlib/pathname/frames Pathname} of the library.
+    # @see #find_requirement
     def find_requirement! lib_name
       find_requirement(lib_name).tap do |retval|
         raise Mergit::RequirementNotFound.new("Unabled to find require'd file: #{lib_name}") if retval.nil?
       end
     end
 
+    ## Scans a single line of the file.
+    #
+    # It looks for things that need to be changed, and {#emit}s the resulting
+    # (changed) line.
+    #
+    # @param [String] line The line to parse
+    # @return [Nil]
     def scan_line line
       line.chomp!
-      if line =~ /^\s*require\s+'([^']+)'\s*$/ or line =~ /^\s*require\s+"([^"]+)"\s*$/
+      if line =~ /#\s*MERGIT:\s*skip\s*$/
+        nil # do nothing
+      elsif line =~ /^\s*require\s+'([^']+)'\s*$/ or line =~ /^\s*require\s+"([^"]+)"\s*$/
         requirement = find_requirement($1)
         if requirement.nil?
           emit line
@@ -45,10 +80,19 @@ class Mergit
           scan_file requirement
         end
       else
+        replacements.each_key do |string_to_replace|
+          line.gsub!(string_to_replace, replacements[string_to_replace])
+        end
         emit line
       end
     end
 
+    ## Scans an entire file
+    #
+    # It passes each line of the file to {#scan_line} for parsing.
+    #
+    # @param [Pathname] filename The file to scan.
+    # @return [Nil]
     def scan_file filename
       relative_filename = if filename.relative?
                             filename
@@ -65,22 +109,39 @@ class Mergit
       emit "### MERGIT: End of '#{relative_filename}'"
     end
 
+    ## Scans a string
+    #
+    # It splits a string up into individual line via {#string_split} and
+    # passes them to {#scan_line}.
+    #
+    # @param [String] string The string to parse.
+    # @return [Nil]
     def scan string
       string_split(string).each { |line| scan_line line }
     end
 
+    ## Split a string into lines.
+    #
+    # @param [String] string The string to split into lines.
+    # @return [Array<String>] The split up string.
     def string_split string
       string.split(/\n|\r\n/)
     end
 
+    ## The resulting processed output.
+    #
+    # @return [String]
     def output
       @output.close unless @output.closed?
       @final_output ||= @output.string
     end
 
+    ## Sends a string to the {#output}
+    #
+    # @param [String] string The string to send to {#output}.
+    # @return [Nil]
     def emit string
       @output.puts string
     end
-
   end
 end

data/lib/mergit/version.rb

@@ -1,3 +1,5 @@
+# coding: utf-8
 class Mergit
-  VERSION = "0.1.0"
+  # The version of the Mergit Library.
+  VERSION = "1.0.0"
 end

data/lib/mergit.rb

@@ -1,8 +1,13 @@
+# coding: utf-8
 require 'mergit/version'
 require 'mergit/processor'
 require 'mergit/errors'
 
+# A class for merging in `require`ments.
 class Mergit
+  # List of attributes accepted by {Mergit}, and the default values.
+  #
+  # @return [Hash]
   ATTRIBUTES = {
     :search_path => [Dir.pwd],
     :replacements => {},
@@ -12,6 +17,9 @@ class Mergit
     attr_accessor attr
   end
 
+  # Create a new mergit instance.
+  #
+  # @param [Hash] options See {ATTRIBUTES} for the list of options you can pass in.
   def initialize options=nil
     final_options = options ? ATTRIBUTES.merge(options) : ATTRIBUTES
 
@@ -20,6 +28,10 @@ class Mergit
     end
   end
 
+  # Merge a file
+  #
+  # @param [Pathname, String] filename The name of the file to merge.
+  # @return [String] The merged file.
   def process_file filename
     if File.file? filename
       create_file_processor(filename).output
@@ -28,6 +40,10 @@ class Mergit
     end
   end
 
+  # Merge a string
+  #
+  # @param [String] string The text that should be merged.
+  # @return [String] The merged output.
   def process string
     create_string_processor(string).output
   end
@@ -38,10 +54,20 @@ class Mergit
 
   private
 
+  # Helper to create a string processor
+  #
+  # @param [String] string The string to merge.
+  # @return [Processor]
+  # @!visibility private
   def create_string_processor string
     Processor.new(search_path, replacements, :string => string)
   end
 
+  # Helper to create a file processor
+  #
+  # @param [Pathname, String] filename The file to process
+  # @return [Processor]
+  # @!visibility private
   def create_file_processor filename
     Processor.new(search_path, replacements, :filename => filename)
   end

data/mergit.gemspec

@@ -8,9 +8,9 @@ Gem::Specification.new do |spec|
   spec.version       = Mergit::VERSION
   spec.authors       = ["Christian Höltje"]
   spec.email         = ["docwhat@gerf.org"]
-  spec.description   = %q{Merge 'require'd files into one file.}
-  spec.summary       = %q{Ever wanted to merge all your 'require'd files into one file for easy distribution? Mergit is your friend!}
-  spec.homepage      = ""
+  spec.summary       = %q{Merge 'require'd files into one file.}
+  spec.description   = %q{Ever wanted to merge all your 'require'd files into one file for easy distribution? Mergit is your friend!}
+  spec.homepage      = "https://github.com/docwhat/mergit"
   spec.license       = "MIT"
 
   spec.files         = `git ls-files`.split($/)
@@ -20,6 +20,8 @@ Gem::Specification.new do |spec|
 
   spec.add_development_dependency "bundler",                 "~> 1.3"
   spec.add_development_dependency "rake",                    "~> 10.0"
+  spec.add_development_dependency "yard",                    "~> 0.8.5"
+  spec.add_development_dependency "redcarpet",               "~> 2.2"
   spec.add_development_dependency "rspec",                   "~> 2.13"
   spec.add_development_dependency "coveralls",               "~> 0.6"
   spec.add_development_dependency "guard-rspec",             "~> 2.5"

data/spec/mergit/processor_spec.rb

@@ -122,6 +122,44 @@ describe Mergit::Processor do
         subject.should_receive(:scan_file).with(Pathname.new('../../../lib/mergit/version.rb').expand_path(__FILE__)).once
       end
     end
+
+    context "given a line with MERGIT: skip" do
+      let(:ruby_string) { "this should never be seen # MERGIT: skip " }
+      after { subject.scan_line ruby_string }
+
+      it "should not call emit" do
+        subject.should_not_receive(:emit)
+      end
+    end
+
+    context "with a replacements" do
+      let(:replacements) do
+        {
+          'VERSION' => '1.2.3',
+          /PROG\s*NAME/ => 'Awesome Program',
+        }
+      end
+
+      context "matching on a string" do
+        let(:ruby_string) { "puts 'The version is VERSION'" }
+        let(:expected_string) { ruby_string.sub('VERSION', '1.2.3') }
+        after { subject.scan_line ruby_string }
+
+        it "should replace VERSION" do
+          subject.should_receive(:emit).with(expected_string)
+        end
+      end
+
+      context "matching on a regexp" do
+        let(:ruby_string) { "puts 'The program is PROGNAME.'" }
+        let(:expected_string) { ruby_string.sub('PROGNAME', 'Awesome Program') }
+        after { subject.scan_line ruby_string }
+
+        it "should replace PROGNAME" do
+          subject.should_receive(:emit).with(expected_string)
+        end
+      end
+    end
   end
 
   describe "string_split" do

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mergit
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 1.0.0
   prerelease: 
 platform: ruby
 authors:
@@ -43,6 +43,38 @@ dependencies:
     - - ~>
       - !ruby/object:Gem::Version
         version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.8.5
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.8.5
+- !ruby/object:Gem::Dependency
+  name: redcarpet
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.2'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -187,7 +219,8 @@ dependencies:
     - - ~>
       - !ruby/object:Gem::Version
         version: '1.5'
-description: Merge 'require'd files into one file.
+description: Ever wanted to merge all your 'require'd files into one file for easy
+  distribution? Mergit is your friend!
 email:
 - docwhat@gerf.org
 executables:
@@ -198,6 +231,7 @@ files:
 - .gitignore
 - .rspec
 - .travis.yml
+- .yardopts
 - Gemfile
 - Guardfile
 - LICENSE.txt
@@ -215,7 +249,7 @@ files:
 - spec/mergit/processor_spec.rb
 - spec/mergit_spec.rb
 - spec/spec_helper.rb
-homepage: ''
+homepage: https://github.com/docwhat/mergit
 licenses:
 - MIT
 post_install_message: 
@@ -230,7 +264,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -2751772494269357839
+      hash: 3687644075462403820
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -239,14 +273,13 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -2751772494269357839
+      hash: 3687644075462403820
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.23
 signing_key: 
 specification_version: 3
-summary: Ever wanted to merge all your 'require'd files into one file for easy distribution?
-  Mergit is your friend!
+summary: Merge 'require'd files into one file.
 test_files:
 - spec/examples/loop/a.rb
 - spec/examples/loop/b.rb
@@ -254,3 +287,4 @@ test_files:
 - spec/mergit/processor_spec.rb
 - spec/mergit_spec.rb
 - spec/spec_helper.rb
+has_rdoc: