class SC::Generator

A generator is a special kind of project that can process some input templates to generate some default content in a target project.

Setup Process

When a generator is created, the generator's environment is setup accoding to the following process:

1. Process any passed :arguments hash (also saved as 'arguments')
2. Invoke any defined generator:prepare task to do further set'
3. Search the target project for a target with the target_name if set.

Standard Options

These options are automatically added to the generator if possible. Your generator code should expect to work with them. The following examples assume you pass as an argument either “AddressBook.Contact” or “address_book/contact”.

target_name::
  the name of the target to use as the root.  Defaults to the snake case
  version of the passed namepace.  This can be overridden by passing the
  "target_name" option to new().  example: "address_book"

target::
  If target_name is not nil and a target is found with a matching name,
  then this will be set to that target.  example: Target(/address_book)

build_root::
  If target is not nil, set to the source_root for the target.  If no
  target, set to the project_root for the current target project.  If no
  project is defined, set to the current working directory.  May be
  overridden with build_root option to new().  example:
  /Users/charles/projects/my_project/apps/address_book

filename::
  The filename as passed in arguments.  example: "contact"

namespace::
  The classified version of the target name.  example: "AddressBook"

css_name::
  The CSS class name version of the target name. example: 'address-book'

class_name::
  The classified version of the filename.  example: "Contact"

method_name::
  If a full three-part Namespace.ClassName.methodName is passed, this
  property will be set to the method name.  example: nil (no method name
  included)

Constants

ABBREVIATIONS

Attributes

logger[R]
target_project[R]

the target project to build in or nil if no target provided

Public Class Methods

installed_generators_for(project) click to toggle source

Discover all installed generators for a particular project.

# File lib/sproutcore/models/generator.rb, line 77
def self.installed_generators_for(project)
  ret = []
  while project
    %w(generators sc_generators gen).each do |dirname|
      Dir.glob(project.project_root / dirname / '**').each do |path|
        ret << File.basename(path) if File.directory?(path)
      end
    end
    project = project.parent_project
  end
  return ret.uniq.compact.sort
end
load(generator_name, opts={}) click to toggle source

Creates a new generator. Expects you to pass at least a generator name and additional options including the current target project. This will search for a generator source directory in the target project and any parent projects. The source directory must live inside a folder called “gen” or “generators”. The source directory must contain a Buildfile and a templates directory to be considered a valid generator.

If no valid generator can be found matching the generator name, this method will return null

# File lib/sproutcore/models/generator.rb, line 100
def self.load(generator_name, opts={})

  # get the project to search and look for the generator
  target_project = project = opts[:target_project] || SC.builtin_project
  path = ret = nil

  # attempt to discover the the generator
  while project && path.nil?
    %w(generators sc_generators gen).each do |dirname|
      path = File.join(project.project_root, dirname, generator_name)
      if File.directory?(path)
        has_buildfile = File.exists?(path / 'Buildfile')
        has_templates = File.directory?(path / 'templates')
        break if has_buildfile && has_templates
      end
      path = nil
    end
    project = project.parent_project
  end

  # Create project if possible
  ret = self.new(generator_name, opts.merge(:source_root => path, :target_project => target_project)) if path
  return ret
end
new(generator_name, opts = {}) click to toggle source
Calls superclass method
# File lib/sproutcore/models/generator.rb, line 125
def initialize(generator_name, opts = {})
  super()

  @target_project = opts[:target_project] || opts['target_project']
  @logger = opts[:logger] || opts['logger'] || SC.logger
  @buildfile = nil

  # delete special options
  %w(target_project logger).each do |key|
    opts.delete(key)
    opts.delete(key.to_sym)
  end

  # copy any remaining options onto generator
  opts.each { |key, value| self[key] = value }
  self.generator_name = generator_name

end

Public Instance Methods

build!() click to toggle source

Executes the generator based on the current config options. Raises an exception if anything failed during the build. This will copy each file from the source, processing it with the rhtml template.

# File lib/sproutcore/models/generator.rb, line 221
def build!
  prepare! # if needed
  buildfile.invoke 'generator:build', :generator => self
  return self
end
buildfile() click to toggle source

The current buildfile for the generator. The buildfile is calculated by merging the buildfile for the generator with the default generator buildfile. Buildfiles should be named “Buildfile” and should be placed in the generator root directory.

Returns

Buildfile instance
# File lib/sproutcore/models/generator.rb, line 156
def buildfile
  return @buildfile unless @buildfile.nil?

  @buildfile = Buildfile.new

  # First try to load the shared buildfile
  path = File.join(SC.builtin_project.project_root, 'gen', 'Buildfile')
  if !@buildfile.load!(path).loaded_paths.include?(path)
    SC.logger.warn("Could not load shared generator buildfile at #{buildfile_path}")
  end

  # Then try to load the buildfile for the generator
  path = File.join(source_root, 'Buildfile')
  @buildfile.load!(path)

  return @buildfile
end
camel_case(str, capitalize=true) click to toggle source

Converts a string to CamelCase. If you pass false for the second param then the first letter will be lower case rather than upper. This will first snake_case the passed string. This version differs from the standard camel_case provided by extlib by supporting a few standard abbreviations that are always make upper case.

Examples

camel_case("foo_bar")                #=> "FooBar"
camel_case("headline_cnn_news")      #=> "HeadlineCnnNews"
camel_case("html_formatter")     #=> "HTMLFormatter"

Params

str:: the string to camel case
capitalize:: capitalize first character if true (def: true)
# File lib/sproutcore/models/generator.rb, line 471
def camel_case(str, capitalize=true)
  str = snake_case(str) # normalize
  str.gsub(capitalize ? /(\A|_+)([^_]+)/ : /(_+)([^_]+)/) do
    ABBREVIATIONS.include?($2) ? $2.upcase : $2.capitalize
  end
end
config() click to toggle source

The config for the current generator. The config is computed by merging the config settings for the current buildfile and the current build environment.

Returns

merged HashStruct
# File lib/sproutcore/models/generator.rb, line 181
def config
  return @config ||= buildfile.config_for(:templates, SC.build_mode).merge(SC.env)
end
copy_file(src_path, dst_path) click to toggle source

Copies from source to destination, running the contents through ERB if the file appears to be a text file. The destination file must not exist or else a warning will be logged.

Returns

true if copied successfully.  false otherwise
# File lib/sproutcore/models/generator.rb, line 378
def copy_file(src_path, dst_path)

  # interpolate dst_path to include any variables
  dst_path = expand_path(dst_path)

  src_filename = src_path.sub(self.source_root / '', '')
  dst_filename = dst_path.sub(self.build_root / '', '')
  ret = true

  # if the source path does not exist, just log a warning and return
  if !File.exist? src_path
    warn "Did not copy #{src_filename} because the source does not exist."
    ret = false

  # when copying a directory just make the dir if needed
  elsif File.directory?(src_path)
    logger << " ~ Created directory at #{dst_filename}\n" if !File.exist?(dst_path)
    FileUtils.mkdir_p(dst_path) unless self.dry_run

  # if destination already exists, just log warning
  elsif File.exist?(dst_path) && !self.force
    warn "Did not overwrite #{dst_filename} because it already exists."
    ret = false

  # process file through erubis and copy
  else
    require 'erubis'

    input = File.read(src_path)
    eruby = ::Erubis::Eruby.new input
    output = eruby.result(binding())

    unless self.dry_run
      FileUtils.mkdir_p(File.dirname(dst_path))
      file = File.new(dst_path, 'w')
      file.write output
      file.close
    end

    logger << " ~ Created file at #{dst_filename}\n"
  end
  return ret
end
css_case(str='') click to toggle source

Converts a string to CSS case. This method will accept CamelCase or snake case and normalize into a format that can be converted to CSS case.

# File lib/sproutcore/models/generator.rb, line 448
def css_case(str='')
  snake_case(str).gsub(/_/, '-')
end
debug(description) click to toggle source

Helper method. Call this when you want to log a debug message.

# File lib/sproutcore/models/generator.rb, line 242
def debug(description); logger.debug(description); end
each_template(source_dir = nil, build_dir=nil) { |filename, src_path, dst_path| ... } click to toggle source

Calls your block for each file and directory in the source template passing the expanded source path and the expanded destination directory

Expects you to include a block with the following signature:

block |filename, src_path, dst_path|

filename:: the filename relative to the source directory
src_path:: the full path to the source
dst_path:: the full destination path

Param

source_dir:: optional source directory.  Defaults to templates
build_dir::  optional build directory.  Defaults to build_root

Returns

self
# File lib/sproutcore/models/generator.rb, line 359
def each_template(source_dir = nil, build_dir=nil)
  source_dir = self.source_root / 'templates' if source_dir.nil?
  build_dir = self.build_root if build_dir.nil?

  Dir.glob(source_dir / '**' / '*').each do |src_path|
    filename = src_path.sub(source_dir / '', '')
    dst_path = build_dir / filename
    yield(filename, src_path, dst_path) if block_given?
  end
  return self
end
expand_path(path) click to toggle source

Converts a path with optional template variables into a regular path by looking up said variables on the receiver. Variables in the pathname must appear inside of a pair of @@.

# File lib/sproutcore/models/generator.rb, line 337
def expand_path(path)
  path = path.gsub(/@(.*?)@/) { self.send($1) || $1 }
  File.expand_path path
end
fatal!(description) click to toggle source

Helper method. Call this when an acception occurs that is fatal due to a problem with the user.

# File lib/sproutcore/models/generator.rb, line 233
def fatal!(description)
  raise description
end
info(description) click to toggle source

Helper method. Call this when you want to log an info message. Logs to the standard logger.

# File lib/sproutcore/models/generator.rb, line 239
def info(description); logger.info(description); end
log_file(src_path, a_logger = nil) click to toggle source

Logs the pass file to the logger after first processing it with Erubis. This is the code helper method used to log out USAGE and README files.

Params

src_path:: the file path for the logger
a_logger:: optional logger to use.  defaults to builtin logger

Returns

self
# File lib/sproutcore/models/generator.rb, line 258
def log_file(src_path, a_logger = nil)
  a_logger = self.logger if a_logger.nil?
  if !File.exists?(src_path)
    warn "Could not find #{File.basename(src_path)} in generator source"
  else
    require 'erubis'
    a_logger << Erubis::Eruby.new(File.read(src_path)).result(binding())
    a_logger << "\n"
  end
  return self
end
log_readme(a_logger=nil) click to toggle source

Logs the README file in the source_root if found or logs a warning.

# File lib/sproutcore/models/generator.rb, line 271
def log_readme(a_logger=nil)
  src_path = self.source_root / "README"
  log_file(src_path, a_logger)
end
log_usage(a_logger=nil) click to toggle source

Logs the USAGE file in the source_root if found or logs a warning.

# File lib/sproutcore/models/generator.rb, line 277
def log_usage(a_logger=nil)
  src_path = self.source_root / 'USAGE'
  log_file(src_path, a_logger)
end
namespace_class_name() click to toggle source

Returns the full namespace and class name if both are defined.

# File lib/sproutcore/models/generator.rb, line 287
def namespace_class_name
  [self.namespace, self.class_name].compact.join '.'
end
namespace_instance_name() click to toggle source

Returns the full namespace and object name if both are defined.

# File lib/sproutcore/models/generator.rb, line 292
def namespace_instance_name
  [self.namespace, self.instance_name].compact.join '.'
end
prepare!() click to toggle source

Prepares the generator state by parsing any passed arguments and then invokes the 'generator:prepare' task from the Buildfile, if one exists. Once a generator has been prepared, you can then build it.

# File lib/sproutcore/models/generator.rb, line 192
def prepare!
  return self if @is_prepared
  @is_prepared = true

  parse_arguments!

  has_project = target_project && target_project != SC.builtin_project
  if target_name && has_project && target.nil?
    self.target = target_project.target_for(target_name)
  end

  # Attempt to build a reasonable default build_root.  Usually this should
  # be the target path, but if a target can't be found, use the project
  # path.  If a project is not found or the target project is the builtin
  # project, then use the current working directory
  if target
    self.build_root = target.source_root
  else
    self.build_root = has_project ? target_project.project_root : Dir.pwd
  end

  # Execute prepare task - give the generator a chance to fixup defaults
  buildfile.invoke 'generator:prepare', :generator => self
  return self
end
requires!(*properties) { |key_name, value| ... } click to toggle source

Verifies that the passed array of keys are defined on the object. If you pass an optional block, the block will be invoked for each key so you can validate the value as well. Otherwise, this will raise an error if any of the properties are nil.

# File lib/sproutcore/models/generator.rb, line 322
def requires!(*properties)
  properties.flatten.each do |key_name|
    value = self.send(key_name)
    is_ok = !value.nil?
    is_ok = yield(key_name, value) if block_given? && is_ok
    unless is_ok
      fatal!("This generator requires a #{Extlib::Inflection.humanize key_name}")
    end
  end
  return self
end
snake_case(str='') click to toggle source

Converts a string to snake case. This method will accept any variation of camel case or snake case and normalize it into a format that can be converted back and forth to camel case.

Examples

snake_case("FooBar")           #=> "foo_bar"
snake_case("HeadlineCNNNews")  #=> "headline_cnn_news"
snake_case("CNN")              #=> "cnn"
snake_case("innerHTML")        #=> "inner_html"
snake_case("Foo_Bar")          #=> "foo_bar"
snake_case("Foo-Bar")          #=> "foo_bar"

Params

str:: the string to snake case
# File lib/sproutcore/models/generator.rb, line 439
def snake_case(str='')
  str = str.gsub(/-/, '_')
  str = str.gsub(/([^A-Z_])([A-Z][^A-Z]?)/,'\1_\2') # most cases
  str = str.gsub(/([^_])([A-Z][^A-Z_])/,'\1_\2') # HeadlineCNNNews
  str.downcase
end
warn(description) click to toggle source

Log this when you need to issue a warning.

# File lib/sproutcore/models/generator.rb, line 245
def warn(description); logger.warn(description); end

Protected Instance Methods

parse_arguments!() click to toggle source

Standardized parsing of arguments. This will accept an argument that is either a class name or a path name and generate both a class name and a pathname from it.

# File lib/sproutcore/models/generator.rb, line 484
def parse_arguments!
  name  = (self.arguments || [])[1]
  parts = name.include?('/') ? name.split('/') : name.split('.')

  # method_name would be extracted from for instance Todos.Task.methodName
  # for generators that allow it
  if parts[2] && self.method_name.nil?
    self.method_name = camel_case(parts[2], false)
  end

  # target_name is first part snake_cased, unless already defined
  if parts[0] && self.target_name.nil?
    self.target_name = snake_case(parts[0])
  end

  # namespace is first part CamelCases if defined.  Otherwise use
  # target_name if defined
  if (parts[0] || self.target_name) && self.namespace.nil?
    self.namespace = camel_case(parts[0] || self.target_name)
  end

  # css_name is first part css cased if defined
  if (parts[0] || self.target_name) && self.css_name.nil?
    self.css_name = css_case(parts[0] || self.target_name)
  end

  # filename is second part snake_cased, unless already defined
  if parts[1] && self.filename.nil?
    self.filename = snake_case(parts[1])
  end

  # class_name is second part CamcelCased if defined.  Otherwise use
  # filename if defined.
  if (parts[1] || self.filename) && self.class_name.nil?
    self.class_name = camel_case(parts[1] || self.filename)
  end

  # object_name is class name with first letter lower case.  Used in case
  # the template wants to define an instance instead of class.
  if self.class_name && self.instance_name.nil?
    self.instance_name = self.class_name.sub(/^(.)/) { |x| x.downcase }
  end

end