module RubymentMaintainedModule

# begin_documentation This module receives only functions that are maintained. Ie, the non-deprecated or not under deprecation functions. # end_documentation

Public Instance Methods

bled(args=[], &block) click to toggle source

# documentation_begin # short_desc = “generates a block which may return exceptions instead of raising them.” examples = [

"
(bled [] { :bled_returns }).first.call
# => [:bled_returns, nil, nil]
",
"
(bled { :bled_returns }).first.call
# => [:bled_returns, nil, nil]
",
'
(bled  { X }).first.call
=> [nil,
 [nil,
 # ...
 #   ["uninitialized constant #<Class:#<Rubyment:0x000000035adcc0>>::X", nil],
 # NameError],
 #    #<NameError: uninitialized constant #<Class:#<Rubyment:0x000000035adcc0>>::X>]
 ',
 '
 (bled ["X is not undefined" ]  { X }).first.call
 # => ["X is not undefined",
 #  [nil,
 #   "message{\
 ',

]

@memory.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      => "debug the block execution (misleading name)",
      },
      {
        :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

# File lib/rubyment.rb, line 3844
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}")
    (debug || output_backtrace) && (stderr.puts "block_args.size=#{block_args.size}")
    brv = begin
      local_rv = [ (block.call *block_args), nil, nil]
      (debug || output_backtrace) && (stderr.puts "#{__method__} block: survived exception and returned #{local_rv.inspect}")
      local_rv
    rescue => e
      e_info = exception_info_base [
        e,
        backtrace_max_str_len
      ]
      b_info = block_info_base [
        block,
        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: info #{b_info[1]} ")
      (debug || output_backtrace) && (dont_rescue) && (stderr.puts "#{__method__} block: dont_rescue=#{dont_rescue.inspect}; will rethrow")
      dont_rescue && (raise e)
      (debug || output_backtrace) && (stderr.puts "#{__method__} block: dont_rescue=#{dont_rescue.inspect}; not rethrowing rethrow")
      [ 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
block_info_base(args=[]) click to toggle source

# documentation_begin # short_desc = “extracts information about a block and return them structurally in an array.” @memory.push = {

:function   => :block_info_base,
:short_desc => short_desc,
:description => "",
:params     => [
  {
    :name             => :args,
    :description      => "list of parameters",
    :duck_type        => Array,
    :default_behavior => [],
    :params           => [
      {
        :name             => :block,
        :duck_type        => Exception,
        :default_behavior => nil,
        :description      => "block 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 block; normally a block inspection",
  },
  {
    :name             => :full,
    :duck_type        => String,
    :default_behavior => "",
    :description      => "all the information about the block",
  },
  {
    :name             => :inspection,
    :duck_type        => String,
    :default_behavior => "",
    :description      => "the  block inspection",
  },
  {
    :name             => :source_location,
    :duck_type        => Object,
    :duck_type        => [:_a, Array, :strings],
    :description      => the block location",
  },
  {
    :name             => :source,
    :duck_type        => String,
    :default_behavior => "",
    :description      => "the block source code",
  },
  {
    :name             => :class_,
    :duck_type        => String,
    :default_behavior => "",
    :description      => "the  block class",
  },
  {
    :name             => :comment,
    :duck_type        => String,
    :default_behavior => "",
    :description      => "the  block comment",
  },
  {
    :name             => :reserved,
    :duck_type        => Object,
    :default_behavior => nil,
    :description      => "reserved for future use",
  },
],

} # documentation_end

# File lib/rubyment.rb, line 3566
def block_info_base args=[]
  block,
    max_str_index,
    reserved = args
  inspection = block.inspect
  class_ = block.class
  comment = block.comment rescue [nil, "doesn't respond to :comment"]
  source = block.source rescue [nil, "doesn't respond to :source"]
  source_location = block.source_location rescue [nil, "doesn't respond to :source_location"]
  parameters = block.parameters.inspect rescue [nil, "doesn't respond to :parameters"]
  short = inspection
  full = (
    [
      "inspection{",
      inspection,
      "}",
      "class{",
      class_,
      "}",
      "source_location{",
      source_location,
      "}",
      "source{",
      source,
      "}",
      "comment{",
      comment,
      "}",
      "parameters{",
      parameters,
      "}",
    ]
  ).join "\n"

  full = string_truncate [
    full,
    max_str_index,
  ]
  [short, full, inspection, source_location, source, class_, comment]
end
exception_info_base(args=[]) click to toggle source

# documentation_begin # short_desc = “extracts information about an exception and return them structurally in an array.” @memory.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

# File lib/rubyment.rb, line 3690
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
string_truncate(args=[]) click to toggle source

# documentation_begin # short_desc = “truncates a string” @memory.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

# File lib/rubyment.rb, line 3931
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