Parent

Files

POM::Project

The Project class provides the location of specific directories and files in the project, plus access to the projects metadata, etc.

Constants

README

File glob for matching README file.

Attributes

root[R]

Project’s root location. By default this is determined by scanning up from the current working directory in search of the ROOT_INDICATOR.

source[R]

Location of project source code. Currently, this is always the same as the root.

Public Class Methods

load(*path_opts) click to toggle source

New project with metadata fully loaded.

# File lib/pom/project.rb, line 36
def self.load(*path_opts)
  path = path_opts.shift unless Hash===options.first
  opts = path_opts.last
  opts[:load] = true
  new(path, opts)
end
lookup(*path_opts) click to toggle source

Instantiate a new Project looking up the root directory form a given local.

Project.lookup(local)
# File lib/pom/project.rb, line 28
def self.lookup(*path_opts)
  path = path_opts.shift unless Hash===options.first
  opts = path_opts.last
  opts[:lookup] =true
  new(path, opts)
end
new() click to toggle source
new(root)
new(local, :lookup=>true)

Instantiate a new project.

If a root directory is not given, it will be looked-up starting from the current working directory until a meta/ directory is found.

The :lookup option can be used to induce a lookup from a given location.

# File lib/pom/project.rb, line 55
def initialize(*root_opts)
  root = root_opts.shift unless Hash===root_opts.first
  opts = root_opts.last || {}

  if opts[:lookup] || !root
    root = self.class.root(root)
    raise("cannot locate project root -- #{root}") unless root
  end

  @root = Pathname.new(root)
  @opts = opts

  #metadata.load #if opts[:load]

  #if options[:lookup]
  #  @root = locate_root(local) || raise("can't locate project root -- #{local}")
  #end

  @source = root
end
root(local=Dir.pwd) click to toggle source

Locate the project’s root directory. See POM::root.

# File lib/pom/project.rb, line 19
def self.root(local=Dir.pwd)
  POM.root(local)
end

Public Instance Methods

about(*parts) click to toggle source

About project notice.

# File lib/pom/project.rb, line 358
def about(*parts)
  # pre-format data
  released = package.date ? "(#{package.date.strftime('%Y-%m-%d')})" : nil
  if parts.empty?
    s = []
    s << "#{profile.title} v#{package.version} #{released} (#{package.name}-#{package.version})"
    s << ""
    s << "#{profile.description || profile.summary}"
    s << ""
    s << "* home: #{profile.resources.homepage}"   if profile.resources.homepage
    s << "* work: #{profile.resources.work}"       if profile.resources.work
    s << "* talk: #{profile.resources.mail}"       if profile.resources.mail
    s << "* talk: #{profile.resources.forum}"      if profile.resources.forum
    s << "* repo: #{profile.resources.repository}" if profile.resources.repository
    s << ""
    s << "#{profile.copyright}"
    s.join("\n").gsub("\n\n\n", "\n\n")
  else
    parts.each do |field|
      case field.to_sym
      #when :settings
      #  puts settings.to_yaml
      when :profile
        puts profile.to_yaml
      else
        puts profile.__send__(field)
      end
    end
  end
end
announcement(*parts) click to toggle source

Project release announcement built on README.

# File lib/pom/project.rb, line 390
def announcement(*parts)
  ann = []
  parts.each do |part|
    case part
    when :message
      ann << "#{profile.title} #{self.version} has been released."
    when :description
      ann << "#{profile.description}"
    when :resources
      list = ''
      list << "* home: #{profile.resources.home}\n" if profile.resources.home
      list << "* work: #{profile.resources.work}\n" if profile.resources.work
      list << "* docs: #{profile.resources.docs}\n" if profile.resources.docs
      ann << list
    when :release
      ann << "= #{title} #{history.release}"
    when :version
      ann << "= #{history.release.header}"
    when :notes
      ann << "#{history.release.notes}"
    when :changes
      ann << "#{history.release.changes}"
    #when :line
    #  ann << ("-" * 4) + "\n"
    when :readme
      release = history.release.to_s
      if file = Dir.glob(README, File::FNM_CASEFOLD).first
        readme  = File.read(file).strip
        readme  = readme.gsub("Please see HISTORY file.", '= ' + release)
        ann << readme
      end
    when String
      ann << part
    when File
      ann << part.read
      part.close
    end
  end
  ann.join("\n\n").unfold
end
cache(path=nil) click to toggle source

The .cache/ directory is used by build tools to store temporary files. For instance, the pom command uses it to store backups of metadata entries when overwriting old entries. .cache/ should be in your SCM’s ignore list.

Get pathname of given cache path. Or without path returns the pathname for the cache directory.

# File lib/pom/project.rb, line 230
def cache(path=nil)
  if path
    cache + path
  else
    @cache ||= root + '.cache'
  end
end
codename() click to toggle source
# File lib/pom/project.rb, line 136
def codename
  metadata.codename
end
compiles?() click to toggle source
# File lib/pom/project.rb, line 353
def compiles?
  !extensions.empty?
end
config(path=nil) click to toggle source

The .config/ or config directory is a place for build tools to place their configration files.

Pathname of given config path. Or without path Returns the path to the config directory (either .config or config).

# File lib/pom/project.rb, line 244
def config(path=nil)
  if path
    config + path #root.glob_first('{.,}config' / path)
  else
    @config ||= root.first('{.,}config') || root + '.config'
  end
end
doc(path=nil) click to toggle source

The doc directory is the place to keep documentation. The directory is intended to be distributed with a package, but this is not often done these days since RubyGems generates RDocs on demand, and documentation is often found online.

Get pathname of given doc path. Or without path returns the pathname for the doc directory.

# File lib/pom/project.rb, line 196
def doc(path=nil)
  if path
    doc + path
  else
    @doc ||= root + 'doc'
  end
end
executables() click to toggle source

Returns list of executable files in bin/.

# File lib/pom/project.rb, line 342
def executables
  root.glob('bin/*').select{ |bin| bin.executable? }.map{ |bin| File.basename(bin) }
end
extensions() click to toggle source

List of extension configuration scripts. These are used to compile the extensions.

# File lib/pom/project.rb, line 348
def extensions
  root.glob('ext/**/extconf.rb')
end
history() click to toggle source

Access to project history.

# File lib/pom/project.rb, line 165
def history
  @history ||= History.new(root)
end
import_gemspec(gemspec=nil) click to toggle source

Import a Gem::Specification into a POM::Project. This is intended to make it farily easy to build a set of POM metadata files from pre-existing gemspec.

# File lib/pom/gemspec.rb, line 134
def import_gemspec(gemspec=nil)
  gemspec = gemspec || self.gemspec

  package.name         = gemspec.name
  package.version      = gemspec.version.to_s
  package.path         = gemspec.require_paths
  #package.arch        = gemspec.platform

  profile.title        = gemspec.name.capitalize
  profile.summary      = gemspec.summary
  profile.description  = gemspec.description
  profile.authors      = gemspec.authors
  profile.contact      = gemspec.email

  profile.resources.homepage = gemspec.homepage

  #metadata.extensions   = gemspec.extensions

  gemspec.dependencies.each do |d|
    next unless d.type == :runtime
    requires << "#{d.name} #{d.version_requirements}"
  end
end
import_readme(readme=nil) click to toggle source

Get POM metadata from a README. This is intended to make it fairly easy to build a set of POM’s metadata files if you already have a README.

# File lib/pom/readme.rb, line 182
def import_readme(readme=nil)
  readme = readme || self.readme

  package.name        = readme.name         if readme.name

  profile.title       = readme.title        if readme.title
  profile.description = readme.description  if readme.description
  profile.license     = readme.license      if readme.license
  profile.copyright   = readme.copyright    if readme.copyright
  profile.authors     = readme.authors      if readme.authors

  profile.resources.homepage = readme.homepage  if readme.homepage
  profile.resources.wiki     = readme.wiki      if readme.wiki
  profile.resources.issues   = readme.issues    if readme.issues
end
loadpath() click to toggle source
# File lib/pom/project.rb, line 131
def loadpath
  metadata.loadpath
end
log(path=nil) click to toggle source

The log/ directory stores log output created by build tools. If you want to publish your logs as part of your website (which might be a very nice thing to do) symlink it into you site location.

Get pathname of given log path. Or without path returns the pathname for the log directory.

# File lib/pom/project.rb, line 181
def log(path=nil)
  if path
    log + path
  else
    @log ||= root + 'log'
  end
end
manifest() click to toggle source

Project manifest. For manifest file use manifest.file.

# File lib/pom/project.rb, line 160
def manifest
  @manifest ||= Manifest.new(root)
end
metadata() click to toggle source

Provides access to both profile and package information through a single interface. This will probably be removed from API.

# File lib/pom/project.rb, line 96
def metadata
  @metadata ||= Metadata.new(root, @opts)
end
name() click to toggle source

Project name.

# File lib/pom/project.rb, line 116
def name
  metadata.name
end
news() click to toggle source

Access latest release notes.

# File lib/pom/project.rb, line 170
def news
  @news ||= News.new(root, :history=>history)
end
pack(path=nil) click to toggle source

Alias for pkg.

Alias for: pkg
package() click to toggle source

General information.

# File lib/pom/project.rb, line 106
def package
  metadata.package
end
package_name(options={}) click to toggle source

Package name is generally in the form of name-version, or name-version-platform if platform is specified.

# File lib/pom/project.rb, line 142
def package_name(options={})
  if platform = options[:platform]
    "#{name}-#{version}-#{platform}"
  else
    "#{name}-#{version}"
  end
end
Also aliased as: stage_name
pkg(path=nil) click to toggle source

Returns the pathname for the package directory. With path returns the pathname within the pacakge path.

# File lib/pom/project.rb, line 206
def pkg(path=nil)
  if path
    pkg + path
  else
    @pkg ||= root.first('{pkg,pack,package}{,s}') || root + 'pkg'
  end
  #@pkg ||=(
  #  dir = root.glob_first('{pack,pkg}{,s}') || 'pack'
  #  dir.mkdir_p unless dir.exist?
  #  dir
  #)
end
Also aliased as: pack
plugin(path=nil) click to toggle source

The plug/ directory serves the same purpose as the lib/ directory. It simply provides a place to put plugins separate from the main lib/ files.

Get pathname of given plugin path. Or without path returns the pathname for the plugin directory.

TODO: This assumes lib/ is in the load path, and is used to house plugin/. This is of course typical. However it is possible to alter the load path. So it may not always be the case. In the future, it must be decided if we should standardize around the lib/ convention (though you could still add others to the load path) or allow it to be complete free form. As I did for bin/, I prefer the former, but have not yet firmly decided.

# File lib/pom/project.rb, line 266
def plugin(path=nil)
  if path
    plugin + path
  else
    @plugin ||= root.first('lib/plugins') || root + 'lib/plugins'
  end
end
Also aliased as: plugins
plugins(path=nil) click to toggle source
Alias for: plugin
profile() click to toggle source

General information.

# File lib/pom/project.rb, line 101
def profile
  metadata.profile
end
readme() click to toggle source
# File lib/pom/readme.rb, line 175
def readme
  @readme ||= Readme.load(root)
end
release() click to toggle source

Current release information.

# File lib/pom/project.rb, line 111
def release
  metadata.release
end
require_rubygems() click to toggle source

Require RubyGems library.

# File lib/pom/gemspec.rb, line 6
def require_rubygems
  begin
    require 'rubygems' #/specification'
    #::Gem::manage_gems
  rescue LoadError
    raise LoadError, "RubyGems is not installed."
  end
end
requirements() click to toggle source

Requirements Configuration.

# File lib/pom/project.rb, line 154
def requirements
  @require ||= Require.new(root)
end
Also aliased as: requires
requires() click to toggle source
Alias for: requirements
script(path=nil) click to toggle source

The script/ directory is like the task/ directory but usually holds executables that are made available to the end-installers.

Get pathname of given script path. Or without path returns the pathname for the script directory.

# File lib/pom/project.rb, line 283
def script(path=nil)
  if path
    script + path
  else
    @script ||= root + 'script'
  end
end
site(path=nil) click to toggle source

The site/ directory (also web/ or website/) is where a project’s website is stored.

Get pathname of given site path. Or without path returns the pathname for the site directory.

# File lib/pom/project.rb, line 309
def site(path=nil)
  if path
    site + path
  else
    @site ||= root.first('{site,web,website}') || root+'site'
  end
  #@pkg ||=(
  #  dir = root.glob_first('{pack,pkg}{,s}') || 'pack'
  #  dir.mkdir_p unless dir.exist?
  #  dir
  #)
end
stage_name(options={}) click to toggle source

DEPRECATE

Alias for: package_name
task(path=nil) click to toggle source

The task/ directory is where task scripts are stored used by build tools, such as Rake and Syckle.

Get pathname of given task path. Or without path returns the pathname for the task directory.

# File lib/pom/project.rb, line 296
def task(path=nil)
  if path
    task + path
  else
    @task ||= root.first('{task,tasks}') || root+'task'
  end
end
tmp(path=nil) click to toggle source

Not strickly a project directory. THis provides a temporary system location outside the project directory.

Get pathname of given temporary path. Or without path returns the pathname to the temporary directory.

# File lib/pom/project.rb, line 330
def tmp(path=nil)
  if path
    tmp + path
  else
    @tmp ||= Pathname.new(Dir.tmpdir) #cache+'tmp'
  end
end
Also aliased as: tmpdir
tmpdir(path=nil) click to toggle source

Alias for tmp.

Alias for: tmp
to_gemspec(options={}) click to toggle source

Create a Gem::Specification from a POM::Project. Becuase POM metadata is extensive a fairly complete Gem::Specification can be created from it –sufficient for almost all needs.

TODO: However there are still a few features that need address, such as gem signatures.

# File lib/pom/gemspec.rb, line 22
def to_gemspec(options={})
  require_rubygems

  if md = /(\w+).rubyforge.org/.match(profile.homepage)
    rubyforge_project = md[1]
  else
    rubyforge_project = metadata.name  # b/c it has to be something according to Eric Hodel.
  end

  ::Gem::Specification.new do |spec|
    spec.name          = self.name
    spec.version       = self.version
    spec.require_paths = self.loadpath

    spec.summary       = profile.summary
    spec.description   = profile.description
    spec.authors       = profile.authors
    spec.email         = profile.email

    spec.homepage      = profile.homepage

    # -- platform --

    # TODO: how to handle multiple platforms?
    spec.platform = options[:platform] #|| verfile.platform  #'ruby' ???
    #if metadata.platform != 'ruby'
    #  spec.require_paths.concat(spec.require_paths.collect{ |d| File.join(d, platform) })
    #end

    # -- rubyforge project --

    spec.rubyforge_project = rubyforge_project

    # -- compiled extensions --

    spec.extensions = options[:extensions] || self.extensions

    # -- dependencies --

    case options[:gemfile]
    #when String
    #  gemfile = root.glob(options[:gemfile]).first  # TODO: Alternate gemfile
    when nil, true
      gemfile = root.glob('Gemfile').first
    else
      gemfile = nil
    end

    if gemfile
      require 'bundler'
      spec.add_bundler_dependencies

    elsif requires.file
      requires.dependencies.each do |dep|
        if dep.development?
          spec.add_development_dependency( *[dep.name, dep.constraint].compact )
        else
          next if dep.optional?
          spec.add_runtime_dependency( *[dep.name, dep.constraint].compact )
        end
      end

    end

    # TODO: considerations?
    #spec.requirements = options[:requirements] || package.consider

    # -- executables --

    # TODO: bin/ is a POM convention, is there are reason to do otherwise?
    spec.bindir      = options[:bindir]      || "bin"
    spec.executables = options[:executables] || self.executables

    # -- rdocs (argh!) --

    readme = root.glob_relative('README{,.*}', File::FNM_CASEFOLD).first
    extra  = options[:extra_rdoc_files] || []

    rdocfiles = []
    rdocfiles << readme.to_s if readme
    rdocfiles.concat(extra)
    rdocfiles.uniq!

    rdoc_options = [] #['--inline-source']
    rdoc_options.concat ["--title", "#{metadata.title} API"] #if metadata.title
    rdoc_options.concat ["--main", readme.to_s] if readme

    spec.has_rdoc         = true  # always true
    spec.extra_rdoc_files = rdocfiles
    spec.rdoc_options     = rdoc_options

    # -- distributed files --

    if manifest.exist?
      filelist = manifest.select{ |f| File.file?(f) }
      spec.files = filelist
    else
      spec.files = root.glob_relative("**/*").map{ |f| f.to_s } # metadata.distribute ?
    end

    # -- test files --

    # TODO: Improve. Make test_files configurable (?)
    spec.test_files = manifest.select do |f|
      File.basename(f) =~ /test/ && File.extname(f) == '.rb'
    end
  end

end
version() click to toggle source

Version number string representation, e.g. “1.0.0”.

# File lib/pom/project.rb, line 121
def version
  metadata.version
end

[Validate]

Generated with the Darkfish Rdoc Generator 2.