rubyment 0.6.25540755 → 0.6.25563758

data/lib/rubyment.rb

@@ -1,6 +1,14 @@
 #!/usr/bin/env ruby
 
 
+=begin
+  # begin_documentation
+  TrueClass will be changed just by including
+  this file or requiring rubyment, which is not the
+  best approach, but kept to respect the open/closed
+  principle, but new functions should be added here.
+  # end_documentation
+=end
 class TrueClass
   # returns +false+ (purpose of simplifying
   # functional programming)
@@ -10,6 +18,20 @@ class TrueClass
 end
 
 
+=begin
+  # begin_documentation
+  Object will be changed just by including
+  this file or requiring rubyment, which is not the
+  best approach, but kept to respect the open/closed
+  principle, but new functions should be added here.
+
+  only a bunch of methods, is, however, added:
+  . negate_me
+  . to_nil
+  . nne
+
+  # end_documentation
+=end
 class Object
   # returns +self+ if +self+ is not considered
   # to be the neutral element of its class.
@@ -44,53 +66,804 @@ class Object
   end
 
 
-  # returns nil out of an object.
-  # usage examples:
-  # "this_parameter_is_nil".to_nil
-  def to_nil
-    nil
-  end
+  # returns nil out of an object.
+  # usage examples:
+  # "this_parameter_is_nil".to_nil
+  def to_nil
+    nil
+  end
+
+
+  # returns +!self+, unless +unless_condition+
+  # is +true+; in such case returns +self+.
+  # e.g: +false.negate_me true+ returns
+  # +false+.
+  # (by default, if no params are given,
+  # just # negates +self+)
+  # experiment
+  # [1, 2, nil, 3, nil, 4].select &:negate_me
+  # to find the nil elements in an array
+  def negate_me condition=true
+    (condition) && (
+      !self
+    ) || (!condition) && (
+      self
+    )
+  end
+end
+
+
+=begin
+  # begin_documentation
+  This module receives functions that are being worked on.
+  # end_documentation
+=end
+module RubymentExperimentModule
+
+
+=begin
+  alias for #bled
+=end
+  def experiment__bled args=[], &block
+    bled args, &block
+  end
+
+
+=begin
+
+  # documentation_begin
+  # short_desc = "tests the function #call_or_itself"
+  @memory[:documentation].push = {
+    :function   => :call_or_itself,
+    :short_desc => short_desc,
+    :description => "calls the method #call of an object, or return the object itself",
+    :params     => [
+      {
+        :name             => :args,
+        :description      => "list of parameters",
+        :duck_type        => Array,
+        :default_behavior => [],
+        :params           => [
+          {
+            :name             => :object,
+            :duck_type        => Object,
+            :default_behavior => :nil,
+            :description      => "object to be called, if responds to #call, or to return itself",
+          },
+          {
+            :name             => :return_dont_call,
+            :duck_type        => Object,
+            :default_behavior => :nil,
+            :description      => "forces an object to return itself even when it reponds to #call",
+          },
+          {
+            :name             => :debug,
+            :duck_type        => Object,
+            :default_behavior => :nil,
+            :description      => "prints debug information to the __IO__ specified by __@memory[:stderr]__ (STDERR by default)",
+          },
+          {
+            :name             => :reserved,
+            :duck_type        => Object,
+            :default_behavior => :nil,
+            :description      => "for future use",
+          },
+        ],
+      },
+    ],
+    :return_value     => [
+      {
+        :name             => :args,
+        :description      => "list of parameters",
+        :duck_type        => Array,
+        :default_behavior => [],
+        :params           => [
+          {
+            :name             => :reserved,
+            :duck_type        => Object,
+            :default_behavior => :nil,
+            :description      => "for future use",
+          },
+        ],
+      },
+    ],
+  }
+  # documentation_end
+
+=end
+  def call_or_itself args=[]
+    stderr = @memory[:stderr]
+    object,
+      return_dont_call,
+      debug,
+      reserved = args
+    debug = debug.nne
+    debug && (stderr.puts "{#{__method__} starting")
+    debug && (stderr.puts "args=#{args.inspect}")
+    will_call = (object.respond_to? :call) && return_dont_call.negate_me
+    debug && (stderr.puts "will_call=#{will_call.inspect}")
+    will_call && (rv = object.call)
+    debug && (stderr.puts "provisory return value: #{rv.inspect}")
+    will_call.negate_me && (rv = object)
+    debug && (stderr.puts "will return #{rv.inspect}")
+    debug && (stderr.puts "#{__method__} returning}")
+    rv
+  end
+
+
+=begin
+  # documentation_begin
+  # short_desc = "tests the function #experiment__whether"
+  @memory[:documentation].push = {
+    :function   => :experiment__whether,
+    :short_desc => short_desc,
+    :description => "",
+    :params     => [
+      {
+        :name             => :args,
+        :description      => "list of parameters",
+        :duck_type        => Array,
+        :default_behavior => [],
+        :params           => [
+          {
+            :name             => :condition,
+            :duck_type        => :boolean,
+            :default_behavior => :nil,
+            :description      => "any condition, used to decided which parameter will be run",
+          },
+          {
+            :name             => :run_if_true,
+            :duck_type        => Proc,
+            :default_behavior => :nil,
+            :description      => "block will be called if condition is true",
+          },
+          {
+            :name             => :run_if_false,
+            :duck_type        => Proc,
+            :default_behavior => :nil,
+            :description      => "block will be called if condition is true",
+          },
+          {
+            :name             => :return_dont_run,
+            :duck_type        => Array,
+            :default_behavior => [],
+            :description      => "forces blocks from being called. first element prevents the return_if_true block to be called (so the object return_if_true is returned). the second applies to run_if_false",
+          },
+          {
+            :name             => :debug,
+            :duck_type        => Object,
+            :default_behavior => :nil,
+            :description      => "prints debug information to the __IO__ specified by __@memory[:stderr]__ (STDERR by default)",
+          },
+          {
+            :name             => :reserved,
+            :duck_type        => Object,
+            :default_behavior => :nil,
+            :description      => "for future use",
+          },
+        ],
+      },
+    ],
+    :return_value     => [
+      {
+        :name             => :rv,
+        :description      => "value returned by the block run",
+        :duck_type        => Object,
+        :default_behavior => :nil,
+      },
+    ],
+  }
+  # documentation_end
+=end
+
+  def experiment__whether args=[]
+    stderr = @memory[:stderr]
+    condition,
+      run_if_true,
+      run_if_false,
+      return_dont_run,
+      debug,
+      reserved = args
+    debug = debug.nne
+    debug && (stderr.puts "{#{__method__} starting")
+    debug && (stderr.puts "args=#{args.inspect}")
+    return_don_run_true  = (containerize return_dont_run)[0]
+    return_don_run_false = (containerize return_dont_run)[1]
+    debug && (stderr.puts "[return_don_run_true, return_don_run_false]=#{[return_don_run_true, return_don_run_false].inspect}")
+    condition && (rv = call_or_itself [run_if_true, return_don_run_true])
+    debug && (stderr.puts "provisory return value: #{rv.inspect}")
+    condition.negate_me && (rv = call_or_itself [run_if_false, return_don_run_false])
+    debug && (stderr.puts "will return #{rv.inspect}")
+    debug && (stderr.puts "#{__method__} returning}")
+    rv
+  end
+
+
+=begin
+  # documentation_begin
+  # short_desc = "tests the function #experiment__tester"
+  @memory[:documentation].push = {
+    :function   => :experiment__tester,
+    :short_desc => short_desc,
+    :description => "",
+    :params     => [
+      {
+        :name             => :args,
+        :description      => "list of parameters",
+        :duck_type        => Array,
+        :default_behavior => [],
+        :params           => [
+          {
+            :name             => :test_cases,
+            :duck_type        => Array,
+            :default_behavior => :[],
+            :description      => "Array having the fields: __test_id__, __test_expected_value__ and __actual_params__. __actual_params__ is an __Array__ having  as first member __method_name__ to be called, and all its remaining args __method_args__ (a __splat__) will be given to __method_name__",
+          },
+          {
+            :name             => :debug,
+            :duck_type        => Object,
+            :default_behavior => :nil,
+            :description      => "prints debug information to the __IO__ specified by __@memory[:stderr]__ (STDERR by default)",
+          },
+          {
+            :name             => :reserved,
+            :duck_type        => Object,
+            :default_behavior => :nil,
+            :description      => "for future use",
+          },
+        ],
+      },
+    ],
+    :return_value     => [
+      {
+        :name             => :args,
+        :description      => "__true__ if tests were successful, __false__ otherwise",
+        :duck_type        => :boolean,
+      },
+    ],
+  }
+  # documentation_end
+=end
+  def experiment__tester args=[]
+    stderr = @memory[:stderr]
+    test_cases,
+      debug,
+      reserved = args
+
+    debug = debug.nne
+    debug && (stderr.puts "{#{__method__} starting")
+    debug && (stderr.puts "caller=#{caller_label.inspect}")
+    debug && (stderr.puts backtrace)
+    debug && (stderr.puts "args=#{args.inspect}")
+    test_cases = test_cases.nne [
+     # [ :id, :expectation, :actual_params ],
+     # :actual_params: array with :method_name + :method_args
+    ]
+    expectation = {}
+    actual = {}
+    debug && (stderr.puts "test_cases.size=#{test_cases.size}")
+    test_cases.each_with_index{ |test_case|
+      debug && (stderr.puts "test_case=[test_case_id, test_expectation, actual_params]=#{test_case.inspect}")
+      test_case_id, test_expectation, actual_params = test_case
+      actual_params_method_name,
+        *actual_params_method_args = actual_params
+      debug && (stderr.puts "will send: #{actual_params_method_name.to_s}(*#{actual_params_method_args.inspect})")
+      result = send actual_params_method_name, *actual_params_method_args
+      expectation[test_case_id] = test_expectation
+      actual[test_case_id] = result
+    }
+    judgement = actual.keys.map {|test_case|
+      [expectation[test_case], actual[test_case] , test_case]
+    }.map(&method("expect_equal")).all?
+
+    rv = judgement
+    debug && (stderr.puts "will return #{rv.inspect}")
+    debug && (stderr.puts "#{__method__} returning}")
+    rv
+  end
+
+
+=begin
+=end
+  def experiment__send_array_base args=[]
+    sender,
+      object_to_send,
+      destination,
+      debug,
+      shallow,
+      args_to_bled,
+      send_to_self,
+      reserved = args
+
+    stderr = @memory[:stderr]
+    debug = debug.nne
+debug = 1
+    debug && (stderr.puts "{#{__method__} starting")
+    debug && (stderr.puts "args=#{args.inspect}")
+    debug && (stderr.puts "debug=#{args[3].inspect}")
+
+    method_to_send,
+      *args_to_send = sender
+    debug && (stderr.puts "general case{: #{object_to_send.inspect}.#{method_to_send.inspect}(#{args_to_send.inspect}) }")
+
+    send_block = bled(args_to_bled) {
+      object_to_send.send method_to_send, *args_to_send
+    }.first
+
+    default_block = bled(args_to_bled) {
+      args_to_send
+    }.first
+
+    rv = experiment__whether [
+      method_to_send,
+      send_block,
+      default_block,
+    ]
+
+    debug && (stderr.puts "will return #{rv.inspect}")
+    debug && (stderr.puts "#{__method__} returning}")
+    rv
+  end
+
+
+end
+
+
+=begin
+  # begin_documentation
+  This module receives only functions that are maintained.
+  Ie, the non-deprecated or not under deprecation functions.
+  # end_documentation
+=end
+module RubymentMaintainedModule
+
+
+=begin 
+  # documentation_begin
+  # short_desc = "tests the function #exception_info_base"
+  @memory[:documentation].push = {
+    :function   => :exception_info_base,
+    :short_desc => short_desc,
+    :description => "",
+    :params     => [
+      {
+        :name             => :args,
+        :description      => "list of parameters",
+        :duck_type        => Array,
+        :default_behavior => [],
+        :params           => [
+          {
+            :name             => :exception,
+            :duck_type        => Exception,
+            :default_behavior => nil,
+            :description      => "exception to extract info from",
+          },
+          {
+            :name             => :max_str_index,
+            :duck_type        => FixNum,
+            :default_behavior => -1,
+            :description      => "limit the full string output to this last index",
+          },
+          {
+            :name             => :reserved,
+            :duck_type        => Object,
+            :default_behavior => nil,
+            :description      => "reserved for future use",
+          },
+        ],
+      },
+    ],
+    :return_value     => [
+      {
+        :name             => :short,
+        :duck_type        => String,
+        :default_behavior => "",
+        :description      => "a brief about the exception; normally an exception message",
+      },
+      {
+        :name             => :full,
+        :duck_type        => String,
+        :default_behavior => "",
+        :description      => "all the information about the exception; normally an exception message, backtrace, class and inspection",
+      },
+      {
+        :name             => :inspection,
+        :duck_type        => String,
+        :default_behavior => "",
+        :description      => "the  exception inspection",
+      },
+      {
+        :name             => :backtrace,
+        :duck_type        => Object,
+        :duck_type        => [:_a, Array, :strings],
+        :description      => the exception bactrace",
+      },
+      {
+        :name             => :message,
+        :duck_type        => String,
+        :default_behavior => "",
+        :description      => "the  exception message",
+      },
+      {
+        :name             => :class_,
+        :duck_type        => String,
+        :default_behavior => "",
+        :description      => "the  exception class",
+      },
+      {
+        :name             => :reserved,
+        :duck_type        => Object,
+        :default_behavior => nil,
+        :description      => "reserved for future use",
+      },
+    ],
+  }
+  # documentation_end
+=end
+  def exception_info_base args=[]
+    exception,
+      max_str_index,
+      reserved = args
+    inspection = exception.inspect
+    backtrace = exception.backtrace
+    class_ = exception.class
+    message = exception.message,
+    short = message
+    full = (
+      [
+        "message{",
+        message,
+        "}",
+        "backtrace{",
+      ] +
+      backtrace.to_a +
+      [
+        "}",
+        "class{",
+        class_,
+        "}",
+        "}",
+        "inspection{",
+        inspection,
+        "}",
+      ]
+    ).join "\n"
+
+    full = string_truncate [
+      full,
+      max_str_index,
+    ]
+    [short, full, inspection, backtrace, message, class_]
+  end
+
+
+=begin
+  # documentation_begin
+  # short_desc = "tests the function #bled"
+  @memory[:documentation].push = {
+    :function   => :bled,
+    :short_desc => short_desc,
+    :description => "",
+    :params     => [
+      {
+        :name             => :args,
+        :description      => "list of parameters (splat)",
+        :duck_type        => splat,
+        :default_behavior => [],
+        :params           => [
+          {
+            :name             => :default_on_exception,
+            :duck_type        => Object,
+            :default_behavior => :nil,
+            :description      => "if an exception happens, this value will be returned in the first element of the return value",
+          },
+          {
+            :name             => :dont_rescue,
+            :duck_type        => Object,
+            :default_behavior => :nil,
+            :description      => "do not rescue exceptions",
+          },
+          {
+            :name             => :output_backtrace,
+            :duck_type        => Object,
+            :default_behavior => :nil,
+            :description      => "output when an exception happens",
+          },
+          {
+            :name             => :backtrace_max_str_len,
+            :duck_type        => FixNum,
+            :default_behavior => :nil,
+            :description      => "backtrace outputs can be long, use this to limit it",
+          },
+          {
+            :name             => :debug,
+            :duck_type        => Object,
+            :default_behavior => :nil,
+            :description      => "prints debug information to the __IO__ specified by __@memory[:stderr]__ (STDERR by default)",
+          },
+          {
+            :name             => :reserved,
+            :duck_type        => Object,
+            :default_behavior => :nil,
+            :description      => "for future use",
+          },
+        ],
+      },
+    ],
+    :return_value     => [
+      {
+        :name             => :args,
+        :description      => "list of parameters",
+        :duck_type        => Array,
+        :default_behavior => [],
+        :params           => [
+          {
+            :name             => :actual_block_return,
+            :duck_type        => Object,
+            :default_behavior => :nil,
+            :description      => "the actual return value of the block call",
+          },
+          {
+            :name             => :exception_info,
+            :duck_type        => Array,
+            :default_behavior => [],
+            :description      => "exception info if an exception happened, as returned by :exception_information_base",
+          },
+          {
+            :name             => :exception,
+            :duck_type        => Exception,
+            :default_behavior => :nil,
+            :description      => "the exception that happened, if any",
+          },
+          {
+            :name             => :reserved,
+            :duck_type        => Object,
+            :default_behavior => :nil,
+            :description      => "for future use",
+          },
+        ],
+      },
+    ],
+  }
+  # documentation_end
+=end
+  def bled args=[], &block
+    stderr = @memory[:stderr]
+    default_on_exception,
+      dont_rescue,
+      output_backtrace,
+      backtrace_max_str_len,
+      debug,
+      reserved = args
+    debug = debug.nne
+    debug && (stderr.puts "{#{__method__} starting")
+    debug && (stderr.puts "args=#{args.inspect}")
+    block ||= lambda {|*block_args|}
+    rv = Proc.new { |*block_args|
+      (debug || output_backtrace) && (stderr.puts "{#{__method__} block starting")
+      (debug || output_backtrace) && (stderr.puts "block_args=#{block_args.inspect}")
+      brv = begin
+        [ (block.call *block_args), nil, nil]
+      rescue => e
+        e_info = exception_info_base [
+          e,
+          backtrace_max_str_len
+        ]
+        (debug || output_backtrace) && (stderr.puts "#{__method__} block: #{block.inspect}\nfull exception info:\n#{e_info[1]}")
+        (debug || output_backtrace) && (stderr.puts "#{__method__} block: dont_rescue=#{dont_rescue}; true means will rethrow")
+        dont_rescue && (raise e)
+        [ default_on_exception, e_info, e ]
+      end
+      (debug || output_backtrace) && (stderr.puts "block #{block.inspect} will return #{brv.inspect}")
+      (debug || output_backtrace)  && (stderr.puts "#{__method__} block returning}")
+      brv
+    }
+    rv = [ rv ]
+    debug && (stderr.puts "will return #{rv.inspect}")
+    debug && (stderr.puts "#{__method__} returning}")
+    rv
+  end
+
+
+=begin
+  # documentation_begin
+  # short_desc = "tests the function #string_truncate"
+  @memory[:documentation].push = {
+    :function   => :string_truncate,
+    :short_desc => short_desc,
+    :description => "",
+    :params     => [
+      {
+        :name             => :args,
+        :description      => "list of parameters",
+        :duck_type        => Array,
+        :default_behavior => [],
+        :params           => [
+          {
+            :name             => :max_str_index,
+            :duck_type        => FixNum,
+            :default_behavior => -1,
+            :description      => "index (not size) where to truncate the string (this is the index of the last char)",
+          },
+          {
+            :name             => :reticenses,
+            :duck_type        => String,
+            :default_behavior => "...",
+            :description      => "string to attach to the result when the resulting string is smaller than the original one (ie, has actually been truncated)",
+          },
+        ],
+      },
+    ],
+    :return_value     => 
+      {
+        :name             => :truncated_string,
+        :description      => "truncated string",
+        :duck_type        => String,
+        :default_behavior => :str,
+      },
+    
+  }
+  # documentation_end
+=end
+  def string_truncate args=[]
+    str,
+      max_str_index,
+      reticenses,
+      reserved = args
+    output_max_str_index = @memory[:output_max_str_index]
+    output_max_str_index = output_max_str_index.nne -1
+    max_str_index = max_str_index.nne output_max_str_index
+    max_str_index = max_str_index.to_i
+    reticenses = reticenses.nne "..."
+    sliced_str = str.slice(0..max_str_index)
+    reticenses = (sliced_str.size < str.size ) && reticenses || ""
+    "#{sliced_str}#{reticenses}"
+  end
+
+
 
+end
 
-  # returns +!self+, unless +unless_condition+
-  # is +true+; in such case returns +self+.
-  # e.g: +false.negate_me true+ returns
-  # +false+.
-  # (by default, if no params are given,
-  # just # negates +self+)
-  def negate_me condition=true
-    #   STDERR.puts "negate_me"
-    (condition) && (
-      # STDERR.puts "condition"
-      # STDERR.puts "#{self.inspect}"
-      !self
-    ) || (!condition) && (
-      # STDERR.puts "!condition"
-      self
-    )
+
+=begin
+  # begin_documentation
+  This module receives only functions that are deprecated.
+  They are still kept in Rubyment, but they won't receive
+  more updates, because there is a different more modern
+  way of achieving the same results.
+  The functions here are also not used by any function in
+  #RubymentMaintainedModule.
+  # end_documentation
+=end
+module RubymentDeprecatedModule
+
+
+=begin
+  # documentation_begin
+  # short_desc = "tests the function #exception_information_base"
+  @memory[:documentation].push = {
+    :function   => :exception_information_base,
+    :short_desc => short_desc,
+    :description => "",
+    :params     => [
+      {
+        :name             => :args,
+        :description      => "list of parameters",
+        :duck_type        => Array,
+        :default_behavior => [],
+        :params           => [
+          {
+            :name             => :exception,
+            :duck_type        => Exception,
+            :default_behavior => nil,
+            :description      => "exception to extract info from",
+          },
+          {
+            :name             => :max_str_index,
+            :duck_type        => FixNum,
+            :default_behavior => -1,
+            :description      => "limit the full string output to this last index",
+          },
+          {
+            :name             => :reserved,
+            :duck_type        => Object,
+            :default_behavior => nil,
+            :description      => "reserved for future use",
+          },
+        ],
+      },
+    ],
+    :return_value     => [
+      {
+        :name             => :short,
+        :duck_type        => String,
+        :default_behavior => "",
+        :description      => "a brief about the exception; normally an exception inspection",
+      },
+      {
+        :name             => :full,
+        :duck_type        => String,
+        :default_behavior => "",
+        :description      => "all the information about the exception; normally an exception inspection and bactrace",
+      },
+      {
+        :name             => :inspection,
+        :duck_type        => String,
+        :default_behavior => "",
+        :description      => "the  exception inspection",
+      },
+      {
+        :name             => :backtrace,
+        :duck_type        => Object,
+        :duck_type        => [:_a, Array, :strings],
+        :description      => the exception bactrace",
+      },
+      {
+        :name             => :reserved,
+        :duck_type        => Object,
+        :default_behavior => nil,
+        :description      => "reserved for future use",
+      },
+    ],
+  }
+  # documentation_end
+=end
+  def exception_information_base args=[]
+    exception,
+      max_str_index,
+      reserved = args
+    inspection = exception.inspect
+    backtrace = exception.backtrace
+    short = inspection
+    full = (
+      [
+        "inspection (message):",
+        inspect,
+        "",
+        "backtrace:",
+        "",
+      ] +
+      backtrace.to_a
+    ).join "\n"
+
+    full = string_truncate [
+      full,
+      max_str_index,
+    ]
+    [short, full, inspection, backtrace]
   end
+
+
 end
 
 
-# Collection of Ruby functions
-# * output
-# normally outputs to STDERR, with
-# no mercy
-# STDOUT, just qualified output:
-# only if the function is expected
-# to output something
-module RubymentModule
+=begin
+  # begin_documentation
+  Group of functions under deprecation
 
-  # this class very often needs to split
-  # first argument and remaining elements.
-  # args:
-  # args
-  # default:
-  # ARGV
-  # returns:
-  # [ args[0], args[1..-1] ]
-  def array_first_remainder args=ARGV
-    [ args[0], args[1..-1] ]
+  to be included by #RubymentUnderDeprecationModule
+  # end_documentation
+=end
+module RubymentUnderDeprecationRuneFunctionsModule
+
+
+  # generic function for test__ functions
+  def test__tester args=[]
+    expectation = {}
+    actual = {}
+    test_cases = args
+    test_cases ||= [
+     # [ :id, :expectation, :actual_params ],
+    ]
+    test_cases.each_with_index{ |test_case|
+      test_case_id, test_expectation, actual_params = test_case
+      result = send actual_params[0], actual_params[1]
+      expectation[test_case_id] = test_expectation
+      actual[test_case_id] = result
+    }
+    judgement = actual.keys.map {|test_case|
+      [expectation[test_case], actual[test_case] , test_case]
+    }.map(&method("expect_equal")).all?
   end
 
 
@@ -250,6 +1023,9 @@ module RubymentModule
   # another desirable case is to output
   # the exception, but don't return it;
   # not yet possible.
+  # a third desirable case would be  not to
+  # rescue and print the exception, which is
+  # also not yet possible.
   # @param [splat] +args+, an splat whose elements are expected to be +blea_args+ and +blocks_args+:
   # +blea_args+:: [Array] args to be used internally, which are expected to be:
   # +exception_admitted+:: [Boolean]
@@ -261,6 +1037,360 @@ module RubymentModule
   end
 
 
+end
+
+
+
+=begin
+  # begin_documentation
+  This module receives only functions that are deprecated.
+  They are still kept in Rubyment, but they won't receive
+  more updates, because there is a different more modern
+  way of achieving the same results.
+  However, functions here are still under active use by
+  some official functions in #RubymentMaintainedModule,
+  which were not yet updated with the new modern way of
+  achieving the same results.
+  # end_documentation
+=end
+module RubymentUnderDeprecationModule
+
+
+  include RubymentUnderDeprecationRuneFunctionsModule
+
+
+end
+
+
+=begin
+  # begin_documentation
+  This module receives functions that are supposed to test
+  other functions.
+  Eventually, these functions may be run automatically.
+  They must return false if it fails.
+  Eventually a timeouting standard will be set for function
+  doing IO.
+  # end_documentation
+=end
+module RubymentTestModule
+
+
+  def test_cases_template args=[]
+    test_cases ||= [
+      # [ :id, :expectation, :actual_params ],
+      # actual_params can be an array with method_name + args to that method.
+    ]
+  end
+
+
+=begin
+  test for #bled
+=end
+  def test__bled args=[]
+    test___experiment__bled :bled
+  end
+
+
+=begin
+  test for #experiment__bled
+=end
+  def test___experiment__bled args=[]
+    bled_method_name,
+     reserved = args
+    bled_method_name = bled_method_name.nne :experiment__bled
+    p0 =  send bled_method_name
+    y0 = p0.first.call 2, 3
+    p1 = send bled_method_name, [] {|x| x}
+    y1 = p1.first.call 2, 3
+    y1_2 = p1.first.call
+    p2 =  send bled_method_name, [
+      :default,
+      :no_rescue.negate_me,
+      :yes_output.negate_me,
+    ] {|x| y}
+    y2 = p2.first.call 2, 3
+    p3 =  send bled_method_name, [
+      :default,
+      :no_rescue,
+      :yes_output.negate_me,
+    ] {|x| y}
+    y3 = begin
+      p3.first.call 2, 3
+    rescue => e
+      e_info = exception_info_base [e]
+      [:default, e_info, e]
+    end
+
+    judgement =
+      [
+        [y0[0], nil, "no params: return value"],
+        [y0[1].to_a, [], "no params: e_info"],
+        [y0[2], nil, "no params: no exception"],
+
+        [y1[0], 2, "{|x| x}: return value"],
+        [y1[1].to_a, [], "{|x| x}: e_info"],
+        [y1[2], nil, "{|x| x}: no exception"],
+
+        [y1_2[0], nil, "{|x| x}: return value"],
+        [y1_2[1].to_a, [], "{|x| x}: e_info"],
+        [y1_2[2], nil, "{|x| x}: no exception"],
+
+        [y2[0], :default, "default on exception"],
+        [y3[0], y2[0], "exceptions must be the same"],
+        [y3[2].to_s, y2[2].to_s, "exceptions must be the same"],
+      ].map(&method("expect_equal")).all?
+
+  end
+
+
+=begin
+  test for #call_or_itself
+=end
+  def test__call_or_itself args=[]
+    method_to_test,
+      reserved = args
+    method_to_test = method_to_test.nne :call_or_itself
+    method_to_send = :array_first_remainder
+    args_to_send = [:arg_to_send_1, :arg_to_send_2, :arg_to_send_3]
+    args_to_bled = []
+
+    send_block = bled(args_to_bled) {
+      self.send method_to_send, args_to_send
+    }.first
+
+    default_block = bled(args_to_bled) {
+      args_to_send
+    }.first
+
+    a1 = (send method_to_test, [send_block, :return_dont_call.negate_me]).first
+    e1 = [:arg_to_send_1, [:arg_to_send_2, :arg_to_send_3]]
+    a2 = (send method_to_test, [default_block, :return_dont_call.negate_me]).first
+    e2 = [:arg_to_send_1, :arg_to_send_2, :arg_to_send_3]
+
+    a3 = send method_to_test, [send_block, :return_dont_call ]
+    e3 = send_block
+    a4 = send method_to_test, [default_block, :return_dont_call ]
+    e4 = default_block
+
+    judgement =
+      [
+        [e1, a1, "#{method_to_test}[send_block, :return_dont_call.negate_me]"],
+        [e2, a2, "#{method_to_test}[default_block, :return_dont_call.negate_me]"],
+        [e3, a3, "#{method_to_test}[send_block, :return_dont_call]"],
+        [e4, a4, "#{method_to_test}[default_block, :return_dont_call]"],
+      ].map(&method("expect_equal")).all?
+  end
+
+
+=begin
+  test for #experiment__whether
+=end
+  def test__experiment__whether args=[]
+    method_to_test,
+      reserved = args
+    method_to_test = method_to_test.nne :experiment__whether
+
+    method_to_send = :array_first_remainder
+    args_to_send = [:arg_to_send_1, :arg_to_send_2, :arg_to_send_3]
+    args_to_bled = []
+
+    send_block = bled(args_to_bled) {
+      self.send method_to_send, args_to_send
+    }.first
+
+    default_block = bled(args_to_bled) {
+      args_to_send
+    }.first
+
+    t1 = "two blocks, condition true"
+    a1 = send method_to_test, [
+      method_to_send,
+      send_block,
+      default_block,
+    ]
+    e1 = [[:arg_to_send_1, [:arg_to_send_2, :arg_to_send_3]], nil, nil]
+
+    t2 = "two blocks, condition false"
+    a2 = send method_to_test, [
+      method_to_send.to_nil,
+      send_block,
+      default_block,
+    ]
+    e2 = [[ :arg_to_send_1, :arg_to_send_2, :arg_to_send_3], nil, nil]
+
+    judgement =
+      [
+        [e1, a1, "#{t1}"],
+        [e2, a2, "#{t2}"],
+      ].map(&method("expect_equal")).all?
+  end
+
+
+=begin
+=end
+  def test_cases__experiment__send_array_base args=[]
+    method_to_test,
+      reserved = args
+    method_to_test = method_to_test.nne :experiment__send_array_base
+    test_cases ||= [
+      # test_case:
+      [
+         # id:
+         [ "test #{method_to_test} base :array_first_remainder" ],
+         # expectation:
+         [ [ :arg_to_send_1, [:arg_to_send_2, :arg_to_send_3]], nil, nil],
+         # method_name + args:
+         [
+            # method_name:
+            method_to_test,
+            # args to method_to_test:
+            [
+              :array_first_remainder,
+              [ :arg_to_send_1, :arg_to_send_2, :arg_to_send_3 ],
+            ],
+            # array_first_remainder is a function of...
+            self,
+            # debug:
+            0,
+         ],
+      ],
+
+    ]
+  end
+
+
+=begin
+  test for #experiment__send_array_base
+=end
+  def test__experiment__send_array_base args=[]
+=begin
+    method_to_test,
+      reserved = args
+    method_to_test = method_to_test.nne :experiment__send_array_base
+    e1 = [ [ :arg_to_send_1, [:arg_to_send_2, :arg_to_send_3]], nil, nil]
+    a1 = send method_to_test, [
+      [
+        :array_first_remainder,
+        [ :arg_to_send_1, :arg_to_send_2, :arg_to_send_3 ],
+      ],
+      self,
+    ]
+
+    judgement =
+      [
+        [e1, a1, "test #{method_to_test} base :array_first_remainder"],
+      ].map(&method("expect_equal")).all?
+=end
+    stderr = @memory[:stderr]
+    debug = debug.nne
+debug = 1
+    debug && (stderr.puts "{#{__method__} starting")
+    debug && (stderr.puts "caller=#{caller_label}")
+    debug && (stderr.puts backtrace)
+    debug && (stderr.puts "args=#{args.inspect}")
+    test_cases = (test_cases__experiment__send_array_base args)
+    debug && (stderr.puts "test_cases.size=#{test_cases.size}")
+    experiment__tester_block = bled [
+      nil,
+      :no_rescue.negate_me,
+      :output,
+    ] {
+        experiment__tester [
+        (test_cases), 1
+      ]
+    }
+    debug && (stderr.puts "experiment__tester_block=#{experiment__tester_block.inspect}")
+    rv = experiment__tester_block.first.call
+    debug && (stderr.puts "will return #{rv.inspect}")
+    # if raises exception before it will be unbalanced :
+    debug && (stderr.puts "#{__method__} returning}")
+    rv
+  end
+
+
+end
+
+
+=begin
+  # begin_documentation
+  This module receives functions that change other
+  Ruby classes, by adding or changing their classes.
+
+  The purpose is normally achieve a more functional
+  approach to some classes.
+
+  Some classes will be changed just by including
+  this file or requiring rubyment, which is not the
+  best approach, but kept to respect the open/closed
+  principle, but new functions should be added here.
+  # end_documentation
+=end
+module RubymentClassInjectorModule
+
+
+end
+
+
+
+=begin
+  # begin_documentation
+  This module receives all the Rubyment functions.
+
+  Rubyment functions are helper functions to achieve general
+  repetitive programming tasks, including:
+  - Encryption of files or user input with default proper parameters
+  - HTTP/HTTPS server ready-to-go
+  - gem package generation and submission.
+  - tree parsing.
+
+
+  Rubyment functions must respect the open/closed principle
+  (which ensures also "backwards compatibility").
+
+  Rubyment functions rely on a common bus called @memory[:stderr],
+  per process. Any global (or statics, or singleton, or whatever
+  you call it) must be stored there. Any function has complete
+  read-write access to it.
+
+  Rubyment functions normally output debug information to
+  @memory[:stderr] this output
+  is subject to change (ie, not supposed to be parsed, or the
+  parsing may stop working after the function receives maintenance).
+  There is a @memory[;debug] which is no longer much used, nowadays
+  functions are mostly getting a debug parameter to enable locally.
+
+  Output to @memory[:stdout] should be treated as trustworthy, and
+  respect scripts that might parse it. However, if that output comes
+  from a third party command, that output can't be guaranteed
+  (but surely effort will be taken to ensure it won't break consumers).
+
+  README.md contains more standards adopted by Rubyment.
+
+  # end_documentation
+=end
+module RubymentModule
+
+  include RubymentClassInjectorModule
+  include RubymentExperimentModule
+  include RubymentMaintainedModule
+  include RubymentDeprecatedModule
+  include RubymentUnderDeprecationModule
+  include RubymentTestModule
+
+
+  # this class very often needs to split
+  # first argument and remaining elements.
+  # args:
+  # args
+  # default:
+  # ARGV
+  # returns:
+  # [ args[0], args[1..-1] ]
+  def array_first_remainder args=ARGV
+    [ args[0], args[1..-1] ]
+  end
+
+
   # invoke first arg with following args
   # used by initialize
   def invoke args=ARGV
@@ -396,9 +1526,11 @@ module RubymentModule
   # +headers+:: [Hash] +"Authorization"+ key will be added to it if +auth_user+ is given. Defaults to +{}+
   # +method+:: [HTTP method] one of +:get+, +:method+, +:post+ or +:delete+. defaults to +:get+
   # +timeout+:: [Fixnum, nil] defaults to +nil+
+  # +debug+:: [Object] if calling the object +nne+ method returns a +false+ value, won't print debug information
   #
   # @return [String, Object] read data (or +return_on_rescue+)
   def file_read args=ARGV
+    stderr = @memory[:stderr]
     uri,
       username,
       password,
@@ -410,13 +1542,18 @@ module RubymentModule
       headers,
       method,
       timeout,
+      debug,
       reserved = args
+    debug = debug.nne 1
+    debug && (stderr.puts "{#{__method__} starting")
+    debug && (stderr.puts "args=#{args.inspect}")
     uri = uri.nne ""
     file_is_directory = File.directory?(uri)
+    must_return_on_rescue = false
     return_on_directory_given ||= true
     contents = !(file_is_directory) && (
       begin
-        (send :rest_request_or_open_uri_open, [
+        url_response = (send :rest_request_or_open_uri_open, [
             uri,
             payload,
             verify_ssl,
@@ -427,14 +1564,26 @@ module RubymentModule
             timeout,
             skip_open_uri,
           ]).first
+        debug && (stderr.puts "url_response=#{url_response.inspect}")
+        url_response
       rescue => e1
         begin
+          debug && (stderr.puts "exception e1=#{e1.inspect}")
           File.read uri
         rescue  => e2
+          debug && (stderr.puts "exception e2=#{e2.inspect}")
+          debug && (stderr.puts "return_on_rescue=#{return_on_rescue.inspect}")
+          must_return_on_rescue = true
           return_on_rescue
         end
       end
     ) || (file_is_directory) && (return_on_directory_given)
+    rv = contents
+    (rv = return_on_rescue) if must_return_on_rescue
+    debug && (stderr.puts "will return #{rv.inspect}")
+    # if raises exception before it will be unbalanced :
+    debug && (stderr.puts "#{__method__} returning}")
+    rv
   end
 
 
@@ -973,8 +2122,10 @@ module RubymentModule
   # +password+:: [String, nil] password for basic authentication method. Will prompt without echo if +nil+ and +auth_user+ is not +nil+
   # +timeout+:: [Fixnum, nil] defaults to +nil+
   # +skip_open_uri+:: [Boolean] don't bother trying with #open
+    # +debug+:: [Object] if calling the object +nne+ method returns a +false+ value, won't print debug information
   # @return [Array] the response
   def rest_request_or_open_uri_open args=ARGV
+    stderr = @memory[:stderr]
     url,
       payload,
       verify_ssl,
@@ -984,10 +2135,27 @@ module RubymentModule
       password,
       timeout,
       skip_open_uri,
+      debug,
       reserved = args
+
+    debug = debug.nne
+    debug = 1
+    debug && (stderr.puts "{#{__method__} starting")
+    debug && (stderr.puts "args=#{args.inspect}")
     skip_open_uri = skip_open_uri.nne
+    debug && (stderr.puts "skip_open_uri=#{skip_open_uri.inspect}")
 
-    response = runea ["yes, rescue",
+    response = runea ["yes, rescue".negate_me,
+      "already not rescuing, forget about output".to_nil,
+      "already not rescuing, forget about return control".to_nil,
+    ] {
+      !skip_open_uri && send(
+        :open,
+        url,
+        :http_basic_authentication => [auth_user, password],
+      ).read
+    }
+    response ||= runea ["yes, rescue",
       "output exception".negate_me,
       "nil on exception"
     ] {
@@ -1002,17 +2170,11 @@ module RubymentModule
         timeout,
       ]
     }
-    response ||= runea ["yes, rescue".negate_me,
-      "output exception".negate_me,
-      "nil on exception"
-    ] {
-      !skip_open_uri && send(
-        :open,
-        url,
-        :http_basic_authentication => [auth_user, password],
-      ).read
-    }
-    [response]
+    rv = [response]
+    debug && (stderr.puts "#{__method__}  will return #{rv.inspect}")
+    # if raises exception before it will be unbalanced :
+    debug && (stderr.puts "#{__method__} returning}")
+    rv
   end
 
 
@@ -2624,16 +3786,16 @@ require '#{gem_name}'
       keep_alive.negate_me && "Connection: close",
       "",
       "#{payload}"
-    ].compact
-    debug.nne && (stderr.puts "#{__method__} will return #{rv}")
+    ].compact.join eol
+    debug.nne && (stderr.puts "#{__method__} will return \"#{rv}\"")
     debug.nne && (stderr.puts "#{__method__} returning")
-    rv.join eol
+    rv
   end
 
 
 =begin
-  # documentation_begin
-  # short_desc = "tests the function #test__http_response__redirect"
+  # short_desc = "tests function to create an http redirect response "
+
   @memory[:documentation].push = {
     :function   => :test__http_response__redirect,
     :short_desc => short_desc,
@@ -2645,6 +3807,42 @@ require '#{gem_name}'
         :duck_type        => Array,
         :default_behavior => "interpreted as empty array",
         :params           => [
+          {
+            :name             => :request,
+            :duck_type        => String,
+            :default_behavior => :nil
+            :description      => "ignored, will redirect whatever request is made. nil is used.",
+          },
+          {
+            :name             => :location,
+            :duck_type        => String,
+            :default_behavior => "",
+            :description      => "Location: field value (the url to redirect to)",
+          },
+          {
+            :name             => :code,
+            :duck_type        => String,
+            :default_behavior => "302 Found",
+            :description      => "Error code. Note that there are many redirect codes specified by the HTTP protocol.",
+          },
+          {
+            :name             => :version,
+            :duck_type        => String,
+            :default_behavior => "1.1",
+            :description      => "HTTP protocol version",
+          },
+          {
+            :name             => :debug,
+            :duck_type        => Object,
+            :default_behavior => :nil,
+            :description      => "prints debug information to the __IO__ specified by __@memory[:stderr]__ (STDERR by default)",
+          },
+          {
+            :name             => :eol,
+            :duck_type        => Object,
+            :default_behavior => "\r\n",
+            :description      => "separator to join each line of the response",
+          },
           {
             :name             => :reserved,
             :duck_type        => Object,
@@ -2655,10 +3853,11 @@ require '#{gem_name}'
       },
     ],
   }
-  # documentation_end
+
 =end
   def test__http_response__redirect args = []
-    location,
+    request,
+      location,
       code,
       version,
       debug,
@@ -2668,12 +3867,10 @@ require '#{gem_name}'
     debug = debug.nne
     debug.nne && (stderr.puts "#{__method__} starting")
     debug.nne && (stderr.puts args.inspect)
-    payload ||= ""
-    payload  = nil
-    content_type  = nil
-    version ||= "1.1"
-    code ||= "302 Found"
-    eol ||= "\r\n"
+    location = location.nne ""
+    version = version.nne "1.1"
+    code = code.nne "302 Found"
+    eol = eol.nne "\r\n"
     rv = http_response_base [
       :payload.to_nil,
       :content_type.to_nil,
@@ -3536,6 +4733,233 @@ n8mFEtUKobsK
   end
 
 
+=begin
+  # short_desc = "this functions creates an https (or http server) and a second http server, which always redirect to the first server."
+
+  @memory[:documentation].push = {
+    :function   => :experiment__web_http_https_server,
+    :short_desc => short_desc,
+    :description => "",
+    :params     => [
+      {
+        :name             => :args,
+        :description      => "list of parameters",
+        :duck_type        => Array,
+        :default_behavior => [],
+        :params           => [
+          {
+            :name             => :http_processing_method,
+            :duck_type        => [:_a, String, :method_name],
+            :default_behavior => :http_OK_response
+            :description      => "method name of the method that returns an http request string (used by the first server)",
+          },
+          {
+            :name             => :http_processing_method_args,
+            :duck_type        => Array,
+            :default_behavior => [],
+            :description      => "arguments for the method that returns an http request string (used by the first server)",
+          },
+          {
+            :name             => :http_server_port,
+            :duck_type        => FixNum,
+            :default_behavior => 8003,
+            :description      => " server port (used by the first server)",
+          },
+          {
+            :name             => :http_ip_addr,
+            :duck_type        => String,
+            :default_behavior => "0",
+            :description      => "ip address (used by the first server)",
+          },
+          {
+            :name             => :priv_pemfile,
+            :duck_type        => String,
+            :default_behavior => ssl_cert_pkey_chain_method[1],
+            :description      => "argument to be given to __OpenSSL::SSL::SSLContext.key__ method, after calling __OpenSSL::PKey::RSA.new__ with it. It's the private key file. letsencrypt example: __'/etc/letsencrypt/live/#{domain}/privkey.pem'__ (now it's accepted to pass the file contents instead, both must work).",
+          },
+          {
+            :name             => :cert_pem_file,
+            :duck_type        => String,
+            :default_behavior => ssl_cert_pkey_chain_method[0],
+            :description      => "argument to be given to __OpenSSL::SSL::SSLContext.cert__ method, after calling __OpenSSL::X509::Certificate__.  It's the 'Context certificate' accordingly to its ruby-doc page. letsencrypt example: __'/etc/letsencrypt/live/#{domain}/fullchain.pem'__ (now it's accepted to pass the file contents instead, both must work).",
+          },
+          {
+            :name             => :extra_cert_pem_files,
+            :duck_type        => Object,
+            :duck_type        => [:_a, Array, :strings],
+            :default_behavior => ssl_cert_pkey_chain_method[2],
+            :description      => "Each string will be mapped with __OpenSSL::SSL::SSLContext.new__, and the resulting array is given to __OpenSSL::SSL::SSLContext.extra_chain_cert__. 'An Array of extra X509 certificates to be added to the certificate chain' accordingly to its ruby-doc. letsencrypt example: __['/etc/letsencrypt/live/#{domain}/chain.pem']__ (now it's accepted to pass the file contents instead, both must work)."
+          },
+          {
+            :name             => :ssl_cert_pkey_chain_method,
+            :duck_type        => [:_a, String, :method_name],
+            :default_behavior => :ssl_sample_self_signed_cert_encrypted,
+            :description      => "method name of the method that returns the certificates (used by the first server)",
+          },
+          {
+            :name             => :debug,
+            :duck_type        => Object,
+            :default_behavior => :nil,
+            :description      => "prints debug information to the __IO__ specified by __@memory[:stderr]__ (STDERR by default)",
+          },
+          {
+            :name             => :happy_with_request,
+            :duck_type        => String,
+            :default_behavior => nil,
+            :description      => "A socket never ends returning data. This variable sets an end to a socket -- after such string is found the socket may be closed. As of this writing, underlying functions will use \r\n if nil is found; this function trusts :io_method to do its best.",
+          },
+          {
+            :name             => :io_method,
+            :duck_type        => [:_a, String, :method_name],
+            :default_behavior => :io_transform,
+            :description      => "method name of the method that reads a socket and forwards the call to a processing method  (used both by the first and the redirecting server)",
+          },
+          {
+            :name             => :io_method_debug,
+            :duck_type        => Object,
+            :default_behavior => :nil,
+            :description      => "debug option to the :io_method",
+          },
+          {
+            :name             => :admit_non_ssl,
+            :duck_type        => Object,
+            :default_behavior => :nil,
+            :description      => "if anything fails with the creation of an ssl server, will try to create a plain one (used by the first server)",
+          },
+          {
+            :name             => :plain_http_processing_method,
+            :duck_type        => [:_a, String, :method_name],
+            :default_behavior => :http_OK_response
+            :description      => "method name of the method that returns an http request string (used by the redirecting server)",
+          },
+          {
+            :name             => :plain_http_processing_method_args,
+            :duck_type        => Array,
+            :default_behavior => [],
+            :description      => "arguments for the method that returns an http request string (used by the redirecting server)",
+          },
+          {
+            :name             => :plain_http_server_port,
+            :duck_type        => FixNum,
+            :default_behavior => 8003,
+            :description      => " server port (used by the redirecting server)",
+          },
+          {
+            :name             => :plain_http_ip_addr,
+            :duck_type        => String,
+            :default_behavior => "0",
+            :description      => "ip address (used by the redirect server)",
+          },
+          {
+            :name             => :reserved,
+            :duck_type        => Object,
+            :default_behavior => :nil,
+            :description      => "for future use",
+          },
+        ],
+      },
+    ],
+  }
+=end
+
+  def experiment__web_http_https_server args = []
+    stderr = @memory[:stderr]
+    http_processing_method,
+      http_processing_method_args,
+      http_server_port,
+      http_ip_addr,
+      priv_pemfile,
+      cert_pem_file,
+      extra_cert_pem_files,
+      ssl_cert_pkey_chain_method,
+      debug,
+      happy_with_request,
+      io_method,
+      io_method_debug,
+      admit_non_ssl,
+      plain_http_processing_method,
+      plain_http_processing_method_args,
+      plain_http_server_port,
+      plain_http_ip_addr,
+      reserved = args
+
+    debug = debug.nne
+    debug.nne && (stderr.puts "{#{__method__} starting")
+    debug && (stderr.puts "args=#{args.inspect}")
+    http_processing_method = http_processing_method.nne :http_OK_response
+    http_processing_method_args = http_processing_method_args.nne []
+    http_server_port = http_server_port.nne  8003
+    redirect_location_host = http_ip_addr.nne "localhost"
+    http_ip_addr = http_ip_addr.nne "0"
+    ssl_cert_pkey_chain_method =
+      ssl_cert_pkey_chain_method.nne :ssl_sample_self_signed_cert_encrypted
+    ssl_cert_pkey_chain = send ssl_cert_pkey_chain_method
+    priv_pemfile  =   priv_pemfile.nne ssl_cert_pkey_chain[1]
+    cert_pem_file =  cert_pem_file.nne ssl_cert_pkey_chain[0]
+    extra_cert_pemiles =  extra_cert_pem_files.nne ssl_cert_pkey_chain[2]
+    debug =  debug.nne "yes, debug"
+    io_method =  io_method.nne "io_transform"
+    io_method_debug =  io_method_debug.nne debug
+    happy_with_request = happy_with_request.nne
+    admit_non_ssl = admit_non_ssl.nne
+    plain_http_processing_method =  plain_http_processing_method.nne :test__http_response__redirect
+    plain_http_processing_method_args =  plain_http_processing_method_args.nne [
+      "https://#{redirect_location_host}:#{http_server_port}/#redirect"
+    ]
+    plain_http_server_port =  plain_http_server_port.nne 8004
+    plain_http_ip_addr = plain_http_ip_addr.nne "0"
+
+    tcp_ssl_server_args = [
+      http_server_port,
+      http_ip_addr,
+      debug,
+      admit_non_ssl,
+      io_method,
+      [
+        io_method_debug,
+        happy_with_request,
+        http_processing_method,
+        http_processing_method_args
+      ],
+      priv_pemfile,
+      cert_pem_file,
+      extra_cert_pem_files,
+      "yes, output exceptions",
+    ]
+    tcp_ssl_server_thread   =  send :tcp_ssl_server, tcp_ssl_server_args
+    tcp_plain_server_args = [
+      plain_http_server_port,
+      plain_http_ip_addr,
+      debug,
+      :admit_non_ssl,
+      io_method,
+      [
+        io_method_debug,
+        happy_with_request,
+        plain_http_processing_method,
+        plain_http_processing_method_args,
+      ],
+      :priv_pemfile.to_nil,
+      :cert_pem_file.to_nil,
+      :extra_cert_pem_files.to_nil,
+      "yes, output exceptions",
+    ]
+    tcp_plain_server_thread =  send :tcp_ssl_server, tcp_plain_server_args
+
+    rv = [
+      tcp_ssl_server_thread,
+      tcp_ssl_server_args,
+      :tcp_ssl_server_reserved.to_nil,
+      tcp_plain_server_thread,
+      tcp_plain_server_args,
+      :tcp_ssl_server_reserved.to_nil,
+    ]
+    debug && (stderr.puts "will return #{rv}")
+    debug && (stderr.puts "#{__method__} returning}")
+    rv
+  end
+
+
   # test for tcp_ssl_server (calling an +io_method+,
   # by default #io_transform, with
   # a function that processes an http request and returns
@@ -3601,38 +5025,57 @@ n8mFEtUKobsK
   end
 
 
-  # tests file_read against a uri.
-  # created to test a client for servers
-  # created with
-  # #test__tcp_ssl_server__io_method
-  def test__file_read__uri_root args = ARGV
+=begin
+ generalization of #test__file_read__uri_root
+=end
+  def test__file_read__uri args = []
     stderr = @memory[:stderr]
     domain,
       http_server_port,
       admit_non_ssl,
       debug,
+      path,
       reserved = args
+    debug = debug.nne
+    debug && (stderr.puts "{#{__method__} starting")
+    debug && (stderr.puts "args=#{args.inspect}")
+
     domain = domain.nne "localhost"
+    path = path.nne ""
     http_server_port = http_server_port.nne 8003
     admit_non_ssl = admit_non_ssl.nne true
-    debug = debug.nne
-    stderr.puts admit_non_ssl.inspect
-    stderr.puts (admit_non_ssl && (file_read ["http://#{domain}:#{http_server_port}/"])).inspect
-    response = (file_read ["https://#{domain}:#{http_server_port}/"]) ||
-      admit_non_ssl && (file_read ["http://#{domain}:#{http_server_port}/"])
-    debug && (stderr.puts  "response{#{response}}response")
-    response
+    http_file_read_attempt = (
+      debug && (stderr.puts "file_read \"https://#{domain}:#{http_server_port}/#{path}\"")
+      file_read ["https://#{domain}:#{http_server_port}/#{path}", nil, nil, :return_on_rescue, nil, :skip_open_uri]
+    )
+    debug && (stderr.puts "#{admit_non_ssl.inspect} && file_read \"http://#{domain}:#{http_server_port}/#{path}\"")
+    response = http_file_read_attempt ||
+      admit_non_ssl && (file_read ["http://#{domain}:#{http_server_port}/#{path}"])
+    rv = [response, http_file_read_attempt]
+    debug && (stderr.puts  "#{__method__} will return [response, http_file_read_attempt]=#{rv.inspect}")
+    debug && (stderr.puts "#{__method__} returning}")
+    rv
   end
 
 
-  # tests test__tcp_ssl_server__io_method, creating two
-  # servers, one ssl and another plain, redirecting to
-  # the ssl one. then, opens a client thread with a client
-  # connecting to the root document of the plain server
-  # (and in the end being served by the root document of
-  # the ssl server).
-  # another thread for the client
-  def test__tcp_ssl_server__get_root__plain_redirect args = ARGV
+  # tests file_read against a uri.
+  # created to test a client for servers
+  # created with
+  # #test__tcp_ssl_server__io_method
+  def test__file_read__uri_root args = ARGV
+    test__file_read__uri args
+  end
+
+
+=begin
+   tests #experiment__web_http_https_server, creating two
+   servers, one ssl and another plain, redirecting to
+   the ssl one. then, opens a client thread with a client
+   connecting to the root document of the plain server
+   (and in the end being served by the root document of
+   the ssl server).
+=end
+  def test__experiment__web_http_https_server args = ARGV
     stderr = @memory[:stderr]
     tcp_ssl_server_method,
       http_processing_method,
@@ -3651,11 +5094,11 @@ n8mFEtUKobsK
       admit_non_ssl,
       no_debug_client,
       reserved = args
-    tcp_ssl_server_method = tcp_ssl_server_method.nne :test__tcp_ssl_server__io_method
+    tcp_ssl_server_method = tcp_ssl_server_method.nne :experiment__web_http_https_server
     domain = domain.nne "localhost"
     http_server_port = http_server_port.nne 8003
     no_debug_client = no_debug_client.nne
-    ssl_server_thread = send tcp_ssl_server_method,
+    servers = send tcp_ssl_server_method,
       [
         http_processing_method,
         http_processing_method_args,
@@ -3672,40 +5115,20 @@ n8mFEtUKobsK
         admit_non_ssl,
       ]
 
-   plain_http_processing_method ||=  plain_http_processing_method.nne 
-   plain_http_processing_method_args ||=  plain_http_processing_method_args.nne 
-   plain_http_server_port ||=  plain_http_server_port.nne 
-   plain_http_ip_addr ||= plain_http_ip_addr.nne 
-
-    plain_server_thread = send tcp_ssl_server_method,
-      [
-        plain_http_processing_method,
-        plain_http_processing_method_args,
-        plain_http_server_port,
-        plain_http_ip_addr,
-        :priv_pemfile.to_nil,
-        :cert_pem_file.to_nil,
-        :extra_cert_pem_files.to_nil,
-        :ssl_cert_pkey_chain_method.to_nil,
-        :debug_tcp_ssl_server_method.to_nil,
-        happy_with_request,
-        plain_io_method,
-        plain_io_method_debug,
-        :admit_non_ssl,
-      ]
-
-    thread_2 = Thread.new {
+    # TODO: not hardcoded this way
+    plain_http_server_port = 8004
+    thread_client = Thread.new {
       loop {
         response = test__file_read__uri_root [
           domain,
-          http_server_port,
+          plain_http_server_port,
           admit_non_ssl,
-          no_debug_client.negate_me,
+          :no_debug_client,
         ]
         sleep 2
       }
     }
-    server_thread.first.join
+    servers.first.join
 
     true
   end
@@ -4174,26 +5597,6 @@ n8mFEtUKobsK
   end
 
 
-  # generic function for test__ functions
-  def test__tester args=[]
-    expectation = {}
-    actual = {}
-    test_cases = args
-    test_cases ||= [
-     # [ :id, :expectation, :actual_params ],
-    ]
-    test_cases.each_with_index{ |test_case|
-      test_case_id, test_expectation, actual_params = test_case
-      result = send actual_params[0], actual_params[1]
-      expectation[test_case_id] = test_expectation
-      actual[test_case_id] = result
-    }
-    judgement = actual.keys.map {|test_case|
-      [expectation[test_case], actual[test_case] , test_case]
-    }.map(&method("expect_equal")).all?
-  end
-
-
   # test for #array_unflatten_base_shallow
   def test__array_unflatten_base_shallow args=[]
     test_cases ||= [
@@ -4264,9 +5667,10 @@ n8mFEtUKobsK
         ],
       ],
 
+    # test__array_unflatten_base_shallow
 
     ]
-    test__tester test_cases
+    experiment__tester [ test_cases ]
   end
 
 
@@ -4445,16 +5849,16 @@ n8mFEtUKobsK
            ]
         ],
       ],
-
+# test__array_unflatten_base
 
     ]
-    test__tester test_cases
+    experiment__tester [ test_cases ]
   end
 
 
 =begin
-  # documentation_begin
   # short_desc = "tests the function #string_repetion"
+
   @memory[:documentation].push = {
     :function    => :test__string_repetition,
     :short_desc  => short_desc,
@@ -4476,7 +5880,6 @@ n8mFEtUKobsK
       },
     ],
   }
-  # documentation_end
 
 
 =end
@@ -4582,9 +5985,53 @@ n8mFEtUKobsK
 end
 
 
+=begin
+ includes RubymentModule
+=end
 class Rubyment
    include RubymentModule
 end
+=begin
+c = :c
+experiment__input_select [[:a, :b, :c], c ]
+=end
+class Rubyment
+  def experiment__input_select args=[]
+    alternatives,
+      default,
+      reserved = args
+    stderr = @memory[:stderr]
+    caption = alternatives.each_with_index.map {|a, i| "#{i} - #{a.inspect}"}.join("\n")
+    stderr.puts "[alternatives: #{caption}][default: #{default.inspect}]"
+    alternative = input_single_line
+    selection = alternative.nne && alternatives[alternative.to_i] || default
+  end
+end
+
+
+=begin
+=end
+class Rubyment
+  def file__json args=[]
+    require 'json'
+    file_path,
+      enum,
+      reserved = args
+    File.write file_path,  JSON.pretty_generate({ :root.to_s => enum })
+  end
+  def load__file_json args=[]
+    require 'json'
+    file_path,
+      reserved = args
+    file_contents = File.read file_path
+    puts "file_contents size=#{file_contents.size}"
+    loaded = JSON.parse file_contents
+    puts "loaded size=#{loaded.size}"
+    puts "loaded=#{loaded.inspect}"
+    loaded[:root.to_s]
+  end
+end
+
 
 (__FILE__ == $0) && Rubyment.new({:invoke => ARGV})