decode 0.13.0 → 0.15.2

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.
@@ -39,24 +45,52 @@ module Decode
 				['.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.
+			# @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/module.rb

@@ -42,6 +42,12 @@ module Decode
 				
 				# The long form is the same as the short form.
 				alias long_form short_form
+				
+				# The fully qualified name of the class.
+				# e.g. `module ::Barnyard::Dog`.
+				def qualified_form
+					"module #{self.qualified_name}"
+				end
 			end
 		end
 	end

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

@@ -25,6 +25,37 @@ module Decode
 		module Ruby
 			# An Ruby-specific reference which can be resolved to zero or more definitions.
 			class Reference < Language::Reference
+				def self.from_const(node, language)
+					lexical_path = append_const(node)
+					
+					return self.new(node.location.expression.source, language, lexical_path)
+				end
+				
+				def self.append_const(node, path = [])
+					parent, name = node.children
+					
+					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
+				
 				def split(text)
 					text.scan(/(::|\.|#|:)?([^:.#]+)/)
 				end

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

@@ -40,7 +40,7 @@ module Decode
 				end
 				
 				# The source code trailing the comments.
-				# @return [String | nil]
+				# @returns [String | nil]
 				def code
 					@expression.source
 				end

data/lib/decode/scope.rb

@@ -23,10 +23,13 @@ require_relative 'definition'
 module Decode
 	# An abstract namespace for nesting definitions.
 	class Scope < Definition
+		# @returns [String] The name of the scope.
 		def short_form
 			@name
 		end
 		
+		# Scopes are always containers.
+		# @returns [Boolean] Always `true`.
 		def container?
 			true
 		end

data/lib/decode/segment.rb

@@ -35,15 +35,15 @@ module Decode
 		end
 		
 		# The preceeding comments.
-		# @attr [Array(String)]
+		# @attribute [Array(String)]
 		attr :comments
 		
 		# The language of the code attached to this segment.
-		# @attr [Language]
+		# @attribute [Language::Generic]
 		attr :language
 		
 		# An interface for accsssing the documentation of the definition.
-		# @return [Documentation | nil] A `Documentation` if this definition has comments.
+		# @returns [Documentation | nil] A {Documentation} instance if this definition has comments.
 		def documentation
 			if @comments&.any?
 				@documentation ||= Documentation.new(@comments, @language)
@@ -51,7 +51,7 @@ module Decode
 		end
 		
 		# The source code trailing the comments.
-		# @return [String | nil]
+		# @returns [String | nil]
 		def code
 		end
 	end

data/lib/decode/source.rb

@@ -21,34 +21,50 @@
 require_relative 'language'
 
 module Decode
+	# Represents a source file in a specific language.
 	class Source
 		def initialize(path, language)
 			@path = path
+			@buffer = nil
 			@language = language
 		end
 		
+		# The path of the source file.
+		# @attribute [String] A file-system path.
 		attr :path
 		
+		# The language of the source file.
+		# @attribute [Language::Generic]
 		attr :language
 		
-		def open(&block)
-			File.open(@path, &block)
+		# Read the source file into an internal buffer/cache.
+		# @returns [String]
+		def read
+			@buffer ||= File.read(@path).freeze
 		end
 		
+		# Open the source file and read all definitions.
+		# @yields {|definition| ...} All definitions from the source file.
+		# 	@parameter definition [Definition]
+		# @returns [Enumerator(Definition)] If no block given.
 		def definitions(&block)
 			return to_enum(:definitions) unless block_given?
 			
-			self.open do |file|
-				@language.definitions_for(file, &block)
-			end
+			@language.definitions_for(self.read, &block)
 		end
 		
+		# Open the source file and read all segments.
+		# @yields {|segment| ...} All segments from the source file.
+		# 	@parameter segment [Segment]
+		# @returns [Enumerator(Segment)] If no block given.
 		def segments(&block)
 			return to_enum(:segments) unless block_given?
 			
-			self.open do |file|
-				@language.segments_for(file, &block)
-			end
+			@language.segments_for(self.read, &block)
+		end
+		
+		def code(index = nil, relative_to: nil)
+			@language.code_for(self.read, index, relative_to: relative_to)
 		end
 	end
 end

data/lib/decode/syntax/link.rb

@@ -0,0 +1,44 @@
+# 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 'match'
+
+module Decode
+	module Syntax
+		class Link < Match
+			def initialize(range, definition)
+				@definition = definition
+				
+				super(range)
+			end
+			
+			attr :definition
+			
+			def apply(output, rewriter)
+				output << rewriter.link_to(
+					@definition,
+					rewriter.text_for(@range)
+				)
+				
+				return self.size
+			end
+		end
+	end
+end