RubyGems - rind - Versions diffs - 0.1.0 - Mend

rind 0.1.0

Files changed (29) hide show

data/LICENSE +22 -0
data/README.rdoc +111 -0
data/lib/rind.rb +15 -0
data/lib/rind/document.rb +81 -0
data/lib/rind/equality.rb +9 -0
data/lib/rind/html.rb +41 -0
data/lib/rind/manipulate.rb +31 -0
data/lib/rind/nodes.rb +234 -0
data/lib/rind/parser.rb +141 -0
data/lib/rind/traverse.rb +86 -0
data/lib/rind/xml.rb +28 -0
data/lib/rind/xpath.rb +144 -0
data/test/all_test.rb +14 -0
data/test/cdata_test.rb +9 -0
data/test/children_test.rb +50 -0
data/test/comment_test.rb +9 -0
data/test/document_test.rb +23 -0
data/test/element_test.rb +49 -0
data/test/equality_test.rb +19 -0
data/test/files/document_test.html +8 -0
data/test/files/traverse_test.html +13 -0
data/test/html_test.rb +16 -0
data/test/manipulate_test.rb +23 -0
data/test/nodes_test.rb +16 -0
data/test/parser_test.rb +7 -0
data/test/traverse_test.rb +57 -0
data/test/xml_test.rb +14 -0
data/test/xpath_test.rb +27 -0
metadata +109 -0

data/LICENSE ADDED Viewed

@@ -0,0 +1,22 @@
+Copyright (c) 2010 Aaron Lasseigne
+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.

data/README.rdoc ADDED Viewed

@@ -0,0 +1,111 @@
+= Rind
+Rind is a templating engine that turns HTML (and XML) into node trees
+and allows you to create custom tags or reuse someone else's genius.
+Rind gives web devs tags to work with and provides the same thing to
+app devs as an object. This project is just getting started so watch
+out for sharp corners and unfinished rooms. Enough of that, let's talk
+about what's done.
+== Come say "Hello".
+  # example.rb
+  require 'rind'
+  # Create a new document and load your template.
+  doc = Rind::Document.new('index.html')
+  # Xpath search for the the title and add some text.
+  doc.sf('/html/head/title').children.push('Hello World')
+  # Send it out the door.
+  puts doc.render!
+== Create your own!
+One of the great things about Rind is that you can create your own HTML
+elements and bundle them in modules. Imagine making a module that performs
+a variety of useful functions on images. For example, it could provide
+a gallery view that automatically generates thumbnails and paginates. Clicked
+pics could provide full sized versions of themselves in a lightbox.
+Create your custom module.
+  # images.rb
+  require 'rind'
+  module Images
+    class Gallery < Rind::Element
+      attr_accessor :path_to_images
+      # gallery magic here
+      ...
+    end
+  end
+App devs treat it like an object.
+  # index.cgi
+  require 'rind'
+  require 'images'
+  doc = Rind::Document.new('index.html')
+  doc.sf('/html/body/images:gallery').path_to_images = '/home/me/photos'
+  puts doc.render!
+Web devs treat it like a tag.
+  # index.html
+  <html>
+    <body>
+      <images:gallery width="400px" per_row="5" max_rows="3"/>
+    </body>
+  </html>
+And just like a regular Ruby module, if you make it available, we can all benefit.
+== Mucking with standard HTML
+Interested in modifying the behavior of a standard HTML element? Let's
+say that you want all external links to use <tt>rel="nofollow"</tt>.
+Rather than remembering to do this every time you can build it into a base
+namespace.
+Create your base module.
+  # core.rb
+  require 'rind'
+  module Core
+    class A < Rind::Html::A
+      def initialize(options={})
+	      super(options)
+	      @attributes[:rel] = 'nofollow' if is_external?
+      end
+      def is_external?
+        ....
+      end
+      private :is_external?
+    end
+  end
+Pass it to the Document as the <tt>base_namespace</tt>.
+  # my_file.cgi
+  require 'rind'
+  require 'core'
+  doc = Document.new('index.html', :base_namespace => 'core')
+  puts doc.render!
+The links in <tt>index.html</tt> will now have the <tt>rel</tt> attribute
+automatically added.
+  <a href="http://github.com" rel="nofollow">GitHub</a>
+== The Future?
+This is an early release. An alpha of sorts. The interface may change before it's
+all over. Rind needs to help out modules with style sheets, JavaScript libraries,
+images, querying system/user info, etc. Virtually no time has been spent optimizing
+the code. More test cases need to be written. I still have a bunch of stuff in my
+office that needs filing. You get the idea.

data/lib/rind.rb ADDED Viewed

@@ -0,0 +1,15 @@
+# :title: Rind
+# :main: lib/rind.rb
+# :include: README.rdoc
+# = License
+# :include: LICENSE
+require 'rind/equality'
+require 'rind/traverse'
+require 'rind/manipulate'
+require 'rind/xpath'
+require 'rind/nodes'
+require 'rind/html'
+require 'rind/xml'
+require 'rind/parser'
+require 'rind/document'

data/lib/rind/document.rb ADDED Viewed

@@ -0,0 +1,81 @@
+module Rind
+	class Document
+		include Equality
+		attr_reader :base_namespace, :dom, :template, :type
+		# === Parameter
+		# _template_ = file system path to the template
+		#
+		# === Options
+		# * _base_namespace_ = namespace
+		#
+		#   Allows you to provide a namespace to check before
+		#   falling back to the default Rind namespace.
+		# * _require_ = array of namespaces
+		#
+		#   All namespaces that should be rendered must be
+		#   listed.
+		# * _type_ = "xml" or "html"
+		#
+		#   This can be automatically detect based on the
+		#   file extension. Unknown extensions will default
+		#   to "xml".
+		# === Example
+		#  Rind::Document.new( "template.tpl", {
+		#    :type           => "html",
+		#    :base_namespace => "core",
+		#    :require        => ["forms","photos"]
+		#  })
+		def initialize(template, options = {})
+			@template = template
+			raise 'No such template.' if not File.file? @template
+			if options[:type]
+				@type = options[:type]
+			else
+				@type = case File.extname(@template)
+				when '.html', '.htm'
+					'html'
+				else
+					'xml'
+				end
+			end
+			if options[:base_namespace]
+				@base_namespace = options[:base_namespace]
+			else
+				@base_namespace = ['rind', @type].join(':')
+			end
+			@dom = Rind.parse(@template, @type, @base_namespace, options[:require])
+		end
+		# Renders the Document in place. This will recursively call
+		# <tt>render!</tt> on all the Document contents.
+		def render!
+			@dom.collect{|node| node.respond_to?(:render!) ? node.render! : node}.join('')
+		end
+		# Return the root node of the Document.
+		def root
+			@dom.each do |node|
+				return node if not node.is_a? Rind::DocType
+			end
+		end
+		def to_s
+			@dom.to_s
+		end
+		# Xpath search of the root node that returns a list of matching nodes.
+		def s(path)
+			root.s(path)
+		end
+		# Xpath search returning only the first matching node in the list.
+		def sf(path)
+			root.sf(path)
+		end
+	end
+end

data/lib/rind/equality.rb ADDED Viewed

@@ -0,0 +1,9 @@
+module Equality
+	def ==(item)
+		self.to_s == item.to_s
+	end
+	def eql?(item)
+		item.instance_of?(self.class) && self == item
+	end
+end

data/lib/rind/html.rb ADDED Viewed

@@ -0,0 +1,41 @@
+module Rind
+	# Rind::Html will dynamically create any standard (or not) HTML element.
+	module Html
+		@@self_closing = ['br','hr','img','input','meta','link']
+		def self.const_missing(full_class_name, options={}) # :nodoc:
+			klass = Class.new(Element) do
+			  # <b>Parent:</b> Element
+				# === Example
+				#  Rind::Html::A.new(
+				#    :attributes => {:href => "http://github.com"},
+				#    :children   => "GitHub"
+				#  )
+				def initialize(options={})
+					super(options)
+				end
+				def expanded_name # :nodoc:
+					if @namespace_name.nil? or @namespace_name == '' or @namespace_name =~ /^(?:rind:)?html/
+						@local_name
+					else
+						[@namespace_name, @local_name].join(':')
+					end
+				end
+				def to_s # :nodoc:
+					attrs = @attributes.collect{|k,v| "#{k}=\"#{v}\""}.join(' ')
+					attrs = " #{attrs}" if not attrs.empty?
+					if @@self_closing.include? @local_name
+						"<#{self.expanded_name}#{attrs} />"
+					else
+						"<#{self.expanded_name}#{attrs}>#{@children}</#{self.expanded_name}>"
+					end
+				end
+			end
+			const_set full_class_name, klass
+			klass
+		end
+	end
+end

data/lib/rind/manipulate.rb ADDED Viewed

@@ -0,0 +1,31 @@
+# Note: These functions are not available for the root node in a tree.
+module Manipulate
+	# Calls {Rind::Children::insert}[link:classes/Rind/Children.html#insert]
+	# to add nodes after <tt>self</tt>.
+	# === Example
+	#  nodes = ['a', 'b', 'c']
+	#  nodes[0].insert_after('d', 'e') => ['a', 'd', 'e', 'b', 'c']
+	def insert_after(*nodes)
+		children = self.parent.children
+		children.insert(children.index(self)+1, *nodes)
+	end
+	# Calls {Rind::Children::insert}[link:classes/Rind/Children.html#insert]
+	# to add nodes before <tt>self</tt>.
+	# === Example
+	#  nodes = ['a', 'b', 'c']
+	#  nodes[2].insert_after('d', 'e') => ['a', 'b', 'd', 'e', 'c']
+	def insert_before(*nodes)
+		children = self.parent.children
+		children.insert(children.index(self), *nodes)
+	end
+	# Calls {Rind::Children::delete}[link:classes/Rind/Children.html#delete]
+	# on <tt>self</tt>.
+	# === Example
+	#  nodes = ['a', 'b', 'c']
+	#  nodes[1].delete => 'b'
+	def remove
+		self.parent.children.delete(self)
+	end
+end

data/lib/rind/nodes.rb ADDED Viewed

@@ -0,0 +1,234 @@
+module Rind
+	class Nodes < Array
+		# Return only the nodes that match the Xpath provided.
+		def filter(path)
+			# if the path doesn't have an axis then default to "self"
+			if path !~ /^([.\/]|(.+?::))/
+				path = "self::#{path}"
+			end
+			Nodes.new(self.find_all{|node| node.s(path)})
+		end
+	end
+	class Cdata
+		include Equality
+		include Manipulate
+		include Traverse
+		include Xpath
+		# Create a CDATA with <tt>content</tt> holding
+		# the character data to contain.
+		def initialize(content)
+			@content = content
+		end
+		def to_s
+			"<![CDATA[#{@content}]]>"
+		end
+	end
+	class Comment
+		include Equality
+		include Manipulate
+		include Traverse
+		include Xpath
+		# Create a comment with <tt>content</tt> holding
+		# the character data of the comment.
+		def initialize(content)
+			@content = content
+		end
+		def to_s
+			"<!--#{@content}-->"
+		end
+	end
+	class DocType
+		# Create a Document Type Declaration with
+		# +content+ holding the DTD identifiers.
+		def initialize(content)
+			@content = content
+		end
+		def to_s
+			"<!DOCTYPE#{@content}>"
+		end
+	end
+	class ProcessingInstruction
+		# Create a processing instruction with
+		# +content+ holding the character data.
+		def initialize(content)
+			@content = content
+		end
+		def to_s
+			"<?#{@content}>"
+		end
+	end
+	class Element
+		include Equality
+		include Manipulate
+		include Traverse
+		include Xpath
+		attr_reader :children, :local_name, :namespace_name
+		alias :name :local_name
+		alias :namespace :namespace_name
+		# === Options
+		# * _attributes_ = hash or string
+		# * _children_   = array of nodes
+		# === Examples
+		#  Rind::Element.new(
+		#    :attributes => { :id => "first", :class => "second" },
+		#    :children   => [Rind::Element.new(), Rind::Element.new()]
+		#  )
+		#  Rind::Element.new(
+		#    :attributes => 'id="first" class="second"',
+		#    :children   => "Hello World!"
+		#  )
+		def initialize(options={})
+			self.class.to_s =~ /^(?:([\w:]+)::)?(\w+)$/
+			@namespace_name, @local_name = $1, $2.downcase
+			@namespace_name.downcase!.gsub!(/::/, ':') if not @namespace_name.nil?
+			@namespace_name = options[:namespace_name] if options[:namespace_name]
+			@attributes = Hash.new
+			if options[:attributes].is_a? Hash
+				options[:attributes].each do |k,v|
+					@attributes[k.to_s] = v
+				end
+			elsif options[:attributes].is_a? String
+				options[:attributes].split(/\s+/).each do |attribute|
+					name, value = attribute.split(/=/)
+					@attributes[name] = value.scan(/\"(.*?)\"/).to_s
+				end
+			end
+			@children = Children.new(self, *options[:children])
+		end
+		# Get attributes or an attribute values.
+		# === Examples
+		#  e = Rind::Element.new(:attributes => {:id => "id_1", :class => "class_1"})
+		#  e[]        => {"id"=>"id_1", "class"=>"class_1"}
+		#  e[:id]     => "id_1"
+		#  e['class'] => "class_1"
+		def [](key = nil)
+			key.nil? ? @attributes : @attributes[key.to_s]
+		end
+		# Set the value of an attribute.
+		# === Examples
+		#  e = Rind::Element.new(:attributes => {:id => "id_1", :class => "class_1"})
+		#  e['id']   => "id_2"
+		#  e[:class] => "class_2"
+		def []=(key, value)
+			@attributes[key.to_s] = value
+		end
+		# Get the full name of the Element.
+		# === Examples
+		#  b = Rind::Html::Br.new()
+		#  b.expanded_name => 'br'
+		#  cn = Custom::Node.new()
+		#  cn.expanded_name => 'custom:node'
+		def expanded_name
+			if @namespace_name == 'rind'
+				@local_name
+			else
+				[@namespace_name, @local_name].join(':')
+			end
+		end
+		# Renders the node in place. This will recursively call
+		# <tt>render!</tt> on all child nodes.
+		def render!
+			@children.render! if not @children.empty?
+			self
+		end
+		def to_s
+			attrs = @attributes.collect{|k,v| "#{k}=\"#{v}\""}.join(' ')
+			attrs = " #{attrs}" if not attrs.empty?
+			if @children.empty?
+				"<#{self.expanded_name}#{attrs} />"
+			else
+				"<#{self.expanded_name}#{attrs}>#{@children}</#{self.expanded_name}>"
+			end
+		end
+	end
+	# All of the Array functions have been modified to work with Children.
+	# Functions like <tt>pop</tt> that remove a node and return it will
+	# remove the association to the parent node. Functions like "push"
+	# will automatically associate the nodes to the parent.
+	class Children < Nodes
+		include Enumerable
+		include Equality
+		def initialize(parent, *nodes)
+			super(nodes)
+			@parent = parent
+			fix_children!
+		end
+		def fix_children!
+			compact!
+			collect! do |node|
+				node = Rind::Text.new(node) if node.is_a?(String)
+				node.parent = @parent
+				node
+			end
+		end
+		private :fix_children!
+		def self.call_and_fix_children(*functions)
+			functions.each do |f|
+				define_method(f) do
+					value = super
+					fix_children!
+					value
+				end
+			end
+		end
+		private_class_method :call_and_fix_children
+		call_and_fix_children :fill, :insert, :push, :replace, :unshift
+		def self.pass_and_clear_parent(*functions)
+			functions.each do |f|
+				define_method(f) do
+					node = super
+					node.parent = nil if not node.nil?
+					node
+				end
+			end
+		end
+		private_class_method :pass_and_clear_parent
+		pass_and_clear_parent :delete_at, :pop, :shift
+		def delete(child, &block) # :nodoc:
+			child = Rind::Text.new(child) if child.is_a?(String)
+			node = super(child, &block)
+			node.parent = nil if node.respond_to? :parent
+			node
+		end
+		# Replace the child nodes with their rendered values.
+		def render!
+			nodes = collect{|child| child.respond_to?(:render!) ? child.render! : child}.flatten
+			replace(nodes)
+		end
+	end
+	class Text < String
+		include Manipulate
+		include Traverse
+		include Xpath
+	end
+end