traject 0.13.0 → 0.13.1

data/.yardopts

@@ -0,0 +1,2 @@
+-
+doc/*.md

data/README.md

@@ -15,15 +15,19 @@ them somewhere.
 
 Existing tools for indexing Marc to Solr exist, and have served us well for many years, and have many useful things about them -- which I've tried to preserve in traject.  But I was having more and more difficulty working with the existing tools, including difficulty providing the custom logic I needed in a maintainable way. I realized that for me, to create a tool with the flexibility, maintainability, and performance I wanted, I would need to do it in jruby (ruby on the JVM).
 
-Some goals:
-
-* Aim to be accessible even to non-rubyists
-* Concise and maintainable local configuration -- including an only gradual increase in difficulty to write your own simple logic.
-* Support reusable and shareable mapping logic routines.
-* Built of modular and composable elements: If you want to change part of what traject does, you should be able to do so without having to reimplement other things you don't want to change.
-* A maintainable internal architecture, well-factored with seperated concerns and DRY logic. Aim to be comprehensible to newcomer developers, and well-covered by tests.
-* High performance, using multi-threaded concurrency where appropriate to maximize throughput. Actual throughput can depend on complexity of your mapping rules and capacity of your server(s), but I am getting throughput 2-5x greater than previous solutions.
-* Cooperate well in unix batch/pipeline, with control over output/logging of errors, proper exit codes, use of stdin/stdout, etc.
+* *Easy to use*, getting started with standard use cases should be easy, even for non-rubyists.
+* *Support customization and flexiblity*, common customization use cases, including simple local
+  logic, should be very easy. More sophisticated and even complex customization use cases should still be possible,
+  changing just the parts of traject you want to change.
+* *Maintainable local logic*, including supporting sharing of reusable logic via ruby gems.
+* *Maintainable understandable internal logic*; well-covered by tests, well-factored seperation of concerns,
+easy for newcomer developers who know ruby to understand the codebase.
+* *High performance*, using multi-threaded concurrency where appropriate to maximize throughput.
+While it depends on your configuration and the size of your server(s), traject is likely higher
+performance than other similar solutions.
+* *Well-behaved shell script*, for painless integration in batch processes and cronjobs, with
+exit codes, sufficiently flexible control of logging, proper use of stderr, etc.
+
 
 
 ## Installation

data/doc/extending.md

@@ -5,7 +5,7 @@ organize it in files other than traject config files, but then
 use it in traject config files.
 
 You might want to have code local to your traject project; or you
-might want to use ruby gems with shared code in your traject project.
+might want to use ruby gems to share code between projects and developers. 
 A given project may use both of these techniques.
 
 Here are some suggestions for how to do this, along with mention
@@ -16,7 +16,7 @@ of a couple traject features meant to make it easier.
 * Traject `-I` argument command line can be used to list directories to
   add to the load path, similar to the `ruby -I` argument. You
   can then 'require' local project files from the load path.
-  * translation map files found on the load path or in a
+  * translation map files found in a
     "./translation_maps" subdir on the load path will be found
     for Traject translation maps.
 * Traject `-G` command line can be used to tell traject to use
@@ -26,7 +26,7 @@ of a couple traject features meant to make it easier.
 ## Custom code local to your project
 
 You might want local translation maps, or local ruby
-code. Here's a standard way you might lay out
+code. Here's a standard recommended way you might lay out
 this extra code in the file system, using a 'lib'
 directory kept next to your traject config files:
 
@@ -97,8 +97,8 @@ That's pretty much it!
 
 What about that translation map? The `$LOAD_PATH` modification
 took care of that too, the Traject::TranslationMap will look
-up translation map definition files on the load path, or
-in a `./translation_maps` subdir on the load path.
+up translation map definition files 
+in a `./translation_maps` subdir on the load path, as in `./lib/translation_maps` in this case. 
 
 
 ## Using gems in your traject project
@@ -128,11 +128,10 @@ require 'some_gem'
 SomeGem.whatever!
 ~~~
 
-Any gem can provide traject translation map definitions
-in it's `lib` directory, or in a `lib/translation_maps`
-sub-directory, and traject will be able to find those
+A gem can provide traject translation map definitions
+in a `lib/translation_maps` sub-directory, and traject will be able to find those
 translation maps when the gem is loaded. (Because gems'
-`./lib` directories are added to the ruby load path.)
+`./lib` directories are by default added to the ruby load path.)
 
 ### Or, with bundler:
 
@@ -161,9 +160,14 @@ possibly with version restrictions, in the [Gemfile](http://bundler.io/v1.3/gemf
 Run `bundle install` from the directory with the Gemfile, on any system
 at any time, to make sure specified gems are installed.
 
-**Run traject** with the `-G` flag to tell it to use the Gemfile:
+**Run traject** with the `-G` flag to tell it to use the Gemfile, for instance if
+your working directory is the one that includes your Gemfile:
 
-   traject -G -c some_traject_config.rb ...
+    traject -G -c some_traject_config.rb ...
+    
+Or explicitly specify a Gemfile somewhere else:
+
+    traject -G /some/path/Gemfile -c some_config.rb ...
 
 Traject will use bundler to setup with the Gemfile, making sure
 the specified versions of all gems are used (and also making sure
@@ -179,4 +183,4 @@ that bundler creates into your source control repo. The
 gem dependencies are currently being used, so you can get the exact
 same dependency environment on different servers.
 
-See the [bundler documentation](http://bundler.io/#getting-started), or google, for more information. 
+See the [bundler documentation](http://bundler.io/#getting-started), or google, for more information. 

data/lib/traject/command_line.rb

@@ -33,14 +33,8 @@ module Traject
     # Returns true on success or false on failure; may also raise exceptions;
     # may also exit program directly itself (yeah, could use some normalization)
     def execute
-      if options[:version]
-        self.console.puts "traject version #{Traject::VERSION}"
-        return
-      end
-      if options[:help]
-        self.console.puts slop.help
-        return
-      end
+      # Do bundler setup FIRST to try and initialize all gems from gemfile
+      # if requested.
 
       # have to use Slop object to tell diff between
       # no arg supplied and no option -g given at all
@@ -48,11 +42,21 @@ module Traject
         require_bundler_setup(options[:Gemfile])
       end
 
+
       # We require them here instead of top of file,
       # so we have done bundler require before we require these.
       require 'traject'
       require 'traject/indexer'
 
+      if options[:version]
+        self.console.puts "traject version #{Traject::VERSION}"
+        return
+      end
+      if options[:help]
+        self.console.puts slop.help
+        return
+      end
+
 
       (options[:load_path] || []).each do |path|
         $LOAD_PATH << path unless $LOAD_PATH.include? path
@@ -282,7 +286,7 @@ module Traject
         on :j, "output as pretty printed json, shortcut for -s writer_class_name=JsonWriter -s json_writer.pretty_print=true"
         on :t, :marc_type, "xml, json or binary. shortcut for -s marc_source.type=", :argument => true
         on :I, "load_path", "append paths to ruby $LOAD_PATH", :argument => true, :as => Array, :delimiter => ":"
-        on :G, "Gemfile", "run with bundler and optionally specified Gemfile", :argument => :optional, :default => ""
+        on :G, "Gemfile", "run with bundler and optionally specified Gemfile", :argument => :optional, :default => nil
 
         on :x, "command", "alternate traject command: process (default); marcout", :argument => true, :default => "process"
 

data/lib/traject/translation_map.rb

@@ -109,6 +109,10 @@ module Traject
           end
         end
 
+        # Cached hash can't be mutated without weird consequences, let's
+        # freeze it! 
+        found.freeze if found
+
         return found
       end
 
@@ -141,7 +145,7 @@ module Traject
       if options[:default]
         @default = options[:default]
       elsif @hash.has_key? "__default__"
-        @default = @hash.delete("__default__")
+        @default = @hash["__default__"]
       end
     end
 
@@ -158,6 +162,12 @@ module Traject
     end
     alias_method :map, :[]
 
+    # Returns a dup of internal hash, dup so you can modify it
+    # if you like. 
+    def to_hash
+      @hash.dup
+    end
+
     # Run every element of an array through this translation map,
     # return the resulting array. If translation map returns nil,
     # original element will be missing from output. 

data/lib/traject/version.rb

@@ -1,3 +1,3 @@
 module Traject
-  VERSION = "0.13.0"
+  VERSION = "0.13.1"
 end

data/test/translation_map_test.rb

@@ -27,6 +27,19 @@ describe "TranslationMap" do
       assert_equal "value1", found["key1"]
     end
 
+    it "freezes the hash" do
+      found = @cache.lookup("yaml_map")
+
+      assert found.frozen?
+    end
+
+    it "respects in-file default, even on second load" do
+      map = Traject::TranslationMap.new("default_literal")
+      map = Traject::TranslationMap.new("default_literal")
+
+      assert_equal "DEFAULT LITERAL", map["not in the map"] 
+    end
+
     it "finds .rb over .yaml" do
       found = @cache.lookup("both_map")
 
@@ -103,4 +116,17 @@ describe "TranslationMap" do
 
     assert_equal ["hola", "first", "second", "last thing", "buenas noches", "hola", "everything else"], arr
   end
+
+  it "#to_hash" do
+    map = Traject::TranslationMap.new("yaml_map")
+
+    hash = map.to_hash
+
+    assert_kind_of Hash, hash
+
+    assert ! hash.frozen?, "#to_hash result is not frozen"
+
+    refute_same hash, map.to_hash, "each #to_hash result is a copy"
+  end
+
 end

data/traject.gemspec

@@ -17,6 +17,8 @@ Gem::Specification.new do |spec|
   spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
   spec.require_paths = ["lib"]
 
+  spec.extra_rdoc_files = spec.files.grep(%r{^doc/})
+
 
   spec.add_dependency "marc", ">= 0.7.1"
   spec.add_dependency "marc-marc4j", ">=0.1.1"

metadata

@@ -2,14 +2,14 @@
 name: traject
 version: !ruby/object:Gem::Version
   prerelease:
-  version: 0.13.0
+  version: 0.13.1
 platform: ruby
 authors:
 - Jonathan Rochkind
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2013-09-12 00:00:00.000000000 Z
+date: 2013-09-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: marc
@@ -157,10 +157,16 @@ email:
 executables:
 - traject
 extensions: []
-extra_rdoc_files: []
+extra_rdoc_files:
+- doc/batch_execution.md
+- doc/extending.md
+- doc/macros.md
+- doc/other_commands.md
+- doc/settings.md
 files:
 - .gitignore
 - .travis.yml
+- .yardopts
 - Gemfile
 - LICENSE.txt
 - README.md