RubyGems - olag - Versions diffs - 0.1.10 - Mend

olag 0.1.10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (29) hide show

data/ChangeLog +24 -0
data/LICENSE +19 -0
data/README.rdoc +17 -0
data/Rakefile +24 -0
data/codnar.html +4379 -0
data/doc/root.html +26 -0
data/doc/system.markdown +283 -0
data/lib/olag/application.rb +167 -0
data/lib/olag/change_log.rb +59 -0
data/lib/olag/data_files.rb +20 -0
data/lib/olag/errors.rb +44 -0
data/lib/olag/gem_specification.rb +77 -0
data/lib/olag/globals.rb +43 -0
data/lib/olag/hash_struct.rb +12 -0
data/lib/olag/rake.rb +263 -0
data/lib/olag/string_unindent.rb +19 -0
data/lib/olag/test.rb +8 -0
data/lib/olag/test/with_errors.rb +26 -0
data/lib/olag/test/with_fakefs.rb +36 -0
data/lib/olag/test/with_rake.rb +34 -0
data/lib/olag/test/with_tempfile.rb +49 -0
data/lib/olag/update_version.rb +53 -0
data/lib/olag/version.rb +8 -0
data/test/access_data_files.rb +15 -0
data/test/collect_errors.rb +33 -0
data/test/missing_keys.rb +17 -0
data/test/run_application.rb +44 -0
data/test/unindent_text.rb +26 -0
metadata +243 -0

data/doc/root.html ADDED Viewed

@@ -0,0 +1,26 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+<meta http-equiv="Content-Type" content="text/html;charset=utf-8"/>
+<title>Olag - Oren's Library/Application Gem framework.</title>
+<style type="text/css">
+<embed src="codnar/data/yui/reset.css" type="x-codnar/file"/>
+<embed src="codnar/data/yui/base.css" type="x-codnar/file"/>
+<embed src="codnar/data/style.css" type="x-codnar/file"/>
+<embed src="codnar/data/sunlight/default.css" type="x-codnar/file"/>
+</style>
+</head>
+<body>
+<div id="contents"></div>
+<embed src="README.rdoc" type="x-codnar/include"/>
+<embed src="doc/system.markdown" type="x-codnar/include"/>
+<script type="text/javascript">
+<embed src="codnar/data/contents.js" type="x-codnar/file"/>
+<embed src="codnar/data/control_chunks.js" type="x-codnar/file"/>
+<embed src="codnar/data/sunlight/min.js" type="x-codnar/file"/>
+<embed src="codnar/data/sunlight/ruby-min.js" type="x-codnar/file"/>
+Sunlight.globalOptions.lineNumbers = false;
+Sunlight.highlightAll();
+</script>
+</body>
+</html>

data/doc/system.markdown ADDED Viewed

@@ -0,0 +1,283 @@
+## Rakefile ##
+Olag's Rakefile is a good example of how to use Olag's classes to create a
+full-featured gem Rakefile:
+[[Rakefile|named_chunk_with_containers]]
+The overall Rakefile structure is as follows:
+* A first line sets up the Ruby module load path to begin with
+  the current gem's `lib` directory. This standard idiom ensures we have access
+  to the current gem.
+* The next line imports Olag's `rake` support module.
+* This is followed by setting up the gem specification, which is enhanced by
+  Olag using monkey-patching.
+* Finally, Olag::Rake sets up the following tasks (as reported by `rake -T`):
+      rake all               # Version, verify, document, package
+      rake analyze           # Analyze source code
+      rake changelog         # Update ChangeLog from Git
+      rake clean             # Remove any temporary products.
+      rake clean_codnar      # Clean all split chunks
+      rake clobber           # Remove any generated file.
+      rake clobber_codnar    # Remove woven HTML documentation
+      rake clobber_coverage  # Remove rcov products for coverage
+      rake clobber_package   # Remove package products
+      rake clobber_rdoc      # Remove rdoc products
+      rake codnar            # Build the code narrative HTML
+      rake codnar_split      # Split all files into chunks
+      rake codnar_weave      # Weave chunks into HTML
+      rake commit            # Git commit process
+      rake coverage          # Test code covarage with RCov
+      rake doc               # Generate all documentation
+      rake first_commit      # Perform the 1st (main) Git commit
+      rake flay              # Check for duplicated code with Flay
+      rake gem               # Build the gem file olag-<version>.gem
+      rake package           # Build all the packages
+      rake rdoc              # Build the rdoc HTML Files
+      rake reek              # Check for smelly code with Reek
+      rake repackage         # Force a rebuild of the package files
+      rake rerdoc            # Force a rebuild of the RDOC files
+      rake roodi             # Check for smelly code with Roodi
+      rake saikuro           # Check for complex code with Saikuro
+      rake second_commit     # Perform the 2nd (amend) Git commit
+      rake test              # Run tests for test
+      rake verify            # Test, coverage, analyze code
+      rake version           # Update version file from Git
+### Gem Specification ###
+The gem specification is provided as usual:
+[[Gem specification|named_chunk_with_containers]]
+However, the Gem::Specification class is monkey-patched to automatically
+several of the specification fields, and adding some new ones:
+[[lib/olag/gem_specification.rb|named_chunk_with_containers]]
+### Rake tasks ###
+The Olag::Rake class sets up the tasks listed above as follows:
+[[lib/olag/rake.rb|named_chunk_with_containers]]
+#### Task utilities ####
+The following utilities are used to create the different tasks. It would have
+be nicer if Rake had treated the task description as just another task
+property.
+[[Task utilities|named_chunk_with_containers]]
+#### Verify the gem ####
+The following tasks verify that the gem is correct. Testing for 100% code
+coverage seems excessive but in reality it isn't that hard to do, and is really
+only a modest form of test coverage verification.
+[[Verify gem functionality|named_chunk_with_containers]]
+The following tasks verify that the code is squeacky-clean. While passing the
+code through all these verifiers seems excessive, it isn't that hard to achieve
+in practice. There were several times I did refactorings "just to satisfy
+`reek` (or `flay`)" and ended up with an unexpected code improvement. Anyway,
+if you aren't a youch OCD about this sort of thing, Olag is probably not for
+you :-)
+[[Analyze the source code|named_chunk_with_containers]]
+#### Generate Documentation ####
+The following tasks generate the usual RDoc documentation, required to make the
+gem behave well in the Ruby tool ecosystem:
+[[Generate RDoc documentation|named_chunk_with_containers]]
+The following tasks generate the Codnar documentation (e.g., the document you
+are reading now), which goes beyond RDoc to provide an end-to-end linear
+narrative describing the gem:
+[[Generate Codnar documentation|named_chunk_with_containers]]
+Codnar is very configurable, and the above provides a reasonable default
+configuration for pure Ruby gems. You can modify the CODNAR_CONFIGURATIONS
+array before creating the Rake object, by unshifting additional/overriding
+patterns into it. For example, you may choose to use GVim for syntax
+highlighting. This will cause splitting to become much slower, but the
+generated HTML will already include the highlighting markup so it will display
+instantly. Or, you may have additional source file types (Javascript, CSS,
+HTML, C, etc.) to be highlighted.
+#### Automate Git commit process ####
+In an ideal world, committing to Git would be a simple matter of typing `git
+commit -m "..."`. In our case, things get a bit complicated.
+There is some information that we need to extract out of Git and inject into
+our files (to be committed). Since Git pre-commit hooks do not allow us to
+modify any source files, this turns commit into a two-phase process: we do an
+initial commit, update some files, then `git commit --amend` to merge them with
+the first commit.
+[[Automate Git commit process|named_chunk_with_containers]]
+The first piece of information we need to extract from Git is the current build
+number, which needs to be injected into the gem's version number:
+[[lib/olag/version.rb|named_chunk_with_containers]]
+Documentation generation will depend on the content (and therefore modification
+time) of this file. Luckily, we can update this number before the first commit,
+and we can ensure it only touches the file if there is a real change, to avoid
+unnecessary documentation regeneration:
+[[lib/olag/update_version.rb|named_chunk_with_containers]]
+The second information we extract from Git is the ChangeLog file. Here,
+obviously, the ChangeLog needs to include the first commit's message, so we are
+forced to regenerate the file and amend Git's history with a second commit:
+[[lib/olag/change_log.rb|named_chunk_with_containers]]
+## Utility classes ##
+Olag provides a set of utility classes that are useful in implementing
+well-behaved gems.
+### Unindeting text ###
+When using "here documents" (`<<EOF` data), it is nice to be able to indent the
+data to match the surrounding code. There are other cases where it is useful to
+"unindent" multi-line text. The following tests demonstrates using the
+`unindent` function:
+[[test/unindent_text.rb|named_chunk_with_containers]]
+And here is the implementation extending the built-in String class:
+[[lib/olag/string_unindent.rb|named_chunk_with_containers]]
+### Accessing gem data files ###
+Sometimes it is useful to package some files inside a gem, to be read by user
+code. This is of course trivial for Ruby code files (just use `require`) but
+not trivial if you want, say, to include some CSS files in your gem for
+everyone to use. Olag provides a way to resolve the path of any file in any gem
+(basically replicating what `require` does). Here is a simple test of using
+this functionality:
+[[test/access_data_files.rb|named_chunk_with_containers]]
+And here is the implementation:
+[[lib/olag/data_files.rb|named_chunk_with_containers]]
+### Simulating objects with Hash tables ###
+Javascript has an interesting convention where `hash["key"]` and `hash.key`
+mean the same thing. This is very useful in cutting down boilerplate code, and
+it also makes your data serialize to very clean YAML. Unlike OpenStruct, you do
+not need to define all the members in advance, and you can alternate between
+the `.key` and `["key"]` forms as convenient for any particular piece of code.
+The down side is that you lose any semblance of type checking - misspelled
+member names and other errors are silently ignored. Well, that's what we have
+unit tests for, right? :-)
+Olag provides an extension to the Hash class that provides the above, for these
+who have chosen to follow the dark side of the force. Here is a simple test
+demonstrating using this ability:
+[[test/missing_keys.rb|named_chunk_with_containers]]
+And here is the implementation:
+[[lib/olag/hash_struct.rb|named_chunk_with_containers]]
+### Collecting errors ###
+In library code, it is bad practice to terminate the program on an error.
+Raising an exception is preferrable, but that forces you to abort the
+processing. In some cases, it is preferrable to collect the error, skip a bit
+of processing, and continue (if only for detecting additional errors). For
+example, one would expect a compiler to emit more than just the first syntax
+error message.
+Olag provides an error collection class that also automatically formats the
+error to indicate its location. Here is a simple test that demonstrates
+collecting errors:
+[[test/collect_errors.rb|named_chunk_with_containers]]
+Which uses a mix-in that helps writing tests that use errors:
+[[lib/olag/test/with_errors.rb|named_chunk_with_containers]]
+Here is the actual implementation:
+[[lib/olag/errors.rb|named_chunk_with_containers]]
+### Testing with a fake file system ###
+Sometimes tests need to muck around with disk files. One way to go about it is
+to create a temporary disk directory, work in there, and clean it up when done.
+Another, simpler way is to use the FakeFS file system, which captures all(most)
+of Ruby's file operations and redirect them to an in-memory fake file system.
+Here is a mix-in that helps writing tests using FakeFS (we will use it below
+when running applications inside unit tests):
+[[lib/olag/test/with_fakefs.rb|named_chunk_with_containers]]
+### Testing with a temporary file ###
+When running external programs, actually generating a temporary disk file is
+sometimes inevitable. Of course, such files need to be cleaned up when the test
+is done. If we need more than just one such file, it is easier to create a
+whole temporary directory which is easily cleaned up in one operation.
+Here is a mix-in that helps writing tests using temporary files and folders:
+[[lib/olag/test/with_tempfile.rb|named_chunk_with_containers]]
+### Testing Rake tasks ###
+Testing Rake tasks is tricky because tests may be run in the context of Rake.
+Therefore, the best practice is to create a new Rake application and restore
+the original when the test is done:
+[[lib/olag/test/with_rake.rb|named_chunk_with_containers]]
+### Testing in general ###
+Rather than requiring each of the above test mix-in modules on its own, it is
+convenient to just `require "olag/test"` and be done:
+[[lib/olag/test.rb|named_chunk_with_containers]]
+## Applications ##
+Writing an application requires a lot of boilerplate. Olag provides an
+Application base class that handles standard command line flags, execution from
+within tests, and errors collection.
+Here is a simple test for running such an application from unit tests:
+[[test/run_application.rb|named_chunk_with_containers]]
+And here is the implementation:
+[[lib/olag/application.rb|named_chunk_with_containers]]
+It makes use of the following utility class, for saving and restoring the
+global state when running an application in a test:
+[[lib/olag/globals.rb|named_chunk_with_containers]]
+## License ##
+Olag is published under the MIT license:
+[[LICENSE|named_chunk_with_containers]]

data/lib/olag/application.rb ADDED Viewed

@@ -0,0 +1,167 @@
+require "fileutils"
+require "olag/errors"
+require "olag/globals"
+require "olag/string_unindent.rb"
+require "olag/version"
+require "optparse"
+module Olag
+  # Base class for Olag applications.
+  class Application
+    # Create a Olag application.
+    def initialize(is_test = nil)
+      @errors = Errors.new
+      @is_test = !!is_test
+    end
+    # Run the Olag application, returning its status.
+    def run(*arguments, &block)
+      parse_options
+      yield(*arguments) if block_given?
+      return print_errors
+    rescue ExitException => exception
+      return exception.status
+    end
+    # Execute a block with an overriden ARGV, typically for running an
+    # application.
+    def self.with_argv(argv)
+      return Globals.without_changes do
+        ARGV.replace(argv)
+        yield
+      end
+    end
+  protected
+    # Parse the command line options of the program.
+    def parse_options
+      parser = OptionParser.new do |options|
+        (@options = options).banner = banner + "\n\nOPTIONS:\n\n"
+        define_flags
+      end
+      parser.parse!
+      parse_arguments
+    end
+    # Parse remaining command-line file arguments. This is expected to be
+    # overriden by the concrete application sub-class. By default assumes there
+    # are no such arguments.
+    def parse_arguments
+      return if ARGV.size == 0
+      $stderr.puts("#{$0}: Expects no command line file arguments.")
+      exit(1)
+    end
+    # Define application flags. This is expected to be overriden by the
+    # concrete application sub-class.
+    def define_flags
+      define_help_flag
+      define_version_flag
+      define_redirect_flag("$stdout", "output", "w")
+      define_redirect_flag("$stderr", "error", "w")
+      #! Most scripts do not use this, but they can add it.
+      #! define_redirect_flag("$stdin", "input", "r")
+    end
+    # Define the standard help flag.
+    def define_help_flag
+      @options.on("-h", "--help", "Print this help message and exit.") do
+        puts(@options)
+        print_additional_help
+        exit(0)
+      end
+    end
+    # Print additional help message. This includes both the command line file
+    # arguments, if any, and a short description of the program.
+    def print_additional_help
+      arguments_name, arguments_description = arguments
+      puts(format("    %-33s%s", arguments_name, arguments_description)) if arguments_name
+      print("\nDESCRIPTION:\n\n")
+      print(description)
+    end
+    # Return the banner line of the help message. This is expected to be
+    # overriden by the concrete application sub-class. By default returns the
+    # path name of thje executed program.
+    def banner
+      return $0
+    end
+    # Return the name and description of any final command-line file arguments,
+    # if any. This is expected to be overriden by the concrete application
+    # sub-class. By default, assume there are no final command-line file
+    # arguments (however, `parse_options` does not enforce this by default).
+    def arguments
+      return nil, nil
+    end
+    # Return a short description of the program. This is expected to be
+    # overriden by the concrete application sub-class. By default, provide
+    def description
+      return "Sample description\n"
+    end
+    # Define the standard version flag.
+    def define_version_flag
+      version_number = version
+      @options.on("-v", "--version", "Print the version number (#{version_number}) and exit.") do
+        puts("#{$0}: Version: #{version_number}")
+        exit(0)
+      end
+    end
+    # Define a flag redirecting one of the standard IO files.
+    def define_redirect_flag(variable, name, mode)
+      @options.on("-#{name[0,1]}", "--#{name} FILE", String, "Redirect standard #{name} to a file.") do |file|
+        eval("#{variable} = Application::redirect_file(#{variable}, file, mode)")
+      end
+    end
+    # Redirect a standard file.
+    def self.redirect_file(default, file, mode)
+      return default if file.nil? || file == "-"
+      FileUtils.mkdir_p(File.dirname(File.expand_path(file))) if mode == "w"
+      return File.open(file, mode)
+    end
+    # Return the application's version. This is expected to be overriden by the
+    # concrete application sub-class. In the base class, we just return Olag's
+    # version which only useful for Olag's tests.
+    def version
+      return Olag::VERSION
+    end
+    # Print all the collected errors.
+    def print_errors
+      @errors.each do |error|
+        $stderr.puts(error)
+      end
+      return @errors.size
+    end
+    # Exit the application, unless we are running inside a test.
+    def exit(status)
+      Kernel.exit(status) unless @is_test
+      raise ExitException.new(status)
+    end
+  end
+  # Exception used to exit when running inside tests.
+  class ExitException < Exception
+    # The exit status.
+    attr_reader :status
+    # Create a new exception to indicate exiting the program with some status.
+    def initialize(status)
+      @status = status
+    end
+  end
+end