decode 0.12.0 → 0.15.1

data/lib/decode/language/ruby/segment.rb

@@ -40,7 +40,7 @@ module Decode
 				end
 				
 				# The source code trailing the comments.
-				# @return [String | nil]
+				# @returns [String | nil]
 				def code
 					@expression.source
 				end

data/lib/decode/languages.rb

@@ -0,0 +1,92 @@
+# 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 'language/generic'
+require_relative 'language/ruby'
+
+module Decode
+	# A context for looking up languages based on file extension or name.
+	class Languages
+		def self.all
+			self.new.tap do |languages|
+				languages.add(Language::Ruby)
+			end
+		end
+		
+		def initialize
+			@named = {}
+			@extensions = {}
+		end
+		
+		def freeze
+			return unless frozen?
+			
+			@named.freeze
+			@extensions.freeze
+			
+			super
+		end
+		
+		def add(language)
+			language.names.each do |name|
+				@named[name] = language
+			end
+			
+			language.extensions.each do |extension|
+				@extensions[extension] = language
+			end
+		end
+		
+		def fetch(name)
+			@named.fetch(name) do
+				unless @named.frozen?
+					@named[name] = Language::Generic.new(name)
+				end
+			end
+		end
+		
+		def source_for(path)
+			extension = File.extname(path)
+			
+			if language = @extensions[extension]
+				Source.new(path, language)
+			end
+		end
+		
+		REFERENCE = /\A(?<name>[a-z]+)?\s+(?<identifier>.*?)\z/
+		
+		# Parse a language agnostic reference:
+		# e.g. `ruby MyModule::MyClass`
+		#
+		def parse_reference(text, default_language: nil)
+			if match = REFERENCE.match(text)
+				language = self.fetch(match[:name]) || default_language
+				
+				return language.reference_for(match[:identifier])
+			elsif default_language
+				return default_language.reference_for(text)
+			end
+		end
+		
+		def reference_for(name, identifier)
+			self.fetch(name).reference_for(identifier)
+		end
+	end
+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

@@ -35,15 +35,15 @@ module Decode
 		end
 		
 		# The preceeding comments.
-		# @attr [Array(String)]
+		# @attribute [Array(String)]
 		attr :comments
 		
 		# The language of the code attached to this segment.
-		# @attr [Language]
+		# @attribute [Language::Generic]
 		attr :language
 		
 		# An interface for accsssing the documentation of the definition.
-		# @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, @language)
@@ -51,7 +51,7 @@ module Decode
 		end
 		
 		# The source code trailing the comments.
-		# @return [String | nil]
+		# @returns [String | nil]
 		def code
 		end
 	end

data/lib/decode/source.rb

@@ -21,40 +21,50 @@
 require_relative 'language'
 
 module Decode
+	# Represents a source file in a specific language.
 	class Source
-		def self.for?(path)
-			if language = Language.detect(path)
-				self.new(path, language)
-			end
-		end
-		
-		def initialize(path, language = nil)
+		def initialize(path, language)
 			@path = path
-			@language = language || Language.detect(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

@@ -31,17 +31,17 @@ module Decode
 			end
 			
 			# A mutable array of all values that terminate at this node.
-			# @attr [Array]
+			# @attribute [Array]
 			attr_accessor :values
 			
 			# A hash table of all children nodes, indexed by name.
-			# @attr [Hash(String, Node)]
+			# @attribute [Hash(String, Node)]
 			attr :children
 			
 			# Look up a lexical path starting at this node.
 			#
-			# @param path [Array(String)] The path to resolve.
-			# @return [Node | Nil]
+			# @parameter path [Array(String)] The path to resolve.
+			# @returns [Node | Nil]
 			def lookup(path, index = 0)
 				if index < path.size
 					if child = @children[path[index]]
@@ -55,9 +55,9 @@ module Decode
 			# Traverse the trie from this node.
 			# Invoke `descend.call` to traverse the children of the current node.
 			#
-			# @param path [Array(String)] The current lexical path.
+			# @parameter path [Array(String)] The current lexical path.
 			#
-			# @block `{|path, node, descend| descend.call}`
+			# @block {|path, node, descend| descend.call}
 			# @yield path [Array(String)] The current lexical path.
 			# @yield node [Node] The current node which is being traversed.
 			# @yield descend [Proc] The recursive method for traversing children.
@@ -76,12 +76,12 @@ module Decode
 		end
 		
 		# The root of the trie.
-		# @attr [Node]
+		# @attribute [Node]
 		attr :root
 		
 		# Insert the specified value at the given path into the trie.
-		# @param path [Array(String)] The lexical path where the value will be inserted.
-		# @param value [Object] The value to insert.
+		# @parameter path [Array(String)] The lexical path where the value will be inserted.
+		# @parameter value [Object] The value to insert.
 		def insert(path, value)
 			node = @root
 			
@@ -94,15 +94,15 @@ module Decode
 		
 		# Lookup the values at the specified path.
 		#
-		# @param path [Array(String)] The lexical path which contains the values.
-		# @return [Array(Object) | Nil] The values that existed (or not) at the specified path.
+		# @parameter path [Array(String)] The lexical path which contains the values.
+		# @returns [Array(Object) | Nil] The values that existed (or not) at the specified path.
 		def lookup(path)
 			@root.lookup(path)
 		end
 		
 		# Enumerate all lexical scopes under the specified path.
 		#
-		# @block `{|path, values| ...}`
+		# @block {|path, values| ...}
 		# @yield path [Array(String)] The lexical path.
 		# @yield values [Array(Object)] The values that exist at the given path.
 		def each(path = [], &block)
@@ -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)