facets 2.7.0 → 2.8.0

data/doc/manual/command.rdoc

@@ -1,177 +0,0 @@
-= 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!
-
-

data/doc/manual/core.rdoc

@@ -1,37 +0,0 @@
-= Facets Core
-
-Core contains the *essentials* of Facets. Core consists of a number
-of generally useful core extension methods, and a couple small support
-classes.
-
-By definition Core contains anything that will load automatically when
-issuing:
-
-  require 'facets'
-
-== Facets by the Method
-
-In the 1.0 series of Facets, all extensions were stored on a per-method
-basis. This had some advantages, organization and complete fine-grain control
-over requires was possible, but it proved in practice to be _too_ granular.
-Some method simply too close in nature, or dependency, to go without others.
-
-So version 2.0 has grouped the extensions method into small groups.
-The library is still highly granular, but not excessively. But there's
-still refinement being done in this regard. You need not worry about it
-though, becuase per-method redirect libraries are provided. This is useful,
-not only for backward compatability, but also if you know what method you
-want, but don't recall exactly which core file it is in.
-
-Here's an example:
-
-  require 'facets-by-method/hash/collate'
-
-== Authors
-
-This library more than any other part of Facets is full of contributions
-from sources all across the Ruby community. For all who have code here,
-the Facets Team salutes you.
-
-For a list of names, look to the README in Facet's main documetation.
-

data/doc/manual/faq.rdoc

@@ -1,32 +0,0 @@
-= Facets FAQs
-
-Q. How do I use the core mixins on object-by-object basis?
-
-A. One way is to use Facets' Capsule library.
-
-     require 'facets/capsule'
-
-     MyStringExts = Capsule.load('facets/string/align')::String
-
-     s = "string"
-
-     s.extend(MyStringExts)
-
-     s.align_right(10)  #=> "    string"
-
-Or handle it using in-module load methods. 
-
-     require 'facets/module/require'
-
-     module MyStringExts
-       module_load 'facets/string/align'
-       include String
-     end
-
-     s = "string"
-
-     s.extend(MyStringExts)
-
-     s.align_right(10)  #=> "    string"
-
-

data/doc/manual/typecast.html

@@ -1,112 +0,0 @@
-<html>
-
-<head>
-  <title>Facets Typecast</title>
-
-  <style>
-    body { font: 12pt sans-serif; 
-      padding: 0; margin: 0;
-    }
-    #container {
-      margin: 0 auto;
-    }
-    #title {
-      color: #dddddd;
-      border-bottom: 1px solid gray;
-      padding: 20px;
-    }
-    #project {
-      font: 22pt sans-serif;
-      color: black;
-    }
-    #package {
-      font: bold 42pt sans-serif;
-      color: red;
-    }
-    #corpus {
-      padding: 20px;
-    }
-  </style>
-</head>
-
-<body>
-<div id="container">
-
-  <div id="title">
-    <div id="project">Facets</div>
-    <div id="package">Typecast</div>
-  </div>
-
-  <div id="corpus">
-    <h2>Overview</h2>
-    <p>Typecast provides a simple generic type conversion system. All the ruby core
-    conversions are available by default.</p>
-
-    <p>To implement a new type conversion, you have two choices. Given:</p>
-
-     <pre>
-      class CustomType
-        def initialize(my_var)
-          @my_var = my_var
-        end
-      end
-     </pre>
-
-     <p> 1) Define a to_class_name instance method </p>
-
-    <pre>
-      class CustomType
-        def to_string
-          my_var.to_s
-        end
-      end
-
-      c = CustomType.new 1234
-      s.cast_to String   =>  "1234" (String)
-    </pre>
-
-    <p> 2. Define a from_class_name class method </p>
-
-    <pre>
-      class CustomType
-        def self.from_string(str)
-          self.new(str)
-        end
-      end
-
-      "1234".cast_to CustomType  =>  #<CustomType:0xb7d1958c @my_var="1234">
-    </pre>
-
-    <p>Those two methods are equivalent in the result. It was coded like that to
-    avoid the pollution of core classes with tons of to_* methods.</p>
-
-    <p>The standard methods to_s, to_f, to_i, to_a and to_sym are also used by
-    this system if available.</p>
-
-    <p>Usage looks like</p>
-
-    <pre>
-      "1234".cast_to Float     => 1234.0  (Float)
-      Time.cast_from("6:30")   => 1234.0   (Time)
-    </pre>
-
-    <h2>FAQ</h2>
-
-    <p>Why didn't you name the `cast_to` method to `to` ?</p>
-
-    <p>Even if it would make the syntax more friendly, I suspect it could cause
-    a lot of collisions with already existing code. The goal is that each
-    time you call cast_to, you either get your result, either a
-    TypeCastException.</p>
-  </div>
-
-  <div id="copy">
-    Copyright &copy; 2004 Thomas Sawyer and all respective authors.
-    Ruby License
-  </div>
-
-</div>
-</body>
-
-</html>
-

data/lib/more/facets/capsule.rb

@@ -1,258 +0,0 @@
-# = Capsule
-#
-# A Capsule is subclass of Module. It encapsulates an extenal script
-# as a funcitons module.
-#
-# 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.
-#
-# == Authors
-#
-# * Joel VanderWerf
-# * Thomas Sawyer
-#
-# == Todo
-#
-# * The name of this is rather weak. Think of a better one.
-#
-# == Copying
-#
-# Copyright (c) 2005 Thomas Sawyer, Joel VanderWerf
-#
-# Ruby License
-#
-# This module is free software. You may use, modify, and/or redistribute this
-# software under the same terms as Ruby.
-#
-# This program 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.
-
-#require 'rbconfig'
-
-# = Capsule
-#
-# A Capsule is subclass of Module. It encapsulates an extenal script
-# as a funcitons module.
-#
-# 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.
-
-class Capsule < Module
-
-  #DLEXT = Config::CONFIG['DLEXT']
-
-  # The script file with which the Import was instantiated.
-  attr_reader :main_file
-
-  # The directory in which main_file is located, and relative to which
-  # #load searches for files before falling back to Kernel#load.
-  #attr_reader :dir
-
-  # An array of paths to search for scripts. This has the same
-  # semantics as <tt>$:</tt>, alias <tt>$LOAD_PATH</tt>, excpet
-  # that it is local to this script. The path of the current
-  # script is added automatically (equivalent to '.')
-  attr_reader :load_path
-
-  # A hash that maps <tt>filename=>true</tt> for each file that has been
-  # required locally by the script. This has the same semantics as <tt>$"</tt>,
-  # alias <tt>$LOADED_FEATURES</tt>, except that it is local to this script.
-  attr_reader :loaded_features
-
-  class << self
-    # As with #new but will search Ruby's $LOAD_PATH first.
-    #--
-    # Will also try .rb, .so, .dll, et al extensions, like require does.
-    #++
-    def load(main_file, options=nil, &block)
-      file = nil
-      $LOAD_PATH.each do |path|
-        break if file = File.file?(File.join(path, main_file))
-        #break if file = Dir.glob(File.join(path, main_file)+'{,.rb,.'+DLEXT+'}')[0]
-      end
-      new(file || main_file, options=nil, &block)
-    end
-  end
-
-  # Creates new Capsule, and loads _main_file_ in the scope of the script. If a
-  # block is given, the script is passed to it before loading from the file, and
-  # constants can be defined as inputs to the script.
-
-  def initialize(main_file, options=nil, &block)
-    extend self
-
-    options ||= {}
-
-    @main_file       = File.expand_path(main_file)
-    @load_path       = options[:load_path] || []
-    #@load_path |= [File.dirname(@main_file)]  # before or after?
-    @loaded_features = options[:loaded_features] || {}
-
-    # TODO In order to load/require at the instance level.
-    # This needs to be in a separate namespace however
-    # b/c it can interfere with what is expected.
-    #[ :require, :load ].each{ |meth|
-    #  m = method(meth)
-    #  define_method(meth) do |*args| m.call(*args) end
-    #}
-
-    module_eval(&block) if block
-    extend self
-
-    load_in_module(main_file)
-  end
-
-  # Lookup feature in load path.
-
-  def load_path_lookup(feature)
-    paths = File.join('{' + @load_path.join(',') + '}', feature + '{,.rb,.rbs}')
-    files = Dir.glob(paths)
-    match = files.find{ |f| ! @loaded_features.include?(f) }
-    return match
-  end
-
-  # Loads _file_ into the capsule. Searches relative to the local dir, that is,
-  # the dir of the file given in the original call to
-  # <tt>Capsule.load(file)</tt>, loads the file, if found, into this Capsule's
-  # scope, and returns true. If the file is not found, falls back to
-  # <tt>Kernel.load</tt>, which searches on <tt>$LOAD_PATH</tt>, loads the file,
-  # if found, into global scope, and returns true. Otherwise, raises
-  # <tt>LoadError</tt>.
-  #
-  # The _wrap_ argument is passed to <tt>Kernel.load</tt> in the fallback case,
-  # when the file is not found locally.
-  #
-  # Typically called from within the main file to load additional sub files, or
-  # from those sub files.
-  #
-  #--
-  # TODO Need to add load_path lookup.
-  #++
-
-  def load(file, wrap = false)
-    load_in_module(File.join(@dir, file))
-    true
-  rescue MissingFile
-    super
-  end
-
-  # Analogous to <tt>Kernel#require</tt>. First tries the local dir, then falls
-  # back to <tt>Kernel#require</tt>. Will load a given _feature_ only once.
-  #
-  # Note that extensions (*.so, *.dll) can be required in the global scope, as
-  # usual, but not in the local scope. (This is not much of a limitation in
-  # practice--you wouldn't want to load an extension more than once.) This
-  # implementation falls back to <tt>Kernel#require</tt> when the argument is an
-  # extension or is not found locally.
-  #
-  #--
-  # This was using load_in_module rather than include_script. Maybe is still should
-  # and one should have to call include_script instead? Think about this.
-  #++
-
-  def require(feature)
-    file = load_path_lookup(feature)
-    return super unless file
-    begin
-      @loaded_features[file] = true
-      load_in_module(file)
-    rescue MissingFile
-      @loaded_features[file] = false
-      super
-    end
-  end
-
-  # Raised by #load_in_module, caught by #load and #require.
-  class MissingFile < LoadError; end
-
-  # Loads _file_ in this module's context. Note that <tt>\_\_FILE\_\_</tt> and
-  # <tt>\_\_LINE\_\_</tt> work correctly in _file_.
-  # Called by #load and #require; not normally called directly.
-
-  def load_in_module(file)
-    module_eval(IO.read(file), File.expand_path(file))
-  rescue Errno::ENOENT => e
-    if /#{file}$/ =~ e.message
-      raise MissingFile, e.message
-    else
-      raise
-    end
-  end
-
-  def include_script(file)
-    include self.class.new(file, :load_path=>load_path, :loaded_features=>loaded_features)
-  rescue Errno::ENOENT => e
-    if /#{file}$/ =~ e.message
-      raise MissingFile, e.message
-    else
-      raise
-    end
-  end
-
-  #
-  def include(*mods)
-    super
-    extend self
-  end
-
-  def to_s # :nodoc:
-    "#<#{self.class}:#{main_file}>"
-  end
-
-end
-
-# TODO Is autoimport bets name for this?
-
-class Module
-
-  const_missing_definition_for_autoimport = lambda do
-    #$autoimport_activated = true
-    alias const_missing_before_autoimport const_missing
-
-    def const_missing(sym) # :nodoc:
-      filename = @autoimport && @autoimport[sym]
-      if filename
-        mod = Import.load(filename)
-        const_set sym, mod
-      else
-        const_missing_before_autoimport(sym)
-      end
-    end
-  end
-
-  # When the constant named by symbol +mod+ is referenced, loads the script
-  # in filename using Capsule.load and defines the constant to be equal to the
-  # resulting Capsule module.
-  #
-  # Use like Module#autoload--however, the underlying opertation is #load rather
-  # than #require, because scripts, unlike libraries, can be loaded more than
-  # once. See examples/autoscript-example.rb
-
-  define_method(:autoimport) do |mod, file|
-    if @autoimport.empty? #unless $autoimport_activated
-      const_missing_definition_for_autoimport.call
-    end
-    (@autoimport ||= {})[mod] = file
-  end
-end
-
-
-module Kernel
-
-  # Calls Object.autoimport
-  def autoimport(mod, file)
-    Object.autoimport(mod, file)
-  end
-
-end