rdx 0.9.0.pre

data/lib/rdx/ruby_lex.rb

@@ -0,0 +1,324 @@
+
+module RDX
+	
+	require 'rdoc'
+	require 'rdoc/ruby_token'
+	require 'rdoc/ruby_lex'
+	
+	#
+	# Interface to the +RDoc::RubyLex+ tokenizer and parser.
+	#
+	module RubyLex
+		
+		extend self
+		
+	# :stopdoc:
+		
+		# Matches a Ruby inline comment
+		RE_CMT    = /#.*+\n/
+		
+		# Matches a Ruby inline comment optionally preceded by spaces
+		RE_SP_CMT = /[^\S\n]*+#{RE_CMT.source}/o
+		
+		# Matches trailing spaces of a line
+		RE_SP_NL  = /[^\S\n]*+\n/
+		
+		TkCOMMENT = RDoc::Parser::Ruby::TkCOMMENT
+		TkSPACE   = RDoc::Parser::Ruby::TkSPACE
+		TkNL      = RDoc::Parser::Ruby::TkNL
+		ERROR     = RDoc::RubyLex::Error
+		
+		# +tab_width+ does not matter in evaluation...
+		RDOC_OPTIONS = RDoc::Options.new
+		
+	# :startdoc:
+		
+		# Raises a +ParseError+ from the given exception and internal line number.
+		def raise_parse_error err, line_no=nil
+			msg = "Invalid ruby code"
+			error = ParseError.new msg
+			if err.is_a?(ERROR)
+				msg << ":\n" << err.message
+				error.line_no = line_no
+			end
+			raise error # this caller: assuming not debugging RDoc::RubyLex itself
+		end
+		private :raise_parse_error
+		
+		# Generates a new +RDoc::RubyLex+ with the given _ruby_ as input.
+		def new_rdoc_scanner ruby
+			scanner = RDoc::RubyLex.new ruby, RDOC_OPTIONS
+			scanner.exception_on_syntax_error = true
+			scanner
+		end
+		private :new_rdoc_scanner
+		
+		# Through <tt>RDoc::RubyLex.tokenize</tt> tokenizes the _ruby_ string and
+		# retunrs an array of +RDoc::RubyToken+.
+		# These are processed with #adjust_tokens if _adjust_tokens_ is +true+ (default).
+		# May raise a +ParseError+ if the input is invalid enough.
+		def tokenize ruby, adjust_tokens=true
+			ruby = ruby.to_str
+			scanner = new_rdoc_scanner ruby
+			tokens = []
+			begin
+				while token = scanner.token do
+					tokens << token
+				end
+			rescue => err
+				raise_parse_error err, scanner.line_no
+			end
+			tokens = adjust_tokens tokens if adjust_tokens
+			tokens.each{ |tk| yield tk } if block_given?
+			return tokens
+		end
+		private :tokenize
+		
+		# The comments also include the trailing newline and any comment on
+		# successives lines until a blank one.
+		def adjust_tokens orig_tokens
+			tokens = []
+			current_tkcomment = comment_on_current_line = nil
+			space_tokens = []
+			orig_tokens.each do |tk|
+				if tk.instance_of?(TkCOMMENT) # Don't consider embedded documents
+					comment_on_current_line = true
+					next tokens.push(current_tkcomment = tk) unless current_tkcomment
+					current_tkcomment.text << space_tokens.map(&:text).join('') << tk.text
+					space_tokens.clear
+				elsif tk.is_a?(TkSPACE)
+					next tokens << tk unless current_tkcomment
+					# comment_on_current_line is false
+					space_tokens << tk
+				elsif tk.is_a?(TkNL) # there is for sure at the end of the tokens
+					next tokens << tk unless current_tkcomment
+					if comment_on_current_line
+						current_tkcomment.text << tk.text
+						comment_on_current_line = false
+					else
+						tokens.concat space_tokens
+						space_tokens.clear
+						current_tkcomment = nil
+					end
+				else
+					tokens << tk
+					current_tkcomment = nil
+				end
+			end
+			return tokens
+		end
+		private :adjust_tokens
+		
+		#
+		# Doesn't interpret _string_ as ruby code and extracts
+		# potential ruby comments.
+		# The result is an array <tt>[ [comment,line_no],... ]</tt>.
+		# 
+		#   RDX::RubyLex.extract_potential_comments <<EOS
+		#   This is not ruby :-( # potential comment
+		#   # ...continuing... #
+		#   other text
+		#   # another comment
+		#   EOS
+		#   # => [
+		#   #   ["# potential comment\n# ...continuing... #\n", 1],
+		#   #   ["# another comment\n", 4]
+		#   # ]
+		# 
+		# If a block is supplied, it is yielded those results.
+		# 
+		# This method never raises a +ParseError+.
+		#
+		def extract_potential_comments string
+			string = string.to_str
+			string = string.dup << "\n" unless string.end_with?("\n")
+			comments = []
+			string.scan /#{RE_CMT}#{RE_SP_CMT}*+/o do |comment|
+				md = Regexp.last_match
+				l_no = md.pre_match.count("\n") + 1
+				comments << [comment,l_no]
+			end
+			comments.each{ |(comment,line_no)| yield comment, line_no } if block_given?
+			return comments
+		end
+		
+		#
+		# Extracts the comments in _ruby_ string and returns an
+		# array of arrays <tt>[ [comment,line_no],... ]</tt>.
+		# The comments also include the trailing newline and any comment
+		# on successives lines until a blank one.
+		# 
+		#   RDX::RubyLex.extract_comments <<EOS
+		#   # This is Ruby!
+		#   
+		#   # This method simply returns the +Fixnum+ 2.
+		#   def return_two
+		#     2 # of course
+		#     # it returns two
+		#   end
+		#   EOS
+		#   # => [
+		#   #   ["# This is Ruby!\n", 1],
+		#   #   ["# This method simply returns the +Fixnum+ 2.\n", 3],
+		#   #   ["# of course\n  # it returns two\n", 5]
+		#   # ]
+		# 
+		# If a block is given, it is yielded those results.
+		# 
+		# May raise a +ParseError+ if the input is invalid enough.
+		#
+		def extract_comments ruby
+			comments = []
+			tokenize ruby do |tk|
+				next unless tk.instance_of?(TkCOMMENT) # Don't capture embedded documents
+				comments << [tk.text,tk.line_no]
+			end
+			comments.each{ |(comment,line_no)| yield comment, line_no } if block_given?
+			return comments
+		end
+		
+		# Subdivides the _ruby_ string into toplevel statements and returns an array
+		# <tt>[ [statement,line_no] ]</tt>.
+		# These are processed with #adjust_statements if _adjust_statements_ is +true+ (default).
+		# May raise a +ParseError+ if the input invalid enough.
+		def statementize ruby, adjust_statements=true
+			ruby = ruby.to_str
+			statements = []
+			scanner = new_rdoc_scanner ruby
+			begin
+				scanner.each_top_level_statement do |stmnt,l_no|
+					statements << [stmnt,l_no]
+				end
+			rescue => err
+				raise_parse_error err, scanner.line_no
+			end
+			statements = adjust_statements statements if adjust_statements
+			statements.each{ |stmnt| yield stmnt } if block_given?
+			return statements
+		end
+		private :statementize
+		
+		# The statements also includes trailing comments until a blank line.
+		def adjust_statements orig_statements
+			statements = []
+			return statements if orig_statements.empty?
+			# The first statement is unchanged
+			statements.push(orig_statements.shift)
+			previous_statement = statements.first[0]
+			orig_statements.each do |stmnt,l_no|
+				if stmnt =~ /\A[^\S\n]*\./ # statement concatenation
+					previous_statement.concat stmnt
+					next
+				end
+				# For all the other statements move the leading spaces and comment to the previous statement
+				leading = stmnt.slice! /\A#{RE_SP_CMT}*+#{RE_SP_NL}*+/o
+				previous_statement.concat leading
+				l_no += leading.count("\n")
+				statements << [stmnt,l_no]
+				previous_statement = stmnt
+			end
+			return statements
+		end
+		private :adjust_statements
+		
+		#
+		# Collects all top-level statements for _ruby_ string into an array
+		# <tt>[ [statement,line_no], ... ]</tt>. Each statement also includes
+		# trailing comments until a blank line.
+		# 
+		#   RDX::RubyLex.extract_statements <<EOS
+		#   # beginning comment
+		#   statement_1 # => result_1
+		#   # other stuff...
+		#   statement_2
+		#   statement_3
+		#     # => result_3
+		#   
+		#   # new block
+		#   statement_4
+		#   # => result_4
+		#   EOS
+		#   # => [
+		#   #   ["# beginning comment\nstatement_1 # => result_1\n# other stuff...\n", 1],
+		#   #   ["statement_2\n", 4],
+		#   #   ["statement_3\n  # => result_3\n\n", 5],
+		#   #   ["# new block\nstatement_4\n# => result_4\n", 8]
+		#   # ]
+		# 
+		# If a block is given, it is yielded those results.
+		# 
+		# May raise a +ParseError+ if the input is invalid enough.
+		#
+		def extract_statements ruby
+			statements = statementize ruby
+			statements.delete_if{ |stmnt,_| stmnt !~ /\S/ }
+			statements.each{ |(statement,line_no)| yield statement, line_no } if block_given?
+			return statements
+		end
+		
+		#
+		# Returns the first statement for _ruby_ code.
+		# Until it's found may raise a +ParseError+ if the input is invalid enough.
+		# 
+		#   RDX::RubyLex.extract_first_statement <<EOS
+		#   'A ' +
+		#   'string'
+		#   # statement ended succesfully!
+		#   0xqwerty: invalid input, but who cares now?
+		#   EOS
+		#   # => "'A ' +\n'string'\n# statement ended succesfully!\n"
+		#
+		def extract_first_statement ruby
+			ruby = ruby.to_str
+			scanner = new_rdoc_scanner ruby
+			begin
+				stmnt = scanner.each_top_level_statement{ |stmnt| break stmnt }
+			rescue => err
+				raise_parse_error err, scanner.line_no
+			end
+			while line = scanner.gets
+				break unless line =~ /\A#{RE_SP_CMT}/o
+				stmnt << line
+			end
+			stmnt
+		end
+		
+		#
+		# Tokenizes _ruby_statement_ and returns an array of arrays <tt>[ [comment,line_no],... ]</tt>.
+		# The last element will always contain the comment at the end of the statement (an empty
+		# String if there isn't); all the others are indeed at positions of incomplete statement.
+		#   RDX::RubyLex.extract_comments_from_statement <<EOS
+		#   class AClass
+		#     self # => AClass
+		#     # Right, but the statement isn't yet complete!
+		#   end
+		#   # => AClass # Now it's ok!
+		#   # other metadata...
+		#   EOS
+		#   # => [
+		#   #   ["# => AClass\n  # Right, but the statement isn't yet complete!\n", 2],
+		#   #   ["# => AClass # Now it's ok!\n# other metadata...\n", 5]
+		#   # ]
+		#   RDX::RubyLex.extract_comments_from_statement <<EOS
+		#   a_statement +
+		#   without_comment\n
+		#   EOS
+		#   # => [ ["",2] ]
+		#
+		def extract_comments_from_statement ruby_statement
+			ruby_statement = ruby_statement.to_str.rstrip
+			tokens = tokenize ruby_statement
+			comments = []
+			tokens.each do |tk|
+				next unless tk.instance_of?(TkCOMMENT) # Don't capture embedded documents
+				comments << [tk.text,tk.line_no]
+			end
+			last_tk = tokens.last
+			comments << ['',last_tk.line_no] unless last_tk.instance_of?(TkCOMMENT)
+			comments.each{ |(comment,line_no)| yield comment, line_no } if block_given?
+			return comments
+		end
+		
+	end
+	
+end

data/lib/rdx/runner.rb

@@ -0,0 +1,309 @@
+
+require 'rdx'
+
+require 'rdx/code_object'
+require 'rdx/reporter'
+
+module RDX
+	
+	#
+	# Coordinates all moving parts of RDX.
+	#
+	class Runner
+		
+	# :stopdoc:
+		
+		#
+		# Start and run RDX with the given _argv_
+		#
+		def self.run(argv)
+			new(argv).run
+		end
+		
+		# Is RDX running?
+		def self.active?
+			!current.nil?
+		end
+		
+		@current = nil
+		class << self
+			attr_reader :current
+			def current= runner
+				if runner && @current
+					raise Error, 'Only one instance of RDX is allowed to run'
+				end
+				@current = runner
+			end
+		end
+
+		ACTIONS = {
+			:initializing           => [],
+			:ready                  => [:run],
+			:documenting            => [:signal_start_parsing,
+				                          :signal_do_testing, :signal_start_generating],
+				:parsing              => [:signal_end_parsing, :signal_start_parsing_file,
+					                        :signal_found_comment],
+					:parsing_file       => [:signal_end_parsing_file, :signal_found_comment],
+				:testing              => [],
+				  :building           => [],
+					:running_pre_tests  => [],
+					:requiring_libs     => [],
+					:running_post_tests => [],
+				:generating           => [:signal_end_generating],
+			:reporting              => [],
+			:finished               => [],
+		}
+		
+		def check_action action
+			actions = ACTIONS[@status]
+			return if actions && actions.include?(action.to_sym)
+			raise Error, "action #{action} request in #{@status.to_s}"
+		end
+		private :check_action
+		
+		attr_reader :options
+		
+		attr_reader :reporter
+		
+		attr_reader :store
+		
+		def initialize(argv)
+			@status   = :initializing
+			setup_options(argv)
+			setup_reporter
+			setup_store
+			@status   = :ready
+		end
+		
+		def passed?
+			store.passed?
+		end
+		def self.passed?
+			active? && current.passed?
+		end
+		
+		def verbose
+			options.verbose
+		end
+		def debug
+			options.debug
+		end
+		
+		def puts *args # :nodoc:
+			reporter.puts *args
+		end
+		def print *args # :nodoc:
+			reporter.print *args
+		end
+		
+	private
+		
+		def setup_options(options)
+			options = Options.new(options) unless options.is_a?(Options)
+			@options = options
+		end
+		
+		def setup_reporter
+			@reporter = Reporter[options.reporter].new(self)
+		end
+		
+		def setup_store
+			rdx_file = File.expand_path('.rdx')
+			spec = Specification.load(rdx_file) || Specification.default
+			unless spec.original?
+				puts 'Conventions and/or directives changed according to the .rdx file'
+				@options.files.delete rdx_file # TODO: include in doc
+			end
+			@store = Store.new spec
+		end
+		
+		def run
+			check_action __method__
+			Runner.current = self
+			generator = Generator[options.generator].new
+			documenting_hook do
+				generator.generate(options.generator_options,options.files)
+			end
+			reporting_hook
+		rescue Exception => exc
+			exc.set_backtrace RDX.filter_backtrace(exc.backtrace)
+			raise exc
+		ensure
+			Runner.current = nil
+		end
+		public :run
+		
+		#
+		# === Singal and Hooks ===
+		# 
+		# Must be called elsewhere -> public -> checks @status
+		#
+		
+		def start_documenting_hook
+			puts
+			puts "This is RDX, version #{RDX::VERSION}"
+			puts
+			puts "Start documenting with #{options.generator}"
+			@status = :documenting
+		end
+		
+		def signal_start_parsing
+			check_action __method__
+			puts 'Parsing files...'
+			@status = :parsing
+		end
+		
+		def signal_start_parsing_file(filename)
+			check_action __method__
+			@status = :parsing_file
+		end
+		
+		def signal_end_parsing_file filename, success=true
+			check_action __method__
+			@status = :parsing
+		end
+		
+		def signal_end_parsing success=true, testing=success
+			check_action __method__
+			@status = :documenting
+			signal_do_testing if testing
+		end
+		
+		def signal_do_testing
+			check_action __method__
+			prev_status = @status
+			@status = :testing
+			tmpdir = Dir.mktmpdir ['rdx', Time.now.strftime("-%H%M")]
+			begin
+				Dir.chdir tmpdir do
+					build_tests_hook
+					handle_dry_run_option
+					run_tests_hook
+					dispose_store # clear bindings and run GC, so that tmpdir is empty and can be safely deleted
+				end
+			ensure
+				FileUtils.remove_entry tmpdir, !debug
+			end
+			puts "Tests finished!"
+			@status = prev_status
+		end
+		
+		def build_tests_hook
+			puts 'Building tests...'
+			@status = :building
+			store.build options.seed
+		end
+		
+		def run_tests_hook
+			puts
+			reporter.on_testing  do
+				reporter.puts "Running tests (seed=#{options.seed})", ''
+				run_pre_tests_hook
+				require_libs_hook
+				run_post_tests_hook
+			end
+		end
+		
+		def handle_dry_run_option
+			return unless options.dry_run
+			CodeObject::Runnable.class_eval do
+				def trace_execution(*); end
+				def trace_assertion conv_name=nil, frame=location
+					register Detection.new(conv_name,frame)
+				end
+			end
+		end
+		
+		def run_pre_tests_hook
+			@status = :running_pre_tests
+			reporter.run_pre_tests store.tests_before_require
+		end
+		
+		def require_libs_hook
+			@status = :requiring_libs
+			lib_dirs = options.lib_dirs.reverse
+			$LOAD_PATH.unshift(*lib_dirs)
+			libs = options.libs
+			reporter.require_libs do
+				libs.each do |file|
+					reporter.require_lib(file){ require file }
+				end
+			end
+		end
+		
+		def run_post_tests_hook
+			@status = :running_post_tests
+			reporter.run_post_tests store.tests_after_require
+		end
+		
+		def dispose_store
+			store.dispose_bindings
+			GC.start
+		end
+		
+		def signal_start_generating
+			check_action __method__
+			@status = :generating
+			puts "Generating documentation output..."
+		end
+		
+		def signal_end_generating success=true
+			check_action __method__
+			@status = :documenting
+		end
+		
+		def end_documenting_hook
+			puts "Documentation finished!"
+		end
+		
+		def reporting_hook
+			@status = :reporting
+			reporter.show_report
+		end
+		
+		# reset => :ready ???
+		
+		# Block hooks & signals
+		
+		def documenting_hook
+			reporter.on_documenting do
+				start_documenting_hook
+				yield
+				end_documenting_hook
+			end
+		end
+		
+		def signal_parsing
+			signal_start_parsing
+			result = yield
+			signal_end_parsing
+			result
+		end
+		
+		def signal_generating
+			unless options.doc_output
+				puts 'Generation of documentation output is disabled'
+				return
+			end
+			signal_start_generating
+			result = yield
+			signal_end_generating
+			result
+		end
+		
+		# Define these as public signals and also in RDX::Runner and RDX.
+		# This methods do nothing if RDX isn't running.
+		private_instance_methods(false)
+		.concat(public_instance_methods(false))
+		.grep(/^signal_/) do |name|
+			public name
+			define_singleton_method name do |*args,&blk|
+				current && current.public_send(name,*args,&blk)
+			end
+			RDX.define_singleton_method name do |*args,&blk|
+				Runner.public_send(name,*args,&blk)
+			end
+		end
+	end
+	
+end