rant 0.3.4 → 0.3.6

data/doc/rantfile.rdoc

@@ -26,13 +26,16 @@ methods with the Rant application:
 		"rubypackage"</tt> first.
 +plugin+::	Instantiate a plugin. Example: <tt>plugin
 		:Configure</tt> instantiates the Configure plugin.
-+sys+::		When given argument(s), runs an external program.
-		Otherwise you can call methods to interact with the OS
-		on it.
++sys+::		Run external commands or call portable file system
+		manipulation methods (copy files, unlink files,
+		install, ...).
 +source+::	Takes a filename as argument and causes Rant to read
 		it in as Rantfile.
 +subdirs+::	Takes a list of subdirectories in which Rant should
 		look for Rantfiles.
++var+::		Provides access to variables accessible in Rantfiles
+		and from the commandline.
++rac+::		The "Rant compiler" which is compiling the Rantfiles.
 
 === Defining a task
 
@@ -203,23 +206,31 @@ Note::	You are highly encouraged to not <tt>include Rant::Sys</tt>
    read the ri docs to get an overview:
 	ri Dir::glob
 
+   From now on we'll call <tt>sys[...]</tt> the <it>glob
+   operator</it>.
+
    You can give more patterns:
 	c_files = sys["**/*.h", "**/*.c"]
    gives a list of all files ending in ".h" or ".c" in the current
    directory and all subdirectories.
 
-   The object returned by sys#[] _behaves_ like a list of string, so
-   it is possible to pass it to methods expecting an array. If you're
-   getting errors or experience strange behaviour convert the list
-   explicetely to an array:
+   The object returned by the glob operator _behaves_ like a list of
+   string, so it is possible to pass it to methods expecting an array.
+   If you're getting errors or experience strange behaviour convert
+   the list explicetely to an array:
 	sys.touch c_files.to_a
 
 === Generators
 
 The *gen* function takes a generator which usually creates one or more
-tasks for you. Currently are two generators immediately available:
+tasks for you. The following list of generators is immediately
+available:
 +Directory+::	Create directories.
 +Task+::	Define custom task.
++Rule+::	Define a rule (a rule produces tasks on the fly).
++Action+::	Run a block of code immediately.
+		The Action generator is discussed in
+		doc/advanced.rdoc[link:files/doc/advanced_rdoc.html].
 
 === The +Directory+ generator
 
@@ -294,11 +305,20 @@ last dot with the given string.
 
 The +import+ function lets you import additional generators.
 Currently the following are coming with Rant:
++Clean+::	Remove selected files.
++AutoClean+::	Remove all files generated by any file task (including
+		those generated by rules).
++DirectedRule+:: A Rule which takes sources from one or more
+		 directories and puts generated files into a specified
+		 directory.
 +RubyTest+::	Run Test::Unit tests for your Ruby code.
 +RubyDoc+::	Run RDoc.
 +RubyPackage+::	Generate tar, zip and gem packages of your Ruby
 		application/library.
-As these are all Ruby specific, please read the Ruby project howto.
+
+Read doc/advanced.rdoc[link:files/doc/advanced_rdoc.html] and
+doc/rubyproject.rdoc[link:files/doc/rubyproject_rdoc.html] for
+documentation.
 
 === The +subdirs+ command
 

data/lib/rant/import.rb

@@ -19,9 +19,6 @@ module Rant
     class RantImport
 	include Rant::Console
 
-	# TODO: We currently only look for imports and plugins
-	# relative to this LIB_DIR. We should also look in all pathes
-	# in $LOAD_PATH after looking in LIB_DIR.
 	LIB_DIR = File.expand_path(File.dirname(__FILE__))
 
 	OPTIONS = [
@@ -244,8 +241,8 @@ EOF
 	    rs = ""
 	    @imports.each { |name|
 		next if @included_imports.include? name
-		path = File.join(LIB_DIR, "import", "#{name}.rb")
-		unless File.exist? path
+		path = get_lib_rant_path "import/#{name}.rb"
+		unless path
 		    abort("No such import - #{name}")
 		end
 		msg "Including import `#{name}'", path
@@ -260,7 +257,7 @@ EOF
 	    @plugins.each { |name|
 		lc_name = name.downcase
 		next if @included_plugins.include? lc_name
-		path = File.join(LIB_DIR, "plugin", "#{lc_name}.rb")
+		path = get_lib_rant_path "plugin/#{lc_name}.rb"
 		unless File.exist? path
 		    abort("No such plugin - #{name}")
 		end
@@ -275,8 +272,6 @@ EOF
 	# code by directly inserting the code.
 	def resolve_requires script
 	    rs = ""
-	    # TODO: skip multiline comments (=begin, =end) only of
-	    # @skip_comments is true
 	    in_ml_comment = false
 	    script.each { |line|
 		if in_ml_comment
@@ -293,10 +288,15 @@ EOF
 		    in_ml_comment = true
 		    next if @skip_comments
 		end
+		name = nil
 		if line =~ /\s*(require|load)\s+('|")rant\/(\w+)(\.rb)?('|")/
 		    name = $3
+		elsif line =~ /\s*(require|load)\s+('|")rant\/(import\/\w+)(\.rb)?('|")/
+		    name = $3
+		end
+		if name
 		    next if @core_imports.include? name
-		    path = File.join(LIB_DIR, "#{name}.rb")
+		    path = get_lib_rant_path "#{name}.rb"
 		    msg "Including `#{name}'", path
 		    @core_imports << name
 		    rs << resolve_requires(File.read(path))
@@ -308,5 +308,15 @@ EOF
 	    rs
 	end
 
+	def get_lib_rant_path(fn)
+	    path = File.join(LIB_DIR, fn)
+	    return path if File.exist?(path)
+	    $:.each { |lib_dir|
+		path = File.join(lib_dir, "rant", fn)
+		return path if File.exist?(path)
+	    }
+	    nil
+	end
+
     end	# class RantImport
 end	# module Rant

data/lib/rant/import/autoclean.rb

@@ -0,0 +1,65 @@
+
+# autoclean.rb - "AutoClean" generator for Rant.
+#
+# Copyright (C) 2005 Stefan Lang <langstefan@gmx.at>
+
+require 'rant/rantlib'
+require 'rant/import/clean'
+
+class Rant::Generators::AutoClean
+    def self.rant_generate(rac, ch, args, &block)
+	# validate args
+	if args.size > 1
+	    rac.abort_at(ch,
+		"AutoClean doesn't take more than one argument.")
+	end
+	tname = args.first || "autoclean"
+
+	# we generate a normal clean task too, so that the user can
+	# add files to clean via a var
+	::Rant::Generators::Clean.rant_generate(rac, ch, [tname])
+
+	# create task
+	rac.task :__caller__ => ch, tname => [] do |t|
+	    rac.tasks.each { |n, worker|
+		worker.each_target { |entry|
+		    if test ?e, entry
+			if test ?f, entry
+			    rac.cx.sys.rm_f entry
+			else
+			    rac.cx.sys.rm_rf entry
+			end
+		    end
+		}
+	    }
+	    target_rx = nil
+	    rac.resolve_hooks.each { |hook|
+		if hook.respond_to? :each_target
+		    hook.each_target { |entry|
+			if test ?f, entry
+			    rac.cx.sys.rm_f entry
+			else
+			    rac.cx.sys.rm_rf entry
+			end
+		    }
+		elsif hook.respond_to? :target_rx
+		    next(rx) unless (t_rx = hook.target_rx)
+		    target_rx = target_rx.nil? ? t_rx :
+			Regexp.union(target_rx, t_rx)
+		end
+	    }
+	    if target_rx
+		rac.msg 1, "searching for rule products"
+		rac.cx.sys["**/*"].each { |entry|
+		    if entry =~ target_rx
+			if test ?f, entry
+			    rac.cx.sys.rm_f entry
+			else
+			    rac.cx.sys.rm_rf entry
+			end
+		    end
+		}
+	    end
+	end
+    end
+end

data/lib/rant/import/clean.rb

@@ -0,0 +1,45 @@
+
+# clean.rb - "Clean" generator for Rant.
+#
+# Copyright (C) 2005 Stefan Lang <langstefan@gmx.at>
+
+require 'rant/rantlib'
+
+class Rant::Generators::Clean
+    def self.rant_generate(rac, ch, args, &block)
+	# validate args
+	if args.size > 1
+	    rac.abort_at(ch, "Clean doesn't take more than one argument.")
+	end
+	tname = args.first || "clean"
+
+	# set var with task name to a MultiFileList
+	case rac.var[tname]
+	when nil
+	    rac.var[tname] = Rant::MultiFileList.new(rac)
+	when Rant::RacFileList
+	    ml = Rant::MultiFileList.new(rac)
+	    rac.var[tname] = ml.add(rac.var[tname])
+	when Rant::MultiFileList
+	    # ok, nothing to do
+	else
+	    # TODO: refine error message
+	    rac.abort_at(ch,
+		"var `#{tname}' already exists.",
+		"Clean uses var with the same name as the task name.")
+	end
+
+	# create task
+	rac.task :__caller__ => ch, tname => [] do |t|
+	    rac.var[tname].each_entry { |entry|
+		if test ?e, entry
+		    if test ?f, entry
+			rac.cx.sys.rm_f entry
+		    else
+			rac.cx.sys.rm_rf entry
+		    end
+		end
+	    }
+	end
+    end
+end # class Rant::Generators::Clean

data/lib/rant/import/directedrule.rb

@@ -0,0 +1,122 @@
+
+# directedrule.rb - "DirectedRule" generator for Rant.
+#
+# Copyright (C) 2005 Stefan Lang <langstefan@gmx.at>
+
+require 'rant/rantlib'
+
+class Rant::Generators::DirectedRule
+    def self.rant_generate(rac, ch, args, &block)
+	unless args.size == 1
+	    rac.abort_at(ch, "DirectedRule takes one arguments.")
+	end
+	h = args.first
+	if h.respond_to? :to_hash
+	    h = h.to_hash
+	else
+	    rac.abort_at(ch, "Argument has to be a hash.")
+	end
+	ts_h, dir_h = nil, nil
+	h.each { |k, v| v.respond_to?(:to_ary) ?
+	    dir_h = { k => v } :
+	    ts_h = { k => v }
+	}
+	unless dir_h
+	    rac.abort_at(ch,
+		"Source directory argument has to be a list.")
+	end
+	target, source = nil, nil
+	ts_h.each { |target, source| }
+	target_dir, source_dirs = nil, nil
+	dir_h.each { |target_dir, source_dirs| }
+	if target_dir.respond_to? :to_str
+	    target_dir = target_dir.to_str
+	else
+	    rac.abort_at(ch, "String required as target directory.")
+	end
+	if source_dirs.respond_to? :to_ary
+	    source_dirs = source_dirs.to_ary
+	elsif source_dirs.respond_to? :to_str
+	    source_dirs = [source_dirs.to_str]
+	else
+	    rac.abort_at(ch,
+		"List of strings or string required for source directories.")
+	end
+	target = ".#{target}" if Symbol === target
+	source = ".#{source}" if Symbol === source
+	if target.respond_to? :to_str
+	    target = target.to_str
+	else
+	    rac.abort_at(ch, "target has to be a string")
+	end
+	if source.respond_to? :to_str
+	    source = source.to_str
+	else
+	    rac.abort_at(ch, "source has to be a string or symbol")
+	end
+	blk = self.new(rac, ch, target_dir, source_dirs,
+	    target, source, &block)
+	blk.define_hook
+	blk
+    end
+    def initialize(rac, ch, target_dir, source_dirs,
+	    target, source, &block)
+	@rac = rac
+	@ch = ch
+	@source_dirs = source_dirs
+	@target_dir = target_dir
+	# target should be a string (file extension)
+	@target = target.sub(/^\./, '')
+	@target_rx = /#{Regexp.escape(target)}$/o
+	# source should be a string (file extension)
+	@source = source.sub(/^\./, '')
+	@esc_target_dir = Regexp.escape(target_dir)
+	@block = block
+    end
+    def call(name)
+	self[name]
+    end
+    def [](name)
+	#puts "rule for #{name} ?"
+	if name =~ /^#@esc_target_dir\//o && name =~ @target_rx
+	    #puts "  matches"
+	    fn = File.basename(name)
+	    src_fn = fn.sub_ext(@source)
+	    #puts "  source filename #{src_fn}"
+	    src = nil
+	    @source_dirs.each { |d|
+		path = File.join(d, src_fn)
+		#puts "  #{path} exist?"
+		(src = path) && break if test(?e, path)
+	    }
+	    if src
+		[@rac.file(:__caller__ => @ch, name => src, &@block)]
+	    else
+		nil
+	    end
+	else
+	    nil
+	end
+    end
+    def define_hook
+	@rac.resolve_hooks << self
+    end
+    def each_target &block
+	@rac.cx.sys["#@target_dir/*"].each { |entry|
+	    yield entry if entry =~ @target_rx
+	}
+    end
+    def candidates
+	sources.map { |src|
+	    File.join(@target_dir, File.basename(src).sub_ext(@target))
+	}
+    end
+    def sources
+	# TODO: returning a file list would be more efficient
+	cl = []
+	@source_dirs.each { |dir|
+	    cl.concat(@rac.cx.sys["#{dir}/*.#@source"])
+	}
+	cl
+    end
+end # class Rant::Generators::DirectedRule

data/lib/rant/import/package.rb

@@ -0,0 +1,258 @@
+
+require 'rant/rantlib'
+
+class Rant::Generators::Package
+
+    class << self
+	def rant_generate(app, ch, args, &block)
+	    if !args || args.empty?
+		self.new(:app => app, :__caller__ => ch, &block)
+	    elsif args.size == 1
+		pkg_name = case args.first
+		when String: args.first
+		when Symbol: args.first.to_s
+		else
+		    app.abort("Package takes only one additional " +
+			"argument, which should be a string or symbol.")
+		end
+		self.new(:app => app, :__caller__ => ch,
+		    :name => pkg_name, &block)
+	    else
+		app.abort(app.pos_text(file, ln),
+		    "Package takes only one additional argument, " +
+		    "which should be a string or symbol.")
+	    end
+	end
+    end
+
+    # A hash containing all package information.
+    attr_reader :data
+    # Directory where packages go to. Defaults to "pkg".
+    attr_accessor :pkg_dir
+
+    def initialize(opts = {})
+	@rac = opts[:app] || Rant.rantapp
+	@pkg_dir = "pkg"
+	@pkg_dir_task = nil
+	@dist_dir_task = nil
+	@tar_task = nil
+	@zip_task = nil
+	@package_task = nil
+	name = opts[:name]
+	@ch = opts[:__caller__] || Rant::Lib.parse_caller_elem(caller[0])
+	unless name
+	    # TODO: pos_text
+	    @rac.warn_msg(@rac.pos_text(@ch[:file], @ch[:ln]),
+		"No package name given, using directory name.")
+	    # use directory name as project name
+	    name = File.split(Dir.pwd)[1]
+	    # reset name if it contains a slash or a backslash
+	    name = nil if name =~ /\/|\\/
+	end
+	@data = { "name" => name }
+
+	yield self if block_given?
+    end
+
+    def name
+	@data["name"]
+    end
+
+    def version
+	@data["version"]
+    end
+
+    def version=(str)
+	unless String === str
+	    @rac.abort_at(@ch, "version has to be a String")
+	end
+	@data["version"] = str
+    end
+
+    def files
+	@data["files"]
+    end
+
+    def files=(list)
+	unless Array === list || ::Rant::FileList === List
+	    if list.respond_to? :to_ary
+		list = list.to_ary
+	    else
+		@rac.abort_at(@ch,
+		    "files must be an Array or FileList")
+	    end
+	end
+	@data["files"] = list
+    end
+
+    def validate_attrs(pkg_type = :general)
+	%w(name files).each { |a|
+	    pkg_requires_attr a
+	}
+    end
+    private :validate_attrs
+
+    def pkg_requires_attr(attr_name)
+	unless @data[attr_name]
+	    @rac.abort("Packaged defined: " +
+		@rac.pos_text(@ch[:file], @ch[:ln]),
+		"`#{attr_name}' attribute required")
+	end
+    end
+
+    def pkg_dir_task
+	return if @pkg_dir_task
+	if @dist_dir_task
+	    # not ideal but should work: If only the gem task will
+	    # be run, dist dir creation wouldn't be necessary
+	    return @pkg_dir_task = @dist_dir_task
+	end
+	@pkg_dir_task = @rac.gen(
+	    ::Rant::Generators::Directory, @pkg_dir)
+    end
+
+    def dist_dir_task
+	return if @dist_dir_task
+	pkg_name = pkg_dist_dir
+	dist_dir = pkg_dist_dir
+	@dist_dir_task = @rac.gen(Rant::Generators::Directory,
+		dist_dir => files) { |t|
+	    # ensure to create new and empty destination directory
+	    if Dir.entries(dist_dir).size > 2	# "." and ".."
+		@rac.sys.rm_rf(dist_dir)
+		@rac.sys.mkdir(dist_dir)
+	    end
+	    # evaluate directory structure first
+	    dirs = []
+	    fl = []
+	    files.each { |e|
+		if test(?d, e)
+		    dirs << e unless dirs.include? e
+		else	# assuming e is a file
+		    fl << e
+		    dir = File.dirname(e)
+		    dirs << dir unless dir == "." || dirs.include?(dir)
+		end
+	    }
+	    # create directory structure
+	    dirs.each { |dir|
+		dest = File.join(dist_dir, dir)
+		@rac.sys.mkpath(dest) unless test(?d, dest)
+	    }
+	    # link or copy files
+	    fl.each { |f|
+		dest = File.join(dist_dir, f)
+		@rac.sys.safe_ln(f, dest)
+	    }
+	}
+    end
+
+    def tar_task(tname = :tar)
+	validate_attrs
+	# Create tar task first to ensure that a pending description
+	# is used for the tar task and not for the dist dir task.
+	pkg_name = tar_pkg_path
+	pkg_files = files
+	if tname
+	    # shortcut task
+	    @rac.task({:__caller__ => @ch, tname => pkg_name})
+	end
+	# actual tar-creating task
+	@tar_task = @rac.file(:__caller__ => @ch,
+		pkg_name => [pkg_dist_dir] + pkg_files) { |t|
+	    @rac.sys.cd(@pkg_dir) {
+		@rac.sys %W(tar zcf #{tar_pkg_name} #{pkg_base_name})
+	    }
+	}
+	dist_dir_task
+    end
+
+    def zip_task(tname = :zip)
+	validate_attrs
+	# Create zip task first to ensure that a pending description
+	# is used for the zip task and not for the dist dir task.
+	pkg_name = zip_pkg_path
+	pkg_files = files
+	if tname
+	    # shortcut task
+	    @rac.task({:__caller__ => @ch, tname => pkg_name})
+	end
+	# actual zip-creating task
+	@zip_task = @rac.file(:__caller__ => @ch,
+		pkg_name => [pkg_dist_dir] + pkg_files) { |t|
+	    @rac.sys.cd(@pkg_dir) {
+		# zip options:
+		#   y: store symlinks instead of referenced files
+		#   r: recurse into directories
+		#   q: quiet operation
+		@rac.sys %W(zip -yqr #{zip_pkg_name} #{pkg_base_name})
+	    }
+	}
+	dist_dir_task
+    end
+
+    # Create a task which runs gem/zip/tar tasks.
+    def package_task(tname = :package)
+	def_tasks = [@tar_task, @zip_task].compact
+	if def_tasks.empty?
+	    # take description for overall package task
+	    pdesc = @rac.pop_desc
+	    unless def_available_tasks
+		@rac.desc pdesc
+		@rac.warn_msg("No tools for packaging available (tar, zip):",
+		    "Can't generate task `#{tname}'.")
+		return
+	    end
+	    @rac.desc pdesc
+	end
+	pre = []
+	pre << tar_pkg_path if @tar_task
+	pre << zip_pkg_path if @zip_task
+	pre << gem_pkg_path if @gem_task
+	@rac.task(:__caller__ => @ch, tname => pre)
+    end
+
+    # Returns true if at least one task was defined.
+    def def_available_tasks
+	defined = false
+	if Rant::Env.have_tar?
+	    # we don't create shortcut tasks, hence nil as argument
+	    self.tar_task(nil)
+	    defined = true
+	end
+	if Rant::Env.have_zip?
+	    self.zip_task(nil)
+	    defined = true
+	end
+	defined
+    end
+
+    def pkg_base_name
+	unless name
+	    @rac.abort(@rac.pos_text(@ch[:file], @ch[:ln]),
+		"`name' required for packaging")
+	end
+	version ? "#{name}-#{version}" : name
+    end
+
+    def tar_pkg_name
+	pkg_base_name + ".tar.gz"
+    end
+
+    def tar_pkg_path
+	pkg_dist_dir + ".tar.gz"
+    end
+
+    def zip_pkg_name
+	pkg_base_name + ".zip"
+    end
+
+    def zip_pkg_path
+	pkg_dist_dir + ".zip"
+    end
+
+    def pkg_dist_dir
+	@pkg_dir ? File.join(@pkg_dir, pkg_base_name) : pkg_base_name
+    end
+
+end	# class Rant::Generators::Package