facets 2.6.0 → 2.7.0

data/demo/scenario_require.rd

@@ -0,0 +1,9 @@
+= Requiring Facets
+
+We should be able to require all the core libraries 
+by simply:
+
+  require 'facets'
+
+QED.
+

data/doc/README.more

@@ -1,20 +1,38 @@
 = Facets More Library
 
-  http://facets.rubyforge.com
+* http://facets.rubyforge.com
 
   "ALL YOUR BASE ARE BELONG TO RUBY"
 
 
 == Introduction
 
-On top of the extensive Core library, Facet provides a large collection of addational modules and classes.
+On top of the extensive Core library, Facet provides a small collection
+of additional modules and classes, as well as extended versions of
+modules and classes in Ruby's Standard library.
 
 
 == Usage
 
-Use the More library like ou would any other 3rd party library. The only difference between Facets More library and other
-thrid party libraries is the lack of a enclosing @Facets::@ namespace. This is becuase the libraries provided by Facets
-are considerd fairly low-level. (Albeit there are a few exceptions.)
+Use the More library like you would any other 3rd party library.
+The only difference between Facets More library and other libraries
+is the lack of any enclosing @Facets::@ namespace. This is becuase
+the libraries provided by Facets are considerd fairly low-level.
+
+When using Facets' extended versions of Ruby's standard libraries,
+the More libraries have to loaded manually, of course. However you
+do not need to load Ruby's library first, as the Facets' library
+will do that automatically.
+
+For example, normally one load Ruby's OpenStruct class via:
+
+  require 'ostruct'
+
+To load 'ostruct.rb' plus Facets extensions for it simply use:
+
+  require 'facets/ostruct'
+
+instead.
 
 
 == License
@@ -32,7 +50,7 @@ Acknowledgments and Copyrights for particular snippets of borrowed code are give
 
 
 
-ALL YOUR BASE ARE BELONG TO RUBY!
+  "ALL YOUR BASE ARE BELONG TO RUBY!"
 
 
 Ruby Facets, Copyright (c)2005,2006,2007,2008 Thomas Sawyer

data/doc/manual/about.rb

@@ -0,0 +1,47 @@
+# TomsLib - Tom's Ruby Support Library
+# Copyright (c) 2002 Thomas Sawyer, LGPL
+#
+# About
+# A plethora of modules, mixins and methods. Have fun!
+
+# TomsLib is free software; you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# TomsLib 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 Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with TomsLib; if not, write to the Free Software
+# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+
+
+module TomsLib
+  
+  TITLE = "TomsLib"
+	RELEASE = "02.06.18"
+	STATUS = "UCC"
+	AUTHOR = "Thomas Sawyer"
+	EMAIL = "transami@transami.net"
+  
+	Package = "#{TITLE}"
+	Version = "v#{RELEASE} #{STATUS}"
+	Copyright = "Copyright � 2002 #{AUTHOR}, #{EMAIL}"
+
+  def self.about
+    puts
+    puts TomsLib::Package
+    puts TomsLib::Version
+    puts TomsLib::Copyright
+    puts
+  end
+
+end
+
+# Write about info to standerd out
+if $0 == __FILE__
+	TomsLib.about
+end

data/doc/manual/annotations.rdoc

@@ -0,0 +1,60 @@
+= Annotations
+
+A Complete In Code Annotations System
+by Trans and George Moschovitis
+
+http://facets.rubyforge.org
+
+== Synopsis
+
+Annotations provides a complete and easy to use system of annotating methods and arbitrary objects. The annotations are defined in-code,not in comments, so it is fully reflective without any preproccessing.
+
+== What's New
+
+This is Facets/Annotations first release as an independent project. As with all Facets' subprojects it is included in the complete facets package. So if you have 'facets' installed you do not need this.
+
+Version 2.0+ is a major simplification over 1.0 series. Overall speed is much faster and the notation more consistant. Where before one would use "ann.attr_name.ann_name", now it's ann(:attr_name, :ann_name). This change was inspired by Ara T. Howard.
+
+== Example
+
+  class X
+    attr :foo, String, :default => "bar"
+  end
+
+  X.ann :foo, :class               #=> String
+  X.ann :foo, :default             #=> "bar"
+
+  X.ann :foo, :default => "baz"
+
+  X.ann :foo, :default             #=> "baz"
+
+== Installation
+
+IMPORTANT! This library is included in the complete facets package. You do not this library if you already have facets installed. 
+
+You can install either via gem or tarball.
+
+  gem install facets_annotations
+
+or
+
+  wget http://rubyforge.org/frs/download.php/18317/facets_annotations-2.0.0.tgz
+  cd facets_annotations
+  sudo ruby setup.rb
+
+== Documentation
+
+Please see doc/ directory for additional documentation.
+
+== Credit
+
+  Trans [Implementation]
+  George Moschovitis [Original Concept]
+  Ara T. Howard [Suggestions]
+
+== License
+
+Copyright (c) 2004-2007 Thomas Sawyer, George Moschovitis
+
+Distributed under the Ruby/GPL dual-license.
+

data/doc/manual/associations.rdoc

@@ -0,0 +1,55 @@
+= Facets Structures
+
+http://facets.rubyforge.org
+
+Facets Structures is a collection of data structure libraries..
+
+== Libraries
+
+=== Associations
+
+Gerenal binary association allows one object to be
+associated with another. It has a variety of uses,
+link-lists, simple ordered maps and mixed collections,
+among them.
+
+Associations can be used to draw simple relationships.
+
+  :Apple >> :Fruit
+  :Apple >> :Red
+  :Apple.associations #=> [ :Fruit, :Red ]
+
+It can also be used for simple lists of ordered pairs.
+
+  c = [ :a >> 1, :b >> 2 ]
+  c.each { |k,v| puts "#{k} associated with #{v} }
+
+produces
+
+  a associated with 1
+  b associated with 2
+
+The method :>> is used to construct the association.
+It is a rarely used method so it is generally available.
+But you can't use an Association while extending
+any of the following classes becuase they use #>> for
+other things.
+
+  Bignum
+  Fixnum
+  Date
+  IPAddr
+  Process::Status
+
+
+== Documentation
+
+Please see web/doc/ directory for additional documentation.
+
+
+== License
+
+Facets
+Copyright (c) 2004-2007 Thomas Sawyer
+Distributed under the Ruby/GPL dual-license.
+

data/doc/manual/blockups.rdoc

@@ -0,0 +1,101 @@
+= Buildable
+
+Block builder system.
+
+by Trans
+
+http://facets.rubyforge.org
+
+
+== Synopsis
+
+Buildable provides a library for creating your own block builders.
+
+
+== Example
+
+   require 'facets/buildable'
+   require 'xmlhelper'
+
+   module XMLHelper
+     include Buildable
+     alias :build :element
+   end
+
+   doc = XMLHelper.build do
+     html do
+       head do
+         title "Test"
+       end
+       body do
+         i "Hello"
+         br
+         text "Test"
+         text "Hey"
+       end
+     end
+   end
+
+   doc.to_s
+
+_produces_
+
+   <html><head><title>Test</title><body><i>Hello</i><br />TestHey</body></html>
+
+The Buildable module is based on BuildingBlock class. The same effect can be achieved using it directly:
+
+   require 'facets'
+   require 'xmlhelper'
+
+   builder = BuildingBlock.new(XMLHelper, :element)
+
+   doc = builder.html do
+     head do
+       title "Test"
+     end
+     body do
+       i "Hello"
+       br
+       text "Test"
+       text "Hey"
+     end
+   end
+
+   doc.to_s
+
+
+== Installation
+
+IMPORTANT! This library is included in the complete facets package. You do not this library if you already have facets installed. 
+
+You can install either via gem:
+
+  gem install buildable
+
+or manually via tarball:
+
+  wget http://rubyforge.org/frs/download.php/.../buildable-x.x.x.tgz
+  cd buildable-x.x.x
+  sudo util/setup
+
+
+== Documentation
+
+Please see doc/ directory for additional documentation.
+
+
+== Upcoming Features
+
+Better support for alternate output buffers.
+
+
+== Credit
+
+  Trans
+
+
+== License
+
+Copyright (c) 2004-2007 Thomas Sawyer
+
+Distributed under the Ruby/GPL dual-license.

data/doc/manual/capsule.rdoc

@@ -0,0 +1,34 @@
+= Facets Modeling
+
+Facets Modeling is a collection of libraries to assist in object-oriented
+modeling.
+
+== Libraries
+
+=== Capsule
+
+A module which is an instance of the Capsule class encapsulates in its scope
+the top-level methods, top-level constants, and instance variables defined in
+a ruby script file (and its subfiles) loaded by a ruby program. This allows
+use of script files to define objects that can be loaded into a program in
+much the same way that objects can be loaded from YAML or Marshal files.
+
+See intro.txt[link:files/intro_txt.html] for an overview.
+
+
+== Contact
+
+  facets-universal@rubyforge.org
+
+
+== Install
+
+  gem install facets
+
+
+== License
+
+  Facets
+  Copyright (c) 2004 Thomas Sawyer
+  Ruby License
+

data/doc/manual/command.rdoc

@@ -0,0 +1,177 @@
+= Command
+
+Command provides a clean and easy way to create a command
+line interface for your program. The unique technique
+utlizes a Commandline to Object Mapping (COM) to make
+it quick and easy.
+
+== Synopsis
+
+Let's make an executable called 'mycmd'.
+
+  #!/usr/bin/env ruby
+
+  require 'facets/console/command'
+
+  class MyCmd < Console::Command
+
+    def _v
+      $VERBOSE = true
+    end
+
+    def jump
+      if $VERBOSE
+        puts "JUMP! JUMP! JUMP!"
+      else
+        puts "Jump"
+      end
+    end
+
+  end
+
+  MyCmd.execute
+
+Then on the command line:
+
+  % mycmd jump
+  Jump
+
+  % mycmd -v jump
+  JUMP! JUMP! JUMP!
+
+== Subcommands
+
+Commands can take subcommand and suboptions. To do this
+simply add a module to your class with the same name
+as the subcommand, in which the suboption methods are defined.
+
+  MyCmd << Console::Command
+
+    def initialize
+      @height = 1
+    end
+
+    def _v
+      $VERBOSE = true
+    end
+
+    def jump
+      if $VERBOSE
+        puts "JUMP!" * @height
+      else
+        puts "Jump" * @height
+      end
+    end
+
+    module Jump
+      def __height(h)
+        @height = h.to_i
+      end
+    end
+
+  end
+
+  MyCmd.start
+
+Then on the command line:
+
+  % mycmd jump -h 2
+  Jump Jump
+
+  % mycmd -v jump -h 3
+  JUMP! JUMP! JUMP!
+
+Another thing to notice about this example is that #start is an alias
+for #execute.
+
+== Missing Subcommands
+
+You can use #method_missing to catch missing subcommand calls.
+
+== Main and Default
+
+If your command does not take subcommands then simply define
+a #main method to dispatch action. All options will be treated globablly
+in this case and any remaining comman-line arguments will be passed
+to #main.
+
+If on the other hand your command does take subcommands but none is given,
+the #default method will be called, if defined. If not defined
+an error will be raised (but only reported if $DEBUG is true).
+
+== Global Options
+
+You can define <i>global options</i> which are options that will be
+processed no matter where they occur in the command line. In the above
+examples only the options occuring before the subcommand are processed
+globally. Anything occuring after the subcommand belonds strictly to
+the subcommand. For instance, if we had added the following to the above
+example:
+
+  global_option :_v
+
+Then -v could appear anywhere in the command line, even on the end,
+and still work as expected.
+
+  % mycmd jump -h 3 -v
+
+== Missing Options
+
+You can use #option_missing to catch any options that are not explicility
+defined.
+
+The method signature should look like:
+
+  option_missing(option_name, args)
+
+Example:
+  def option_missing(option_name, args)
+    p args if $debug
+    case option_name
+      when 'p'
+        @a = args[0].to_i
+        @b = args[1].to_i
+        2
+      else
+        raise InvalidOptionError(option_name, args)
+    end
+  end
+
+Its return value should be the effective "arity" of that options -- that is,
+how many arguments it consumed ("-p a b", for example, would consume 2 args:
+"a" and "b"). An arity of 1 is assumed if nil or false is returned.
+
+Be aware that when using subcommand modules, the same option_missing
+method will catch missing options for global options and subcommand
+options too unless an option_missing method is also defined in the
+subcommand module.
+
+== Help Documentation
+
+You can also add help information quite easily. If the following code
+is saved as 'foo' for instance.
+
+  MyCmd << Console::Command
+
+    help "Dispays the word JUMP!"
+
+    def jump
+      if $VERBOSE
+        puts "JUMP! JUMP! JUMP!"
+      else
+        puts "Jump"
+      end
+    end
+
+  end
+
+  MyCmd.execute
+
+then by running 'foo help' on the command line, standard help information
+will be displayed.
+
+  foo
+
+    jump  Displays the word JUMP!
+
+