proteus 0.9.0

data/README

@@ -0,0 +1,88 @@
+                              
+                              
+                              
+                              Welcome to Proteus
+                              
+                              
+
+Proteus is an abstraction of general document definition and display markup that
+allows you to create and reuse complex patterns of structured content.
+
+The purpose of Proteus is to allow you to describe documents in terms of their
+content, abstracting away from the often cumbersome markup or syntax of its
+native form (for example in HTML).
+
+
+Project Goals:
+
+  1. Content-orientation: we should be describing content, not the structure
+     used to display it.
+  2. Human-readability: it should be easy for a human to write and maintain
+     documents.
+  3. Flexibility: it should be easy to adapt the solution to solve a wide
+     variety of problems.
+  4. Extensibility: it should be easy to change the behaviour of the system as
+     it is required.
+
+
+For Users:
+
+Proteus works by interpreting document definitions in YAML, for example:
+
+   Form:
+       - Control:
+           name: name
+       - Control:
+           name: age
+       - Control:
+           name: gender
+           type: select
+           options:
+             - male
+             - female
+
+Each camelcase node indicates a "component" - a piece of content which displays
+in a unique way. In the above example, the "Form" and "Control" nodes are
+components and the rest of the information describes those components.
+
+
+For Developers:
+
+Proteus provides a simple system for describing new component types that
+permits inheritance and composition of existing types, again in human readable
+syntax. This allows users to create custom languages from existing components
+quickly and easily.
+
+
+The Name:
+
+In Greek mythology, Proteus is an early sea-god who can foretell the future
+and change his shape. From this feature of Proteus comes the adjective protean,
+with the general meaning of "versatile", "mutable", "capable of assuming many
+forms". -- Wikipedia
+
+
+Homepage:
+
+More information is available on the Proteus website,
+    
+    proteus.rubyforge.org
+
+or on Github,
+
+    github.com/wmadden/proteus
+
+
+Licensing:
+  Proteus is free software: you can redistribute it and/or modify it under the
+terms of the GNU General Public License as published by the Free Software
+Foundation, either version 3 of the License, or (at your option) any later
+version.
+
+Proteus is distributed in the hope that it will be useful, but WITHOUT ANY
+WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+PARTICULAR PURPOSE.  See the GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License along with
+Proteus.  If not, see <http://www.gnu.org/licenses/>.
+

data/Rakefile

@@ -0,0 +1,33 @@
+
+require 'rubygems'
+require 'cucumber/rake/task'
+
+require 'rake'
+require 'spec/rake/spectask'
+
+desc "Run all examples with RCov"
+Spec::Rake::SpecTask.new(:spec) do |t|
+  t.spec_files = FileList['test/spec/**/*.rb']
+  t.rcov = true
+  t.rcov_opts = ['--exclude', 'spec']
+  t.rcov_dir = 'coverage/spec/'
+end
+
+require 'spec/rake/verify_rcov'
+
+RCov::VerifyTask.new(:verify_rcov => :spec) do |t|
+  t.threshold = 100.0
+  t.index_html = 'coverage/spec/verify/index.html'
+end
+
+Cucumber::Rake::Task.new(:features) do |t|
+  t.cucumber_opts = "--format pretty"
+  t.rcov = true
+  t.rcov_opts << %[-o "test/features/cucumber"]
+end
+
+task :doc do |t|
+  `rdoc -aUd src/ -o doc/api`
+end
+
+task :default => [:spec, :features, :verify_rcov]

data/bin/pro

@@ -0,0 +1,189 @@
+#!/usr/bin/ruby
+################################################################################
+# proteus
+#
+# Executable interface to the system.
+# -----------------------------------------------------------------------------
+# (C) Copyright 2009 William Madden
+# 
+# This file is part of Proteus.
+# 
+# Proteus is free software: you can redistribute it and/or modify it under the
+# terms of the GNU General Public License as published by the Free Software
+# Foundation, either version 3 of the License, or (at your option) any later
+# version.
+#
+# Proteus is distributed in the hope that it will be useful, but WITHOUT ANY
+# WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+# A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
+# 
+# You should have received a copy of the GNU General Public License along with
+# Proteus.  If not, see <http://www.gnu.org/licenses/>.
+################################################################################
+
+require 'getoptlong'
+require 'rdoc/usage'
+
+require 'Facade.rb'
+require 'TemplateRenderer.rb'
+require 'exceptions.rb'
+
+include Proteus
+
+PROTEUS_VERSION = "v0.9.0"
+
+USAGE =
+"""
+  Usage:
+    proteus [--path PATH] FILE
+    proteus --inline COMPONENT [--props PROPERTIES] [CHILDREN]
+    proteus --help
+  
+  Options:
+    --help, -h            Display this message.
+                         
+    --inline, -i          Parse inline. Takes component information on the
+                          command line and outputs the rendered component
+                          instance.
+                         
+    --path, -p            Sets the path to search for component definitions.
+                          Defaults to /usr/lib/proteus.
+                          
+    --props, -P           Sets the properties for an inline component.
+    
+    --no-current, -C      Don't add current directory to path.
+    
+    --version, -V      Output version.
+    
+"""
+
+PROTEUS_PATH = 'PROTEUS_PATH'
+
+def exit_error( error )
+  puts error
+  puts USAGE
+  exit( 1 )
+end
+
+def parse_props( props )
+  result = {}
+  
+  props.split( ',' ).each do |prop|
+    pair = prop.split(':')
+    result[ pair[0] ] = pair[1]
+  end
+  
+  return result
+end
+
+
+def parse_command_line
+
+  @opts.each do |opt, arg|
+    case opt
+      when '--help', '-h'
+        puts( USAGE )
+        exit( 0 )
+      when '--inline', '-i'
+        @inline = true
+      when '--props', '-P'
+        @props = parse_props( arg )
+      when '--path', '-p'
+        @path = arg
+      when '--namespace', '-n'
+        @current_ns = arg
+      when '--no-current', '-C'
+        @exclude_current = true
+      when '--version', '-V'
+        puts( PROTEUS_VERSION )
+        exit( 0 )
+    end
+  end
+
+end
+
+#------------------------------
+#  ENTRY POINT
+#------------------------------
+
+# Option variables
+@inline = false
+@path = ENV[ PROTEUS_PATH ] || FileHelper::DEFAULT_PATH
+@props = {}
+@current_ns = []
+@exclude_current = false
+
+# Valid options
+@opts = GetoptLong.new(
+  [ '--help', '-h', GetoptLong::NO_ARGUMENT ],
+  [ '--path', '-p', GetoptLong::REQUIRED_ARGUMENT ],
+  [ '--inline', '-i', GetoptLong::NO_ARGUMENT ],
+  [ '--props', '-P', GetoptLong::REQUIRED_ARGUMENT ],
+  [ '--namespace', '-n', GetoptLong::REQUIRED_ARGUMENT ],
+  [ '--no-current', '-C', GetoptLong::NO_ARGUMENT ],
+  [ '--version', '-V', GetoptLong::NO_ARGUMENT ]
+)
+
+# Parse command line
+parse_command_line
+
+# Set up system
+facade = Facade.new
+
+facade.path = @path + ':.'
+
+# Initialize renderer
+renderer = TemplateRenderer.new
+
+# Parse input
+if not @inline
+  
+  # from file
+  
+  if ARGV.length < 1
+    exit_error( "Error: no target given." )
+  elsif ARGV.length > 1
+    exit_error( "Error: multiple targets given." )
+  end
+  
+  file = ARGV[0]
+  
+  tree = facade.parse_file( file, @current_ns )
+  
+  puts renderer.render( tree )
+  
+else
+  
+  # from command line
+  
+  if ARGV.length < 1
+    exit_error( "Error: no component identifier given." )
+  end
+  
+  component_id = ARGV[0]
+  
+  ARGV.shift
+  component_children = ARGV
+  
+  component_properties = @props
+  
+  class_path = facade.input_parser.parse_component_id( component_id )
+  
+  begin
+    component_class = facade.definition_helper.get_class( class_path,
+      @current_ns )
+  rescue Exceptions::DefinitionUnavailable
+    exit_error( "Error: no definition found for '" + component_id + "'." )
+  end
+  
+  component_children = facade.input_parser.parse_yaml( component_children,
+    @current_ns )
+  
+  instance = ComponentInstance.new( component_class, component_properties,
+    component_children )
+  
+  facade.input_parser.parse_instance( instance, @current_ns )
+  
+  puts renderer.render( instance )
+  
+end

data/lib/ClassParser.rb

@@ -0,0 +1,84 @@
+################################################################################
+# ClassParser.rb
+#
+# Responsible for interpreting YAML for component classes.
+# -----------------------------------------------------------------------------
+# (C) Copyright 2009 William Madden
+# 
+# This file is part of Proteus.
+# 
+# Proteus is free software: you can redistribute it and/or modify it under the
+# terms of the GNU General Public License as published by the Free Software
+# Foundation, either version 3 of the License, or (at your option) any later
+# version.
+#
+# Proteus is distributed in the hope that it will be useful, but WITHOUT ANY
+# WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+# A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
+# 
+# You should have received a copy of the GNU General Public License along with
+# Proteus.  If not, see <http://www.gnu.org/licenses/>.
+################################################################################
+
+require File.expand_path( File.join(File.dirname(__FILE__), 'exceptions.rb') )
+require File.expand_path( File.join(File.dirname(__FILE__), 'ComponentClass.rb') )
+
+
+module Proteus
+  
+  #
+  # Provides functions for parsing component definitions (for component
+  # classes).
+  # 
+  class ClassParser
+    
+    # The regex for valid class names
+    @@CLASS_RE = /^([A-Z][a-zA-Z_0-9]*)(?:[\s]*<[\s]*([A-Z][a-zA-Z_0-9]*))?$/
+    @@CHILDREN = "children"
+    
+    #---------------------------------------------------------------------------
+    #  
+    #  Methods
+    #  
+    #---------------------------------------------------------------------------
+    
+  public
+    
+    #
+    # Parses YAML and returns the resultant component class.
+    # 
+    # yaml: the YAML to parse
+    # new_class: the class instance to parse
+    #
+    def parse_yaml( yaml, new_class = nil )
+      result = new_class || ComponentClass.new
+      
+      # Must be a hash of length one containing a hash
+      if not ( yaml.is_a?(Hash) and yaml.length == 1 and
+        (yaml.values[0].nil? or yaml.values[0].is_a?(Hash)) ) then
+        
+        raise Exceptions::DefinitionMalformed, "Class definition malformed"
+      end
+      
+      # Parse the class name
+      name = yaml.keys[0]
+      match = @@CLASS_RE.match( name )
+      
+      # If there's no match, the definition is malformed
+      if match.nil?
+        raise Exceptions::DefinitionMalformed,
+          "Class identifier '" + name + "' malformed."
+      end
+      
+      # Set properties of class
+      result.name = match[1]
+      result.parent = match[2]
+      result.properties = yaml.values[0] || {}
+      result.children = result.properties.delete(@@CHILDREN) || []
+      
+      return result
+    end
+    
+  end
+  
+end

data/lib/ComponentClass.rb

@@ -0,0 +1,51 @@
+################################################################################
+# ComponentClass.rb
+#
+# Represents an class of component.
+# -----------------------------------------------------------------------------
+# (C) Copyright 2009 William Madden
+# 
+# This file is part of Proteus.
+# 
+# Proteus is free software: you can redistribute it and/or modify it under the
+# terms of the GNU General Public License as published by the Free Software
+# Foundation, either version 3 of the License, or (at your option) any later
+# version.
+#
+# Proteus is distributed in the hope that it will be useful, but WITHOUT ANY
+# WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+# A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
+# 
+# You should have received a copy of the GNU General Public License along with
+# Proteus.  If not, see <http://www.gnu.org/licenses/>.
+################################################################################
+
+module Proteus
+  
+  class ComponentClass
+    
+    DEFAULT_CLASS = ComponentClass.new()
+    
+    #---------------------------------------------------------------------------
+    #  
+    #  Constructor
+    #  
+    #---------------------------------------------------------------------------
+    
+    def initialize( )
+      @properties = {}
+      @children = []
+    end
+    
+    #---------------------------------------------------------------------------
+    #  
+    #  Properties
+    #  
+    #---------------------------------------------------------------------------
+    
+    attr_accessor :name, :namespace, :parent, :properties, :children
+    
+  end
+  
+end
+