decode 0.13.0 → 0.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d285f0566ed8682b02da2b41c0d1e56d4fd45a47ed26e4d4f4ec5a274dbbca45
-  data.tar.gz: 41baab474d5c16ea408ded0fded49479dbbe62649044e142f65b536c6a805e52
+  metadata.gz: 3def34b952d9d52ecd46b00af1d0d6bf35c1e1356b73f0684044d374e23fcbf3
+  data.tar.gz: b95a502a185aedaa5f64c6cdaee5abd30ba0739df530cc1fa5a957b54328f261
 SHA512:
-  metadata.gz: 474044bd964488c5a9003b502c982374d1fca23a00a04a07191b95e86e463ff0c39a54fdb5362ed2dee626538a60e50a07697d3d2cccff3bcc312829f470e535
-  data.tar.gz: 9ad91167fc2f1c6dddfca9e35d4773237125b9433b49163ee35541899efe01a003f719c8b2bb3eac469efe35c7d505a70d8b3a70a87d1ae804dabef41d1784d3
+  metadata.gz: ebb0306d62ce7feeff715b4fb1f2b622d21ab877285c678e8a83acb08f2183c83c4bc6cf3f2ec88743006142fa9f1c8f1094812bf2fde96d1e6d2ffcdb65c133
+  data.tar.gz: 79d583ef1946a0a94010fdd8b23cf2e36433e355eb7c6efb2f72bd949784b563d89e4693b73532e8fdc6cea3bef462dc6c74f484aff0cce95d289a675aebd731

data/bake/decode/index.rb

@@ -1,6 +1,6 @@
 
 # Process the given source root and report on comment coverage.
-# @param root [String] The root path to index.
+# @parameter root [String] The root path to index.
 def coverage(root)
 	require 'build/files/glob'
 	require 'decode/index'

data/lib/decode/comment/attribute.rb

@@ -0,0 +1,61 @@
+# 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 an attribute type.
+		#
+		# - `@attribute [Integer] The person's age.`
+		#
+		class Attribute < Tag
+			PATTERN = /\A\[(?<type>.*?)\](\s+(?<details>.*?))?\Z/
+			
+			def self.build(directive, match)
+				node = self.new(directive, match[:type])
+				
+				if details = match[:details]
+					node.add(Text.new(details))
+				end
+				
+				return node
+			end
+			
+			def initialize(directive, type)
+				super(directive)
+				
+				@type = type
+			end
+			
+			# 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

@@ -0,0 +1,90 @@
+# 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 Comment
+		class Node
+			# Initialize the node.
+			# @parameter children [Array(Node) | Nil]
+			def initialize(children = nil)
+				@children = children
+			end
+			
+			# Whether this node has any children nodes.
+			# Ignores {Text} instances.
+			# @returns [Boolean]
+			def children?
+				@children&.any?{|child| child.is_a?(Node)}
+			end
+			
+			# Add a child node to this node.
+			# @parameter child [Node] The node to add.
+			def add(child)
+				@children ||= []
+				@children << child
+			end
+			
+			# Any children of this node.
+			# @attribute [Array(Node | Text) | Nil]
+			attr :children
+			
+			# Enumerate all non-text children nodes.
+			def each(&block)
+				return to_enum unless block_given?
+				
+				@children&.each do |child|
+					yield child if child.is_a?(Node)
+				end
+			end
+			
+			# Any lines of text associated wtih this node.
+			# @returns [Array(String) | Nil] The lines of text.
+			def text
+				if text = self.extract_text
+					return text if text.any?
+				end
+			end
+			
+			# Traverse the tags from this node using {each}.
+			# Invoke `descend.call` to traverse the children of the current node.
+			#
+			# @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.
+			def traverse(&block)
+				descend = ->(node){
+					node.traverse(&block)
+				}
+				
+				yield(self, descend)
+			end
+			
+			protected
+			
+			def extract_text
+				if children = @children
+					@children.select{|child| child.kind_of?(Text)}.map(&:line)
+				else
+					nil
+				end
+			end
+		end
+	end
+end

data/lib/decode/comment/parameter.rb

@@ -0,0 +1,62 @@
+# 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 named method parameter.
+		#
+		# - `@parameter age [Float] The users age.`
+		#
+		class Parameter < Tag
+			PATTERN = /\A(?<name>.*?)\s+\[(?<type>.*?)\](\s+(?<details>.*?))?\Z/
+			
+			def self.build(directive, match)
+				node = self.new(directive, match[:name], match[:type])
+				
+				if details = match[:details]
+					node.add(Text.new(details))
+				end
+				
+				return node
+			end
+			
+			def initialize(directive, name, type)
+				super(directive)
+				
+				@name = name
+				@type = type
+			end
+			
+			# The name of the parameter.
+			# @attribute [String]
+			attr :name
+			
+			# 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/comment/pragma.rb

@@ -0,0 +1,50 @@
+# 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
+		# Asserts a specific property about the method signature.
+		#
+		# - `@reentrant This method is thread-safe.`
+		# - `@deprecated Please use {other_method} instead.`
+		# - `@blocking This method may block.`
+		# - `@asynchronous This method may yield.`
+		#
+		class Pragma < Tag
+			PATTERN = /\A(?<details>.*?)?\Z/
+			
+			def self.build(directive, match)
+				node = self.new(directive)
+				
+				if details = match[:details]
+					node.add(Text.new(details))
+				end
+				
+				return node
+			end
+			
+			def initialize(directive)
+				super(directive)
+			end
+		end
+	end
+end

data/lib/decode/comment/raises.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 raise an exception.
+		#
+		# - `@raises [ArgumentError] If the argument cannot be coerced.`
+		#
+		class Raises < Attribute
+		end
+	end
+end

data/lib/decode/comment/returns.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
+		# Describes a return value.
+		#
+		# - `@returns [Integer] The person's age.`
+		#
+		class Returns < Attribute
+		end
+	end
+end

data/lib/decode/comment/tag.rb

@@ -0,0 +1,50 @@
+# 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
+		class Tag < Node
+			def self.parse(directive, text, lines, tags, level = 0)
+				if match = self::PATTERN.match(text)
+					node = self.build(directive, match)
+					
+					tags.parse(lines, level + 1) do |child|
+						node.add(child)
+					end
+					
+					return node
+				else
+					# Consume all nested nodes:
+					tags.ignore(lines, level + 1)
+				end
+			end
+			
+			def initialize(directive)
+				@directive = directive
+			end
+			
+			# The directive that generated the tag.
+			# @attribute [String]
+			attr :directive
+		end
+	end
+end

data/lib/decode/comment/tags.rb

@@ -0,0 +1,80 @@
+# 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 'text'
+
+module Decode
+	module Comment
+		class Tags
+			def self.build
+				directives = Hash.new
+				
+				yield directives
+				
+				return self.new(directives)
+			end
+			
+			def initialize(directives)
+				@directives = directives
+			end
+			
+			def valid_indentation?(line, level)
+				line.start_with?('  ' * level) || line.start_with?("\t" * level)
+			end
+			
+			PATTERN = /\A\s*@(?<directive>.*?)(\s+(?<remainder>.*?))?\Z/
+			
+			def parse(lines, level = 0, &block)
+				while line = lines.first
+					# Is it at the right indentation level:
+					return unless valid_indentation?(line, level)
+					
+					# We are going to consume the line:
+					lines.shift
+					
+					# Match it against a tag:
+					if match = PATTERN.match(line)
+						if klass = @directives[match[:directive]]
+							yield klass.parse(
+								match[:directive], match[:remainder],
+								lines, self, level
+							)
+						else
+							# Ignore unknown directive.
+						end
+					
+					# Or it's just text:
+					else
+						yield Text.new(line.strip)
+					end
+				end
+			end
+			
+			def ignore(lines, level = 0)
+				if line = lines.first
+					# Is it at the right indentation level:
+					return unless valid_indentation?(line, level)
+					
+					lines.shift
+				end
+			end
+		end
+	end
+end