decode 0.13.0 → 0.15.2

data/lib/decode/comment/text.rb

@@ -0,0 +1,37 @@
+# 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 'node'
+
+module Decode
+	module Comment
+		# A structured comment.
+		class Text
+			def initialize(line)
+				@line = line
+			end
+			
+			attr :line
+			
+			def traverse
+			end
+		end
+	end
+end

data/lib/decode/comment/throws.rb

@@ -0,0 +1,32 @@
+# 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 'attribute'
+
+module Decode
+	module Comment
+		# Identifies that a method might throw a specific symbol.
+		#
+		# - `@throws [:skip] To skip recursion.`
+		#
+		class Throws < Attribute
+		end
+	end
+end

data/lib/decode/comment/yields.rb

@@ -0,0 +1,52 @@
+# 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 'tag'
+
+module Decode
+	module Comment
+		# Describes a block parameter.
+		#
+		# - `@yields {|person| ... } If a block is given.`
+		#
+		# Should contain nested parameters.
+		class Yields < Tag
+			PATTERN = /\A(?<block>{.*?})(\s+(?<details>.*?))?\Z/
+			
+			def self.build(directive, match)
+				node = self.new(directive, match[:block])
+				
+				if details = match[:details]
+					node.add(Text.new(details))
+				end
+				
+				return node
+			end
+			
+			def initialize(directive, block)
+				super(directive)
+				
+				@block = block
+			end
+			
+			attr :block
+		end
+	end
+end

data/lib/decode/definition.rb

@@ -22,10 +22,10 @@ module Decode
 	# A symbol with attached documentation.
 	class Definition
 		# Initialize the symbol.
-		# @param name [Symbol] The name of the definition.
-		# @param parent [Symbol] The parent lexical scope.
-		# @param language [Language] The language in which the symbol is defined in.
-		# @param comments [Array(String)] The comments associated with the definition.
+		# @parameter name [Symbol] The name of the definition.
+		# @parameter parent [Symbol] The parent lexical scope.
+		# @parameter language [Language] The language in which the symbol is defined in.
+		# @parameter comments [Array(String)] The comments associated with the definition.
 		def initialize(name, parent: nil, language: parent.language, comments: nil)
 			@name = name
 			
@@ -44,20 +44,23 @@ 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.
-		# @attr [Array(String)]
+		# @attribute [Array(String)]
 		attr :comments
 		
 		# The qualified name is an absolute name which includes any and all namespacing.
-		# @return [String]
+		# @returns [String]
 		def qualified_name
 			@qualified_name ||= begin
 				if @parent
@@ -69,21 +72,25 @@ module Decode
 		end
 		
 		# The name of this definition plus the nesting prefix.
-		# @return [String]
+		# @returns [String]
 		def nested_name
 			"::#{@name}"
 		end
 		
+		# Does the definition name match the specified prefix?
+		# @returns [Boolean]
 		def start_with?(prefix)
 			self.nested_name.start_with?(prefix)
 		end
 		
+		# Convert this definition into another kind of definition.
 		def convert(kind)
 			raise ArgumentError, "Unable to convert #{self} into #{kind}!"
 		end
 		
-		# The lexical scope which is an array of lexical {Key} instances as generated by {key}.
-		# @return [Array]
+		# The lexical scope as an array of names.
+		# e.g. `[:Decode, :Definition]`
+		# @returns [Array]
 		def path
 			if @path
 				# Cached version:
@@ -102,14 +109,14 @@ module Decode
 		# A short form of the definition.
 		# e.g. `def short_form`.
 		#
-		# @return [String | nil]
+		# @returns [String | nil]
 		def short_form
 		end
 		
 		# A long form of the definition.
 		# e.g. `def initialize(kind, name, comments, **options)`.
 		#
-		# @return [String | nil]
+		# @returns [String | nil]
 		def long_form
 			self.short_form
 		end
@@ -117,44 +124,44 @@ module Decode
 		# A long form which uses the qualified name if possible.
 		# Defaults to {long_form}.
 		#
-		# @return  [String | nil]
+		# @returns [String | nil]
 		def qualified_form
 			self.long_form
 		end
 		
 		# Whether the definition spans multiple lines.
 		#
-		# @return [Boolean]
+		# @returns [Boolean]
 		def multiline?
 			false
 		end
 		
 		# The full text of the definition.
 		#
-		# @return [String | nil]
+		# @returns [String | nil]
 		def text
 		end
 		
 		# Whether this definition can contain nested definitions.
 		#
-		# @return [Boolean]
+		# @returns [Boolean]
 		def container?
 			false
 		end
 		
 		# Whether this represents a single entity to be documented (along with it's contents).
 		#
-		# @return [Boolean]
+		# @returns [Boolean]
 		def nested?
 			container?
 		end
 		
 		# Structured access to the definitions comments.
 		#
-		# @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)
+				@documentation ||= Documentation.new(@comments, @language)
 			end
 		end
 	end

data/lib/decode/documentation.rb

@@ -18,83 +18,38 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 # THE SOFTWARE.
 
+require_relative 'comment/node'
+
+require_relative 'comment/attribute'
+require_relative 'comment/parameter'
+require_relative 'comment/pragma'
+require_relative 'comment/raises'
+require_relative 'comment/returns'
+require_relative 'comment/throws'
+require_relative 'comment/yields'
+
 module Decode
 	# Structured access to a set of comment lines.
-	class Documentation
+	class Documentation < Comment::Node
 		# Initialize the documentation with an array of comments, within a specific language.
 		#
-		# @param comments [Array(String)] An array of comment lines.
-		# @param language [Language] The language in which the comments were extracted.
+		# @parameter comments [Array(String)] An array of comment lines.
+		# @parameter language [Language] The language in which the comments were extracted.
 		def initialize(comments, language = nil)
 			@comments = comments
 			@language = language
-		end
-		
-		# The language in which the documentation was extracted from.
-		attr :language
-		
-		DESCRIPTION = /\A\s*([^@\s].*)?\z/
-		
-		# The text-only lines of the comment block.
-		#
-		# @yield [String]
-		# @return [Enumerable]
-		def description
-			return to_enum(:description) unless block_given?
-			
-			# We track empty lines and only yield a single empty line when there is another line of text:
-			gap = false
-			
-			@comments.each do |comment|
-				if match = comment.match(DESCRIPTION)
-					if match[1]
-						if gap
-							yield ""
-							gap = false
-						end
-						
-						yield match[1]
-					else
-						gap = true
-					end
-				else
-					break
-				end
-			end
-		end
-		
-		ATTRIBUTE = /\A\s*@(?<name>.*?)\s+(?<value>.*?)\z/
-		
-		# The attribute lines of the comment block.
-		# e.g. `@return [String]`.
-		#
-		# @yield [String]
-		# @return [Enumerable]
-		def attributes
-			return to_enum(:attributes) unless block_given?
 			
-			@comments.each do |comment|
-				if match = comment.match(ATTRIBUTE)
-					yield match
-				end
+			language.tags.parse(@comments.dup) do |node|
+				self.add(node)
 			end
 		end
 		
-		PARAMETER = /\A\s*@param\s+(?<name>.*?)\s+\[(?<type>.*?)\]\s+(?<details>.*?)\z/
+		# The underlying comments from which the documentation is extracted.
+		# @attribute [Array(String)]
+		attr :comments
 		
-		# The parameter lines of the comment block.
-		# e.g. `@param value [String] The value.`
-		#
-		# @yield [String]
-		# @return [Enumerable]
-		def parameters
-			return to_enum(:parameters) unless block_given?
-			
-			@comments.each do |comment|
-				if match = comment.match(PARAMETER)
-					yield match
-				end
-			end
-		end
+		# The language in which the documentation was extracted from.
+		# @attribute [Language::Generic]
+		attr :language
 	end
 end

data/lib/decode/index.rb

@@ -38,26 +38,26 @@ module Decode
 		end
 		
 		# All supported languages for this index.
-		# @attr [Languages]
+		# @attribute [Languages]
 		attr :languages
 		
 		# All source files that have been parsed.
-		# @attr [Array(Source)]
+		# @attribute [Array(Source)]
 		attr :sources
 		
 		# All definitions which have been parsed.
-		# @attr [Array(Symbol)]
+		# @attribute [Array(Symbol)]
 		attr :definitions
 		
 		# A (prefix) trie of lexically scoped definitions.
-		# @attr [Trie]
+		# @attribute [Trie]
 		
 		attr :trie
 		
 		# Updates the index by parsing the specified files.
 		# All extracted definitions are merged into the existing index.
 		#
-		# @param paths [Array(String)] The source file paths.
+		# @parameter paths [Array(String)] The source file paths.
 		def update(paths)
 			paths.each do |path|
 				if source = @languages.source_for(path)
@@ -75,8 +75,8 @@ module Decode
 		
 		# Lookup the specified reference and return matching definitions.
 		#
-		# @param reference [Reference] The reference to match.
-		# @param relative_to [Definition] Lookup the reference relative to the scope of this definition.
+		# @parameter reference [Language::Reference] The reference to match.
+		# @parameter relative_to [Definition] Lookup the reference relative to the scope of this definition.
 		def lookup(reference, relative_to: nil)
 			if reference.absolute? || relative_to.nil?
 				lexical_path = []

data/lib/decode/language/generic.rb

@@ -36,13 +36,13 @@ module Decode
 			end
 			
 			# Parse the input yielding definitions.
-			# @block `{|definition| ...}`
+			# @block {|definition| ... }
 			# @yield definition [Definition]
 			def definitions_for(input, &block)
 			end
 			
 			# Parse the input yielding interleaved comments and code segments.
-			# @block `{|segment| ...}`
+			# @block {|segment| ... }
 			# @yield segment [Segment]
 			def segments_for(input, &block)
 			end

data/lib/decode/language/reference.rb

@@ -23,20 +23,29 @@ module Decode
 		# An reference which can be resolved to zero or more definitions.
 		class Reference
 			# Initialize the reference.
-			# @param identifier [String] The identifier part of the reference.
-			def initialize(identifier, language)
+			# @parameter identifier [String] The identifier part of the reference.
+			def initialize(identifier, language, lexical_path = nil)
 				@identifier = identifier
 				@language = language
 				
-				@lexical_path = nil
+				@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.
-			# @attr [String]
+			# @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.
@@ -58,18 +67,39 @@ 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.
-			# @return [Array(String)]
+			# @returns [Array(String)]
 			def path
 				@path ||= self.lexical_path.map{|_, name| name.to_sym}
 			end