decode 0.12.0 → 0.15.1

data/lib/decode/language/generic.rb

@@ -0,0 +1,51 @@
+# Copyright, 2020, by Samuel G. D. Williams. <http://www.codeotaku.com>
+# 
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+# 
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+# 
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+
+require_relative 'reference'
+
+module Decode
+	module Language
+		# The Ruby language.
+		class Generic
+			def initialize(name)
+				@name = name
+			end
+			
+			attr :name
+			
+			# Generate a generic reference.
+			def reference_for(identifier)
+				Reference.new(identifier, self)
+			end
+			
+			# Parse the input yielding definitions.
+			# @block {|definition| ... }
+			# @yield definition [Definition]
+			def definitions_for(input, &block)
+			end
+			
+			# Parse the input yielding interleaved comments and code segments.
+			# @block {|segment| ... }
+			# @yield segment [Segment]
+			def segments_for(input, &block)
+			end
+		end
+	end
+end

data/lib/decode/language/reference.rb

@@ -0,0 +1,108 @@
+# Copyright, 2020, by Samuel G. D. Williams. <http://www.codeotaku.com>
+# 
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+# 
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+# 
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+
+module Decode
+	module Language
+		# An reference which can be resolved to zero or more definitions.
+		class Reference
+			# Initialize the reference.
+			# @parameter identifier [String] The identifier part of the reference.
+			def initialize(identifier, language, lexical_path = nil)
+				@identifier = identifier
+				@language = language
+				
+				@lexical_path = lexical_path
+				@path = nil
+			end
+			
+			def to_s
+				"{#{self.language} #{self.identifier}}"
+			end
+			
+			def inspect
+				"\#<#{self.class} {#{self.identifier}}>"
+			end
+			
+			# The identifier part of the reference.
+			# @attribute [String]
+			attr :identifier
+			
+			# The language associated with this reference.
+			# @attribute [Language::Generic]
+			attr :language
+			
+			# Whether the reference starts at the base of the lexical tree.
+			def absolute?
+				!self.relative?
+			end
+			
+			def relative?
+				prefix, name = self.lexical_path.first
+				
+				return prefix.nil?
+			end
+			
+			def split(identifier)
+				identifier.scan(/(\W+)?(\w+)/)
+			end
+			
+			def lexical_path
+				@lexical_path ||= self.split(@identifier)
+			end
+			
+			def priority(definition, prefix)
+				if prefix.nil?
+					return 1
+				elsif definition.start_with?(prefix)
+					return 0
+				else
+					return 2
+				end
+			end
+			
+			def best(definitions)
+				prefix, name = lexical_path.last
+				
+				first = nil
+				without_prefix = nil
+				
+				definitions.each do |definition|
+					first ||= definition
+					
+					next unless definition.language == @language
+					
+					if prefix.nil?
+						without_prefix ||= definition
+					elsif definition.start_with?(prefix)
+						return definition
+					end
+				end
+				
+				return without_prefix || first
+			end
+			
+			# The lexical path of the reference.
+			# @returns [Array(String)]
+			def path
+				@path ||= self.lexical_path.map{|_, name| name.to_sym}
+			end
+		end
+	end
+end

data/lib/decode/language/ruby.rb

@@ -20,10 +20,16 @@
 
 require_relative 'ruby/reference'
 require_relative 'ruby/parser'
+require_relative 'ruby/code'
+
+require_relative '../comment/tags'
+require_relative '../comment/parameter'
+require_relative '../comment/yields'
+require_relative '../comment/returns'
 
 module Decode
 	module Language
-		# The Ruby language.
+		# An interface for extracting information from Ruby source code.
 		module Ruby
 			# The canoical name of the language for use in output formatting.
 			# e.g. source code highlighting.
@@ -31,24 +37,60 @@ module Decode
 				"ruby"
 			end
 			
+			def self.names
+				[self.name]
+			end
+			
+			def self.extensions
+				['.rb', '.ru']
+			end
+			
+			TAGS = Comment::Tags.build do |tags|
+				tags['attribute'] = Comment::Attribute
+				tags['parameter'] = Comment::Parameter
+				tags['yields'] = Comment::Yields
+				tags['returns'] = Comment::Returns
+				tags['raises'] = Comment::Raises
+				tags['throws'] = Comment::Throws
+				
+				tags['reentrant'] = Comment::Pragma
+				tags['deprecated'] = Comment::Pragma
+				tags['blocking'] = Comment::Pragma
+				tags['asynchronous'] = Comment::Pragma
+			end
+			
+			def self.tags
+				TAGS
+			end
+			
 			# Generate a language-specific reference.
-			def self.reference(value)
-				Reference.new(value)
+			# @parameter identifier [String] A valid identifier.
+			def self.reference_for(identifier)
+				Reference.new(identifier, self)
 			end
 			
 			# Parse the input yielding definitions.
-			# @block `{|definition| ...}`
-			# @yield definition [Definition]
+			# @parameter input [File] The input file which contains the source code.
+			# @yields {|definition| ...} Receives the definitions extracted from the source code.
+			# 	@parameter definition [Definition] The source code definition including methods, classes, etc.
+			# @returns [Enumerator(Segment)] If no block given.
 			def self.definitions_for(input, &block)
 				Parser.new.definitions_for(input, &block)
 			end
 			
-			# Parse the input yielding interleaved comments and code segments.
-			# @block `{|segment| ...}`
-			# @yield segment [Segment]
+			# Parse the input yielding segments.
+			# Segments are constructed from a block of top level comments followed by a block of code.
+			# @parameter input [File] The input file which contains the source code.
+			# @yields {|segment| ...}
+			# 	@parameter segment [Segment]
+			# @returns [Enumerator(Segment)] If no block given.
 			def self.segments_for(input, &block)
 				Parser.new.segments_for(input, &block)
 			end
+			
+			def self.code_for(text, index, relative_to: nil)
+				Code.new(text, index, relative_to: relative_to, language: self)
+			end
 		end
 	end
 end

data/lib/decode/language/ruby/block.rb

@@ -58,7 +58,7 @@ module Decode
 				
 				def convert(kind)
 					case kind
-					when :attr
+					when :attribute
 						Attribute.new(@node, @name,
 							comments: @comments, parent: @parent, language: @language
 						)

data/lib/decode/language/ruby/class.rb

@@ -62,13 +62,13 @@ module Decode
 			# A Ruby-specific singleton class.
 			class Singleton < Definition
 				# A singleton class is a container for other definitions.
-				# @return [Boolean]
+				# @returns [Boolean]
 				def container?
 					true
 				end
 				
 				# Typically, a singleton class does not contain other definitions.
-				# @return [Boolean]
+				# @returns [Boolean]
 				def nested?
 					false
 				end

data/lib/decode/language/ruby/code.rb

@@ -0,0 +1,85 @@
+# Copyright, 2020, by Samuel G. D. Williams. <http://www.codeotaku.com>
+# 
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+# 
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+# 
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+
+require_relative 'definition'
+require_relative '../../syntax/link'
+
+require 'parser/current'
+
+module Decode
+	module Language
+		module Ruby
+			# A Ruby-specific block of code.
+			class Code
+				def initialize(text, index, relative_to: nil, language: relative_to&.language)
+					@text = text
+					@root = ::Parser::CurrentRuby.parse(text)
+					@index = index
+					@relative_to = relative_to
+					@language = language
+				end
+				
+				attr :text
+				
+				attr :language
+				
+				def extract(into = [])
+					if @index
+						traverse(@root, into)
+					end
+					
+					return into
+				end
+				
+				private
+				
+				def traverse(node, into)
+					case node&.type
+					when :send
+						if reference = Reference.from_const(node, @language)
+							if definition = @index.lookup(reference, relative_to: @relative_to)
+								expression = node.location.selector
+								range = expression.begin_pos...expression.end_pos
+								into << Syntax::Link.new(range, definition)
+							end
+						end
+						
+						# Extract constants from arguments:
+						children = node.children[2..-1].each do |node|
+							traverse(node, into)
+						end
+					when :const
+						if reference = Reference.from_const(node, @language)
+							if definition = @index.lookup(reference, relative_to: @relative_to)
+								expression = node.location.name
+								range = expression.begin_pos...expression.end_pos
+								into << Syntax::Link.new(range, definition)
+							end
+						end
+					when :begin
+						node.children.each do |child|
+							traverse(child, into)
+						end
+					end
+				end
+			end
+		end
+	end
+end

data/lib/decode/language/ruby/definition.rb

@@ -44,7 +44,7 @@ module Decode
 				end
 				
 				# The source code associated with the definition.
-				# @return [String]
+				# @returns [String]
 				def text
 					expression = @node.location.expression
 					lines = expression.source.lines

data/lib/decode/language/ruby/method.rb

@@ -52,9 +52,15 @@ module Decode
 					end
 				end
 				
+				# The fully qualified name of the block.
+				# e.g. `::Barnyard#foo`.
+				def qualified_form
+					self.qualified_name
+				end
+				
 				def convert(kind)
 					case kind
-					when :attr
+					when :attribute
 						Attribute.new(@node, @name,
 							comments: @comments, parent: @parent, language: @language
 						)

data/lib/decode/language/ruby/parser.rb

@@ -40,7 +40,7 @@ module Decode
 			class Parser
 				# Extract definitions from the given input file.
 				def definitions_for(input, &block)
-					top, comments = ::Parser::CurrentRuby.parse_with_comments(input.read)
+					top, comments = ::Parser::CurrentRuby.parse_with_comments(input)
 					
 					if top
 						walk_definitions(top, comments, &block)
@@ -207,7 +207,7 @@ module Decode
 				end
 				
 				KIND_ATTRIBUTE = /\A
-					(@(?<kind>attr)\s+(?<value>.*?))|
+					(@(?<kind>attribute)\s+(?<value>.*?))|
 					(@define\s+(?<kind>)\s+(?<value>.*?))
 				\Z/x
 				
@@ -241,7 +241,7 @@ module Decode
 				
 				# Extract segments from the given input file.
 				def segments_for(input, &block)
-					top, comments = ::Parser::CurrentRuby.parse_with_comments(input.read)
+					top, comments = ::Parser::CurrentRuby.parse_with_comments(input)
 					
 					# We delete any leading comments:
 					line = 0
@@ -279,6 +279,14 @@ module Decode
 						end
 						
 						yield segment if segment
+					else
+						# One top level segment:
+						segment = Segment.new(
+							extract_comments_for(node, comments),
+							Ruby,	node
+						)
+						
+						yield segment
 					end
 				end
 			end

data/lib/decode/language/ruby/reference.rb

@@ -18,47 +18,46 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 # THE SOFTWARE.
 
+require_relative '../reference'
+
 module Decode
 	module Language
 		module Ruby
 			# An Ruby-specific reference which can be resolved to zero or more definitions.
-			class Reference
-				# Initialize the reference.
-				# @param text [String] The text text of the reference.
-				def initialize(text)
-					@text = text
+			class Reference < Language::Reference
+				def self.from_const(node, language)
+					lexical_path = append_const(node)
 					
-					@lexical_path = nil
-					@path = nil
-				end
-				
-				def language
-					Ruby
-				end
-				
-				attr :text
-				
-				# Whether the reference starts at the base of the lexical tree.
-				def absolute?
-					@text.start_with?('::')
+					return self.new(node.location.expression.source, language, lexical_path)
 				end
 				
-				def lexical_path
-					@lexical_path ||= @text.scan(/(::|\.|#|:)?([^:.#]+)/)
-				end
-				
-				def best(definitions)
-					prefix, name = lexical_path.last
+				def self.append_const(node, path = [])
+					parent, name = node.children
 					
-					definitions.select do |definition|
-						prefix.nil? || definition.start_with?(prefix)
+					if parent and parent.type != :cbase
+						append_const(parent, path)
 					end
+					
+					case node.type
+					when :const
+						if parent && parent.type != :cbase
+							path << ['::', name]
+						else
+							path << [nil, name]
+						end
+					when :send
+						path << ['#', name]
+					when :cbase
+						# Ignore.
+					else
+						raise ArgumentError, "Could not determine reference for #{node}!"
+					end
+					
+					return path
 				end
 				
-				# The lexical path of the reference.
-				# @return [Array(String)]
-				def path
-					@path ||= self.lexical_path.map{|_, name| name.to_sym}
+				def split(text)
+					text.scan(/(::|\.|#|:)?([^:.#]+)/)
 				end
 			end
 		end