decode 0.14.0 → 0.15.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3def34b952d9d52ecd46b00af1d0d6bf35c1e1356b73f0684044d374e23fcbf3
-  data.tar.gz: b95a502a185aedaa5f64c6cdaee5abd30ba0739df530cc1fa5a957b54328f261
+  metadata.gz: fef5bd0d089112f4e4897666683a8ecebb9306a9c4a1d454aa2cfef8a30daecf
+  data.tar.gz: cddb38a43954d3bd8ee2587ee66a2a7bd9ab207b33553dcc871b1d032fcde01e
 SHA512:
-  metadata.gz: ebb0306d62ce7feeff715b4fb1f2b622d21ab877285c678e8a83acb08f2183c83c4bc6cf3f2ec88743006142fa9f1c8f1094812bf2fde96d1e6d2ffcdb65c133
-  data.tar.gz: 79d583ef1946a0a94010fdd8b23cf2e36433e355eb7c6efb2f72bd949784b563d89e4693b73532e8fdc6cea3bef462dc6c74f484aff0cce95d289a675aebd731
+  metadata.gz: 2ffceab58980663e235b35dcf68575e4a6857a483b796fe9a6df8248d52df5c52810711f7a4d9ba249113c6bb5facfc36af5efab22482b8ab1dc52956503c18e
+  data.tar.gz: daf76f009f6bc36d3f7515f182fc8daf5aceec3fc74758cd11fcb67c3f5f0780cbd55cffc0b3786dbe058f95c1a3085a7442d7a09833797a1c625add875def1a

data/lib/decode/comment/attribute.rb

@@ -48,14 +48,6 @@ module Decode
 			# The type of the attribute.
 			# @attribute [String]
 			attr :type
-			
-			# The details associated with the tag.
-			# @attribute [String | Nil]
-			attr :details
-			
-			def text
-				text = super
-			end
 		end
 	end
 end

data/lib/decode/comment/node.rb

@@ -63,11 +63,11 @@ module Decode
 			end
 			
 			# Traverse the tags from this node using {each}.
-			# Invoke `descend.call` to traverse the children of the current node.
+			# Invoke `descend.call(child)` to recursively traverse the specified child.
 			#
-			# @block {|node, descend| descend.call}
-			# @yield node [Node] The current node which is being traversed.
-			# @yield descend [Proc | Nil] The recursive method for traversing children.
+			# @yields {|node, descend| descend.call}
+			# 	@parameter node [Node] The current node which is being traversed.
+			# 	@parameter descend [Proc | Nil] The recursive method for traversing children.
 			def traverse(&block)
 				descend = ->(node){
 					node.traverse(&block)

data/lib/decode/comment/parameter.rb

@@ -53,10 +53,6 @@ module Decode
 			# The type of the attribute.
 			# @attribute [String]
 			attr :type
-			
-			# The details associated with the tag.
-			# @attribute [String | Nil]
-			attr :details
 		end
 	end
 end

data/lib/decode/definition.rb

@@ -44,12 +44,15 @@ module Decode
 		
 		# The symbol name.
 		# e.g. `:Decode`.
+		# @attribute [Symbol]
 		attr :name
 		
-		# The parent symbol, defining lexical scope.
+		# The parent definition, defining lexical scope.
+		# @attribute [Definition | Nil]
 		attr :parent
 		
 		# The language the symbol is defined within.
+		# @attribute [Language::Generic]
 		attr :language
 		
 		# The comment lines which directly preceeded the definition.
@@ -74,6 +77,8 @@ module Decode
 			"::#{@name}"
 		end
 		
+		# Does the definition name match the specified prefix?
+		# @returns [Boolean]
 		def start_with?(prefix)
 			self.nested_name.start_with?(prefix)
 		end
@@ -83,7 +88,8 @@ module Decode
 			raise ArgumentError, "Unable to convert #{self} into #{kind}!"
 		end
 		
-		# The lexical scope which is an array of lexical {Key} instances as generated by {key}.
+		# The lexical scope as an array of names.
+		# e.g. `[:Decode, :Definition]`
 		# @returns [Array]
 		def path
 			if @path

data/lib/decode/documentation.rb

@@ -49,7 +49,7 @@ module Decode
 		attr :comments
 		
 		# The language in which the documentation was extracted from.
-		# @attribute [Language]
+		# @attribute [Language::Generic]
 		attr :language
 	end
 end

data/lib/decode/language/reference.rb

@@ -24,11 +24,11 @@ module Decode
 		class Reference
 			# Initialize the reference.
 			# @parameter identifier [String] The identifier part of the reference.
-			def initialize(identifier, language)
+			def initialize(identifier, language, lexical_path = nil)
 				@identifier = identifier
 				@language = language
 				
-				@lexical_path = nil
+				@lexical_path = lexical_path
 				@path = nil
 			end
 			
@@ -45,6 +45,7 @@ module Decode
 			attr :identifier
 			
 			# The language associated with this reference.
+			# @attribute [Language::Generic]
 			attr :language
 			
 			# Whether the reference starts at the base of the lexical tree.
@@ -66,14 +67,35 @@ module Decode
 				@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
 				
-				definitions.select do |definition|
-					definition.language == @language && (
-						prefix.nil? || definition.start_with?(prefix)
-					)
+				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.

data/lib/decode/language/ruby.rb

@@ -20,6 +20,7 @@
 
 require_relative 'ruby/reference'
 require_relative 'ruby/parser'
+require_relative 'ruby/code'
 
 require_relative '../comment/tags'
 require_relative '../comment/parameter'
@@ -86,6 +87,10 @@ module Decode
 			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/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

@@ -51,10 +51,10 @@ module Decode
 					if lines.count == 1
 						return lines.first
 					else
-						indentation = expression.source_line[/\A\s+/]
-						
-						# Remove all the indentation:
-						lines.each{|line| line.sub!(indentation, '')}
+						if indentation = expression.source_line[/\A\s+/]
+							# Remove all the indentation:
+							lines.each{|line| line.sub!(indentation, '')}
+						end
 						
 						return lines.join
 					end

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)
@@ -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

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/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

@@ -39,7 +39,7 @@ module Decode
 		attr :comments
 		
 		# The language of the code attached to this segment.
-		# @attribute [Language]
+		# @attribute [Language::Generic]
 		attr :language
 		
 		# An interface for accsssing the documentation of the definition.

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

data/lib/decode/syntax/match.rb

@@ -0,0 +1,53 @@
+# 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 Syntax
+		class Match
+			def initialize(range)
+				@range = range
+			end
+			
+			attr :range
+			
+			def apply(source)
+				return source[range]
+			end
+			
+			def <=> other
+				@range.min <=> other.range.min
+			end
+			
+			def offset
+				@range.min
+			end
+			
+			def size
+				@range.size
+			end
+			
+			def apply(output, rewriter)
+				output << rewriter.text_for(@range)
+				
+				return self.size
+			end
+		end
+	end
+end

data/lib/decode/syntax/rewriter.rb

@@ -0,0 +1,70 @@
+# 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 Syntax
+		class Rewriter
+			def initialize(text)
+				@text = text
+				@matches = []
+			end
+			
+			attr :text
+			
+			attr :matches
+			
+			def << match
+				@matches << match
+			end
+			
+			# Returns a chunk of raw text with no formatting.
+			def text_for(range)
+				@text[range]
+			end
+			
+			def apply(output = [])
+				offset = 0
+				
+				@matches.sort.each do |match|
+					if match.offset > offset
+						output << text_for(offset...match.offset)
+						
+						offset = match.offset
+					elsif match.offset < offset
+						# Match intersects last output buffer.
+						next
+					end
+					
+					offset += match.apply(output, self)
+				end
+				
+				if offset < @text.size
+					output << text_for(offset...@text.size)
+				end
+				
+				return output
+			end
+			
+			def link_to(definition, text)
+				"[#{text}]"
+			end
+		end
+	end
+end

data/lib/decode/trie.rb

@@ -116,7 +116,7 @@ module Decode
 		end
 		
 		# Traverse the trie.
-		# See {Node:traverse} for details.
+		# See {Node#traverse} for details.
 		def traverse(path = [], &block)
 			if node = @root.lookup(path)
 				node.traverse(&block)

data/lib/decode/version.rb

@@ -19,5 +19,5 @@
 # THE SOFTWARE.
 
 module Decode
-	VERSION = "0.14.0"
+	VERSION = "0.15.3"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: decode
 version: !ruby/object:Gem::Version
-  version: 0.14.0
+  version: 0.15.3
 platform: ruby
 authors:
 - Samuel Williams
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2020-05-10 00:00:00.000000000 Z
+date: 2020-08-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: parser
@@ -38,34 +38,6 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-- !ruby/object:Gem::Dependency
-  name: bake-bundler
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: utopia-project
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
 - !ruby/object:Gem::Dependency
   name: covered
   requirement: !ruby/object:Gem::Requirement
@@ -108,7 +80,7 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description: 
+description:
 email:
 - samuel.williams@oriontransfer.co.nz
 executables: []
@@ -139,6 +111,7 @@ files:
 - lib/decode/language/ruby/block.rb
 - lib/decode/language/ruby/call.rb
 - lib/decode/language/ruby/class.rb
+- lib/decode/language/ruby/code.rb
 - lib/decode/language/ruby/constant.rb
 - lib/decode/language/ruby/definition.rb
 - lib/decode/language/ruby/function.rb
@@ -151,13 +124,16 @@ files:
 - lib/decode/scope.rb
 - lib/decode/segment.rb
 - lib/decode/source.rb
+- lib/decode/syntax/link.rb
+- lib/decode/syntax/match.rb
+- lib/decode/syntax/rewriter.rb
 - lib/decode/trie.rb
 - lib/decode/version.rb
 homepage: https://github.com/ioquatix/decode
 licenses:
 - MIT
 metadata: {}
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -173,7 +149,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubygems_version: 3.1.2
-signing_key: 
+signing_key:
 specification_version: 4
 summary: Code analysis for documentation generation.
 test_files: []