Class: Hoe

Class | Hoe
In: | lib/hoe.rb
Parent: | Object

Hoe is a simple rake/rubygems helper for project Rakefiles. It helps generate rubygems and includes a dynamic plug-in system allowing for easy extensibility. Hoe ships with plug-ins for all your usual project tasks including rdoc generation, testing, packaging, and deployment.

## Using Hoe

### Basics

Sow generates a new project from scratch. Sow uses a simple ERB templating system allowing you to capture patterns common to your projects. Run `sow` and then see ~/.hoe_template for more info:

      % sow project_name
      ...
      % cd project_name

and have at it.

### Extra Configuration Options:

Hoe maintains a config file for cross-project values. The file is located at `~/.hoerc`. The file is a YAML formatted config file with the following settings (extended by plugins):

exclude: | A regular expression of files to exclude from `check_manifest`.

Run ``rake config_hoe`` and see ~/.hoerc for examples.

## Extending Hoe

Hoe can be extended via its plugin system. Hoe searches out all installed files matching `‘hoe/*.rb‘` and loads them. Those files are expected to define a module matching the file name. The module must define a define task method and can optionally define an initialize method. Both methods must be named to match the file. eg

      module Hoe::Blah
        def initialize_blah # optional
          # ...
        end

        def define_blah_tasks
          # ...
        end
      end

### Methods

activate_plugins add_dependencies add_include_dirs define_spec developer intuit_values load_plugin_tasks load_plugins missing normalize_deps paragraphs_of pluggable! plugin plugins post_initialize spec timebomb validate_fields

### Classes and Modules

Module Hoe::Clean
Module Hoe::Debug
Module Hoe::Deps
Module Hoe::Flay
Module Hoe::Flog
Module Hoe::Inline
Module Hoe::Package
Module Hoe::Publish
Module Hoe::RCov
Module Hoe::Signing
Module Hoe::Test

### Constants

VERSION | = | '2.3.3' |  | duh
RUBY_DEBUG | = | ENV['RUBY_DEBUG'] |  | Used to add extra flags to RUBY_FLAGS.
RUBY_FLAGS | = | ENV['RUBY_FLAGS'] || default_ruby_flags |  | Used to specify flags to ruby [has smart default].
DEFAULT_CONFIG | = | { "exclude" => /tmp$|CVS|\.svn|\.log$/, } |  | Default configuration values for .hoerc. Plugins should populate this on load.
WINDOZE | = | /mswin|mingw/ =~ RUBY_PLATFORM unless defined? WINDOZE |  | True if you‘re a masochistic developer. Used for building commands.

### Attributes

author | [RW] | MANDATORY: The author(s) of the package. (can be array) Use the developer method to fill in both author and email cleanly.
changes | [RW] | Optional: A description of the release‘s latest changes. Auto-populates.
description | [RW] | Optional: A description of the project. Auto-populates.
description_sections | [RW] | Optional: What sections from the readme to use for auto-description. Defaults to %w(description).
email | [RW] | MANDATORY: The author‘s email address(es). (can be array) Use the developer method to fill in both author and email cleanly.
extra_deps | [RW] | Optional: An array of rubygem dependencies.
      extra_deps << ['blah', '~> 1.0']
extra_dev_deps | [RW] | Optional: An array of rubygem developer dependencies.
extra_rdoc_files | [RW] | Optional: Extra files you want to add to RDoc. .txt files are automatically included (excluding the obvious).
history_file | [RW] | Optional: The filename for the project history. [default: History.txt]
name | [RW] | MANDATORY: The name of the release. Set via Hoe.spec.
post_install_message | [RW] | Optional: A post-install message to be displayed when gem is installed.
readme_file | [RW] | Optional: The filename for the project readme. [default: README.txt]
rubyforge_name | [RW] | Optional: The name of the rubyforge project. [default: name.downcase]
spec_extras | [RW] | Optional: A hash of extra values to set in the gemspec. Value may be a proc.
      spec_extras[:required_rubygems_version] = '>= 1.3.2'
(tho, see pluggable! if that‘s all you want to do)
summary | [RW] | Optional: A short summary of the project. Auto-populates.
summary_sentences | [RW] | Optional: Number of sentences from description for summary. Defaults to 1.
test_globs | [RW] | Optional: An array of test file patterns [default: test/**/test_*.rb]
url | [RW] | Optional: The url(s) of the project. (can be array). Auto-populates.
version | [RW] | MANDATORY: The version. Don‘t hardcode! use a constant in the project.

### Public Class methods

add_include_dirs(*dirs)

Add extra dirs to both $: and RUBY_FLAGS (for test runs and rakefile deps)

load_plugins()

Find and load all plugin files.

It is called at the end of hoe.rb

plugin(*names)

Activate plugins.

plugins()

Return the list of activated plugins.

spec(name, &block)

Create a new hoe-specification executing the supplied block

### Public Instance methods

activate_plugins()

Activate plugin modules and add them to the current instance.

add_dependencies()

Add standard and user defined dependencies to the spec.

define_spec()

Define the Gem::Specification.

developer(name, email)

Convenience method to set add to both the author and email fields.

intuit_values()

Intuit values from the readme and history files.

load_plugin_tasks()

Load activated plugins by calling their define tasks method.

missing(name)

Bitch about a file that is missing data or unparsable for intuiting values.

normalize_deps(deps)

Normalize the dependencies.

paragraphs_of(path, *paragraphs)

Reads a file at `path` and spits out an array of the `paragraphs` specified.

      changes = p.paragraphs_of('History.txt', 0..1).join("\n\n")
      summary, *description = p.paragraphs_of('README.txt', 3, 3..8)

pluggable!()

Tell the world you‘re a pluggable package (ie you require rubygems 1.3.1+)

post_initialize()

Finalize configuration

timebomb(n, m, finis = '2010-04-01', start = '2009-03-14')

Provide a linear degrading value from n to m over start to finis dates.

validate_fields()

Verify that mandatory fields are set.

[Validate]