decode 0.12.0 → 0.15.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 353e9f1529672844e406beb0587827a8a5a4e045506511019c1adf91ebf22a42
-  data.tar.gz: 88ef4f1965c4a95c0ddff8aa3857083e7854eb5c1b2dcbef02c3c1d92749d4b6
+  metadata.gz: d503df4edff393db446c6c310b6eea0ecbfe16cf10192a835b92a1685ca7c9bf
+  data.tar.gz: 57bc7884dd02e59b9564c1acbafc037a0dc73c458b8d986febecb5a81f4b250b
 SHA512:
-  metadata.gz: c386399350a839bd1e53e5398d725a7a14a311fd3af8c946e27bb2b472e1859b30e36bd3286e56c03b5956078705ea2b099ed002dfbaf22b169f8cc729fadc2f
-  data.tar.gz: e0e20aa3755863f3ad67c1317be7451c141ef783e90cb5f69fde7a5c91ab6992ad522cb11cf9988e91de95ca2d1d1e852b3cb4ba767023356f3c7dd6cb6534de
+  metadata.gz: 10ddb407f54f4091a3a0b876f6a971e9b5c83e68aab21d1255261306e5e15c4d74e063bb3da26e30cd20dfa24c46721d05966b25c5ed537a3e976f16cb8a9fca
+  data.tar.gz: fa41898224db150d5fd491f91d494878336edce0cceecb98a91e6187df6bd55dca9582149028bbefd58587796bbb3b2b629d710c4ef3408d005bd75e30dbf2d0

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,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.
+
+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
+		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(child)` to recursively traverse the specified child.
+			#
+			# @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)
+				}
+				
+				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,58 @@
+# 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
+		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