decode 0.12.0 → 0.15.1

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

@@ -21,11 +21,15 @@
 require_relative 'source'
 require_relative 'trie'
 
+require_relative 'languages'
+
 module Decode
 	# A list of definitions organised for quick lookup and lexical enumeration.
 	class Index
 		# Initialize an empty index.
-		def initialize
+		def initialize(languages = Languages.all)
+			@languages = languages
+			
 			@sources = {}
 			@definitions = {}
 			
@@ -33,26 +37,30 @@ module Decode
 			@trie = Trie.new
 		end
 		
+		# All supported languages for this index.
+		# @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 = Source.for?(path)
+				if source = @languages.source_for(path)
 					@sources[path] = source
 					
 					source.definitions do |symbol|
@@ -67,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.rb

@@ -18,29 +18,11 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 # THE SOFTWARE.
 
+require_relative 'language/generic'
 require_relative 'language/ruby'
 
 module Decode
 	# Language specific parsers and definitions.
 	module Language
-		def self.detect(path)
-			case path
-			when /\.(rb|ru)\z/
-				return Language::Ruby
-			end
-		end
-		
-		REFERENCE = /\A(?<language>\.[a-z]+)?\s+(?<text>.*?)\z/
-		
-		# A language agnostic reference:
-		# e.g. `.rb MyModule::MyClass`
-		#
-		def self.reference(string, language = nil)
-			if match = REFERENCE.match(string)
-				language = self.detect(match[:language]) || language
-				
-				return language.reference(match[:text])
-			end
-		end
 	end
 end