sub_object 1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ba4fda603b0841fbf226306a1858819a85a733f8c6863c86bcc7091aa3987dbc
+  data.tar.gz: b61a445e22d45c5a35f224e867f04b74ee6a03300fe8cbc705e4771f9cba3d79
+SHA512:
+  metadata.gz: 0000c9fe5c0d2910ca8b70d63cdabd0e7cf20461c68df7209d75530475eea2ae5d2ccca9b21cfdc20ee48efabca069331d89d92a519e66533d4349adf23939c7
+  data.tar.gz: 701376479f084de002d3bf88adcbb9806ba2fa34a5ff989f3d5d50fffc153fce99e6b82c40a3afa6a56672c35138f23eaaa991026a2e74caedde76ec9b588608

data/.gitignore

@@ -0,0 +1,51 @@
+# See https://help.github.com/articles/ignoring-files for more about ignoring files.
+#
+# If you find yourself ignoring temporary files generated by your text editor
+# or operating system, you probably want to add a global ignore instead:
+#   git config --global core.excludesfile '~/.gitignore_global'
+
+# Ignore bundler config.
+/.bundle
+/vendor/bundle
+
+# Ignore all logfiles and tempfiles.
+/log/*
+/tmp/*
+!/log/.keep
+!/tmp/.keep
+
+.rbenv-version
+# unless supporting rvm < 1.11.0 or doing something fancy, ignore this:
+.rvmrc
+
+/node_modules
+/yarn-error.log
+
+.byebug_history
+
+*.[oa]
+*.so
+*~
+*.nogem
+*nogem.*
+*.bak
+*.BAK
+*.backup
+*.org
+*.orig
+*.elc
+*.pyc
+\#*\#
+
+# Elastic Beanstalk Files
+.elasticbeanstalk/*
+!.elasticbeanstalk/*.cfg.yml
+!.elasticbeanstalk/*.global.yml
+
+# yard
+*.yardoc
+
+# Ruby Gem doc
+*.gem
+doc/*
+

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2012-2018 Scott Chacon and others
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Makefile

@@ -0,0 +1,23 @@
+ALL	= 
+
+objs	= 
+
+.SUFFIXES:	.so .o .c .f
+
+#.o.so:
+#	${LD} ${LFLAGS} -o $@ $< ${LINK_LIB}
+
+all: ${ALL}
+
+
+.PHONY: clean test doc
+clean:
+	$(RM) bin/*~
+
+## You may need RUBYLIB=`pwd`/lib:$RUBYLIB
+test:
+	rake test
+
+doc:
+	yard doc; [[ -x ".github" && ( "README.en.rdoc" -nt ".github/README.md" ) ]] && ( ruby -r rdoc -e 'puts RDoc::Markup::ToMarkdown.new.convert ARGF.read' < README.en.rdoc > .github/README.md ; echo ".github/README.md is updated." ) || exit 0
+

data/README.en.rdoc

@@ -0,0 +1,287 @@
+
+= SubObject - Parent class for memory-efficient sub-Something
+
+== Summary
+
+This class {SubObject} is the parent class for
+{SubString}[http://rubygems.org/gems/sub_string] and alike.
+This class expresses Ruby sub-Object (like Sub-String),
+which are obtained with the +self[i, j]+ method,
+but taking up negligible memory space, as its instance internally holds
+the (likely positional, though arbitrary) information +(i, j)+ only.  This class provides the base
+interface so the instance behaves exactly like the original
+class (String for SubString, for example) as duck-typing, except
+destructive modification, which is prohibited.
+
+If the original object (which an instance of this class refers to) is ever destructively modified in a way it changes
+its hash value, warning will be issued whenever this instance is accessed.
+
+The entire package of SubObject is found in the
+{Ruby Gems page}[http://rubygems.org/gems/sub_object]
+and in
+{Github}[https://github.com/masasakano/sub_object]
+
+=== Important note to the developers
+
+To inherit this class, make sure to include the lines equivalent to
+the following 2 lines, replacing the method name +:to_str+ (which is for
+SubString class) to suit your child class.
+
+  TO_SOURCE_METHOD = :to_str
+  alias_method TO_SOURCE_METHOD, :to_source
+
+== Cencept
+
+This class takes three parameters in the initialization: *source*, *pos*
+(position), and *size*.  *source* is the original object, and
+basically the constructed instance of this class holds these three
+pieces of information only (plus a hash value, strictly speaking).
+Then, whenever it is referred to, it reconstructs
+
+  source[pos, size]
+
+and works exactly like +source[pos, size]+ does
+({duck-typing}[https://en.wikipedia.org/wiki/Duck_typing]),
+whereas it uses negligible internal memory space on its own.  Note the
+information it needs for the +source+ is basically +source.object_id+
+or equivalent, which is nothing in terms of memory use.
+In other words, this class does
+not create the copy of sub-Object from the original source object, as,
+for example, +String#[i,j]+ does.
+
+As an example, the child class {SubString}[http://rubygems.org/gems/sub_string] (provided as a different Gem)
+works as:
+
+  src = "abcdef"
+  ss = SubString.new(src, -4, 3)  # => Similar to "abcdef"[-4,3]
+  print ss     # => "cde" (STDOUT)
+  ss+'3p'      # => "cde3p"
+  ss.upcase    # => "CDE"
+  ss.sub(/^./, 'Q') # => "Qde"
+  ss.is_a?(String)  # => true
+  "xy_"+ss     # => "xy_cde"
+  "cde" == ss  # => true
+
+Internally the instance holds the source object.  Therefore, as long
+as the instance is alive, the source object is never garbage-collected (GC).
+
+If the source object has been destructively altered, such as with the
+destructive method +clear+, the corresponding object of this class
+is likely not to make sense any more.  This class can detect such destructive
+modification (using the method +Object#hash+) and issues a warning
+whenever it is accessed after the source object has been destructively
+altered, unless the appropriate global settings (see the next section)
+are set to suppress it.
+
+Similarly, because this class supplies an object with the filter
+appropriate for the class when it receives any message (i.e., method),
+it does not make sense to apply a destructive change on the instance of this class.
+Therefore, whenever a destructive method is applied, this class tries
+to raise NoMethodError exception.  The routine to identify the
+destructive method relies thoroughly on the method name.
+The methods ending with "!" are regarded as destructive.
+Other standard distructive method names are defined in the constant {SubObject::DESTRUCTIVE_METHODS}.
+Each child class may add entries or modify it.
+
+Note that if a (likely user-defined) desturctive method passes the check,
+the result is most likely to be different from intended.  It certainly
+never alters this instance destructively (unless +[]+ method of the
+source object returns self, which is against the Ruby convention), and
+the returned value may be not like the expected value.
+
+=== Potential use
+
+You can make a subclass of this class, corresponding to any class that
+has the method of +[i, j]+.  For example, *SubArray* class is
+perfectly possible; indeed it is defined as {SubObject::SubArray}.
+To be fair, I am afraid *SubArray* class does not have much practical
+value (apart from the demonstration of the concept!), because the only
+advantage of this class is to use the minimum memory, whereas the
+original sub-array as in +Array#[i,j]+ does not take much memory in
+the first place, given Array is by definition just a container.
+
+By stark contrast, each sub-String in Ruby default takes up memory
+according to the length of the sub-String.  Consider an example:
+
+  src = "Some very extremely lengthy string.... (snipped)".
+  sub = src[1..-1]
+
+The variable +sub+ uses up about the same memory of +src+.
+If a great number of +sub+ is created and held alive, the total memory
+used by the process can become quicly multifold, even by orders of magnitude.
+
+This is where this class comes in handy.  For example, a parsing
+program applied to a huge text document with a complex grammar may
+hold a number of such String variables.  By using this class instead
+of String, it can save some valuable memory.
+
+That is precisely why
+{SubString}[http://rubygems.org/gems/sub_string],
+which is a child class of this class and for String, is registered as an official Gem.
+(In practice, this class is a generalised version of *SubString*,
+which Ruby allows as a flexible programming language!)
+
+== Description
+
+=== Initialization
+
+Initialize as follows:
+
+  SubObject.new( source, index1, index2 )
+
+Usually, +index1+ is the starting index and +index2+ is the size,
+though how they should be recognized depends on the definition of the method
++[i,j]+ of +source+.
+
+=== Constant
+
+{SubObject::DESTRUCTIVE_METHODS}::  This public constant is the array holding the list of the names (as String) of the methods that should be recognized as destructive (other than those ending with "!").
+{SubObject::TO_SOURCE_METHOD}::  This public constant specifies the method that projects to (returns) the original-like instance; e.g., :to_str for String.
+
+The class variable +TO_SOURCE_METHOD+ is meant to be set by each
+child class (and child classes only).  For example, if it is the subclass for String, it should
+be +:to_str+.  Specifically, the registered method must respond to
++source[i,j]+. Nott that in this class (parent class), it is **left unset**, but the (private) method of the
+same name +to_original_method+ returns +:itself+ instead.
+
+*WARNING*: Do not set this class variable in this class, as it could result in unexpected behaviours if
+a child class and the parent class are used simultaneously.
+
+
+=== Class-global settings and class methods
+
+When this class is accessed after any alteration of the original
+source object has been detected, it may issue warning (as the insntace does not make sense any more).
+The warning is suppressed when the Ruby global variable +$VERBOSE+ is
+nil (it is false in Ruby default).  Or, if the following setting is
+made (internaly, it sets/reads a class instance variable) and set non-nil,
+its value precedes +$VERBOSE+:
+
+  SubObject.verbose       # => getter
+  SubObject.verbose=true  # => setter
+
+where SubObject should be replaced with the name of your child class that inherits {SubObject}.
+If this value is true or false, such a warning is issued or suppresed,
+respectively, regardless of the value of the global variable +$VERBOSE+.
+
+
+=== Instance methods
+
+The following is the instance methods of {SubObject} unique to this class.
+
++#source()+::  Returns the first argument given in initialization. The returned value is dup-ped and **frozen**.
++#pos()+::  Returns the second argument given in initialization (usually meaning the starting index).
++#subsize()+::  Returns the third argument given in initialization (usually meaning the size of the sub-"source").  Usually this is equivalent to the method +#size+; this method is introduced in case the class of the +source+ somehow does not have the +#size+ method.
++#pos_size()+::  Returns the two-component array of +[pos, subsize]+
++#to_source()+::  Returns the instance as close as the original +source+ (the class of it, etc).
+
+In addition, {#inspect}[SubObject#inspect] is redefined.
+
+Any public methods but destructive ones that are defined for the +source+ can
+be applied to the instance of this class.
+
+== Algorithm
+
+A child class of this class should redefine the constant
++TO_SOURCE_METHOD+ in the child class, as well as setting alias to the
+appropriate method like,
+
+  TO_SOURCE_METHOD = :to_str
+  alias_method TO_SOURCE_METHOD, :to_source
+
+(which is an example for SubString class)
+so the method would project to (return) the corresponding instance as close as the original +source+ (the class of it, etc).
+For example, it should be +:to_str+ for {SubString}[http://rubygems.org/gems/sub_string] and
++:to_ary+ for {SubObject::SubArray}.  Providing they are appropriately set, even
+the equal operator works *regardless of the directions* (as long as the
+methods in the other classes are designed, considering duck-typing
+appropriately - which should be fine for the built-in classes).
+
+Internally, almost any method that the instance receives, except for those specific to this class, is processed in
+the following order:
+
+1. {#method_missing}[SubObject#method_missing] (almost any methods except those defined in Object should be processed here)
+   1. +super+ if destuctive (usually NoMethodError, because Object class does not have "destructive" methods, though you may argue +taint+ etc is "destructive")
+   2. Else, +send+ to {#to_source}[SubObject#to_source]
+2. {#to_source}[SubObject#to_source]
+   1. check whether the original {#source}[SubObject#source] has been altered and issues a warning if the conditions are met.
+   2. +#source+[+#pos+, +#subsize+]
+   3. +send+ to +TO_SOURCE_METHOD+ (+:to_str+ etc; +:itself+ in default)
+3. Back to the method received
+   1. +send+ the method with the arguments and block to it.
+
+Note {#respond_to_missing?}[SubObject#respond_to_missing?] is redefined so those instance methods are
+recognized appropriately by +#respond_to?+ and Ruby built-in
++#default?+ sentence.
+
+(See {this post}[https://stackoverflow.com/questions/44107544/respond-to-versus-defined/58673436#58673436]
+for how Ruby handles in +#respond_to?+ etc.)
+
+== Example
+
+An example of +SubObject+ with a test class +MyC+, which
+
+1. takes the given single argument in initialization, and keeps it as its instance variable (+@x+),
+2. returns an own instance having the sum of +@x+, +a+ and +b+ for the method +[a,b]+
+3. has the method +plus1+, which returns its instance variable plus 1,
+4. has the method +dest!+
+
+  class MyC
+    def initialize(a); @x = a; end
+    def [](a, b); MyC.new(a+b); end
+    def plus1; @x+1; end
+    def to_s; @x.to_s; end
+    def dest!; end
+  end
+
+  # How MyC behaves.
+  myo = MyC.new(8)
+  myo.is_a?(MyC)   # => true
+  myo.to_s         # => "1"
+  myo.plus1        # =>  2   # (= 8+1) (self is unmodified)
+
+  # How "Sub"-MyC behaves.
+  obj = SubObject.new(myo, 2, 3)
+  obj.respond_to?(:plus1)  # => true
+  obj.to_s         # => "6"  # (= 1+(2+3))
+  obj.plus1        # =>  7   # (= 6+1)
+  obj.dest!        # => raise NoMethodError (destructive method)
+
+  (SubObject === obj)         # => true
+  obj.instance_of?(SubObject) # => true
+  obj.is_a?(       SubObject) # => false
+  (MyC       === obj)    # => false
+  obj.instance_of?(MyC)  # => false
+  obj.is_a?(       MyC)  # => true
+
+== Install
+
+This script requires {Ruby}[http://www.ruby-lang.org] Version 2.0
+or above.
+
+You can install it from the usual Ruby gem command.
+Or, alternatively, download it and put the library file in one of your Ruby library search paths.
+
+== Developer's note
+
+The master of this README file is found in
+{RubyGems/sub_object}[https://rubygems.org/gems/sub_object]
+
+=== Tests
+
+Ruby codes under the directory <tt>test/</tt> are the test scripts.
+You can run them from the top directory as <tt>ruby test/test_****.rb</tt>
+or simply run <tt>make test</tt>.
+
+
+== Known bugs and Todo items
+
+* This class ignores any optional (keyword) parameters for the methods.  It is due to the fact Ruby {BasicObject#method_missing}[https://ruby-doc.org/core-2.6.5/BasicObject.html#method-i-method_missing] does not take them into account as of Ruby-2.6.5.  It may change in future versions of Ruby.
+
+
+== Copyright
+
+Author::  Masa Sakano < info a_t wisebabel dot com >
+Versions:: The versions of this package follow Semantic Versioning (2.0.0) http://semver.org/
+License:: MIT
+

data/Rakefile

@@ -0,0 +1,9 @@
+require 'rake/testtask'
+
+Rake::TestTask.new do |t|
+  t.libs << 'test'
+end
+
+desc "Run tests"
+task :default => :test
+

data/lib/sub_object.rb

@@ -0,0 +1,222 @@
+# -*- coding: utf-8 -*-
+
+# Parent class for SubString and SubObject::SubArray or similar.
+#
+# == Summary
+#
+# This class SubObject is the parent class for
+# {SubString}[http://rubygems.org/gems/sub_string] and alike.
+# This class expresses Ruby sub-Object (like Sub-String),
+# which are obtained with the +self[i, j]+ method,
+# but taking up negligible memory space, as its instance internally holds
+# the (likely positional, though arbitrary) information +(i, j)+ only.  It provides the basic
+# interface so the instance behaves exactly like the original
+# class (String for SubString, for example) as duck-typing, except
+# destructive modification, which is prohibited.
+#
+# If the original object is destructively modified in a way it changes
+# its hash value, warning is issued whenever this instance is accessed.
+#
+# == Important note to the developers
+#
+# To inherit this class, make sure to include the lines equivalent to
+# the following 2 lines, replacing the method name +:to_str+ (which is for
+# SubString class) to suit your child class.
+#
+#   TO_SOURCE_METHOD = :to_str
+#   alias_method TO_SOURCE_METHOD, :to_source
+#
+# The full reference is found in the top page
+# {SubObject}[http://rubygems.org/gems/sub_object]
+# and in {Github}[https://github.com/masasakano/sub_object]
+#
+# @author Masa Sakano (Wise Babel Ltd)
+#
+class SubObject
+  # The verbosity flag specific to this class, which has a priority
+  # over the global $VERBOSE if set non-nil. If this is true or false,
+  # the warning is always issued or suppressed, respectively, when
+  # an instance is accessed after the source object is destructively modified.
+  # NOTE this class instance variable is specific to this class and
+  # is NOT shared with or inherited to its children!
+  @verbosity = nil
+
+  # Symbol of the method that projects to (returns) the original-like instance;
+  # e.g., :to_str for String. The value should be overwritten in the child class of {SubObject}.
+  TO_SOURCE_METHOD = :itself
+
+  # Symbol of the method to get the original-like instance; e.g., :to_str for String.
+  # The value should be set in the child class, along with the crucial alias, e.g.,
+  #
+  #   TO_SOURCE_METHOD = :to_str
+  #   alias_method TO_SOURCE_METHOD, :to_source
+  #
+  # @return [Symbol] Method name like :to_str
+  def to_source_method
+    self.class::TO_SOURCE_METHOD
+  end
+  private :to_source_method
+
+  # Getter of the class instance variable @verbosity
+  def self.verbose
+    (defined? @verbosity) ? @verbosity : nil
+  end
+
+  # Setter of the class instance variable @@verbosity
+  def self.verbose=(obj)
+    @verbosity=obj
+  end
+
+  # Warning/Error messages.
+  ERR_MSGS = {
+    no_method_error: 'source does not accept #[] method',
+    argument_error:  'source does not accept #[i, j]-type method',
+    type_error:      'wrong type for (pos, size)=(%s, %s)',  # Specify (pos,size) as the argument.
+  }
+  private_constant :ERR_MSGS  # since Ruby 1.9.3
+
+  # List of the names (String) of destructive methods (other than those ending with "!").
+  DESTRUCTIVE_METHODS = %w( []= << clear concat force_encoding insert prepend replace )
+
+  # Starting (character) position
+  attr_reader :pos
+
+  # Size of SubObject.  Identical with #size
+  # attr_reader :isize
+
+  # Returns a new instance of SubObject equivalent to source[ pos, size ]
+  #
+  # @param source [String]
+  # @param pos [Integer]
+  # @param size [Integer]
+  def initialize(source, pos, size)
+    @source, @pos, @isize = source, pos, size
+
+    # Sanity check
+    begin
+      _ = @source[@pos, @isize]
+    rescue NoMethodError
+      raise TypeError, ERR_MSGS[:no_method_error]
+    rescue ArgumentError
+      raise TypeError, ERR_MSGS[:argument_error]
+    rescue TypeError
+      raise TypeError, ERR_MSGS[:type_error]%[pos.inspect, size.inspect]
+    end
+
+    if !source.respond_to? self.class::TO_SOURCE_METHOD
+      raise TypeError, "Wrong source class #{source.class.name} for this class #{self.class.name}"
+    end
+
+    # Hash value retained to check its potential destructive change
+    @hash = @source.hash
+  end
+
+  # @return [Aray]
+  def pos_size
+    [@pos, @isize]
+  end
+
+  # @return usually the size (Integer)
+  def subsize
+    @isize
+  end
+
+  # Frozen String returned.
+  def source
+    warn_hash
+    src = @source.dup
+    src.freeze
+    src
+  end
+
+  # Returns the original representation of the instance as in the source
+  #
+  # Each child class should set the constant TO_SOURCE_METHOD
+  # appropriately and should alias this method to the method registered
+  # to TO_SOURCE_METHOD . For example, for SubString,
+  #
+  #   TO_SOURCE_METHOD = :to_str
+  #   alias_method TO_SOURCE_METHOD, :to_source
+  #
+  # Warning: DO NOT OVERWRITE THIS METHOD.
+  #
+  # @return [Object]
+  def to_source
+    warn_hash
+    @source[@pos, @isize].send(to_source_method)
+  end
+
+  # Method aliases to back up the Object default originals
+  %i(== === is_a? :kind_of? =~ <=> to_s).each do |ec|
+    begin
+      alias_method :to_s_before_sub_object, ec if !method_defined? :to_s_before_sub_object
+    rescue NameError
+      warn "The method {#ec.inspect} is disabled in Object(!!), hence for #{name}" if !$VERBOSE.nil?
+    end
+  end
+
+  # Redefining some methods in Object
+  #
+  # Statements repeated, because Module#define_method uses instance_eval
+  # at run-time, which is inefficient.
+
+  # Redefining a method in Object to evaluate via {#to_source}
+  def ==(       *rest); to_source.send(__method__, *rest); end
+  # Redefining a method in Object to evaluate via {#to_source}
+  def ===(      *rest); to_source.send(__method__, *rest); end
+  # Redefining a method in Object to evaluate via {#to_source}
+  def is_a?(    *rest); to_source.send(__method__, *rest); end
+  # Redefining a method in Object to evaluate via {#to_source}
+  def kind_of?(*rest); to_source.send(__method__, *rest); end
+  # Redefining a method in Object to evaluate via {#to_source}
+  def =~(       *rest); to_source.send(__method__, *rest); end
+  # Redefining a method in Object to evaluate via {#to_source}
+  def <=>(      *rest); to_source.send(__method__, *rest); end
+  # Redefining a method in Object to evaluate via {#to_source}
+  def to_s(     *rest); to_source.send(__method__, *rest); end
+
+  alias_method :inspect_before_sub_object, :inspect
+
+  # @return [String]
+  def inspect
+    warn_hash
+    sprintf('%s[%d,%d]%s', self.class.name.split(/::/)[-1], @pos, @isize, @source[@pos, @isize].inspect)
+  end
+
+  # method_missing for any but destructive methods
+  #
+  # @return [Object]
+  # @see #respond_to_missing?
+  def method_missing(method_name, *rest, &block)
+    destructive_method?(method_name) ? super : to_source.send(method_name, *rest, &block)
+  end
+
+  # Obligatory redefinition, following redefined {#method_missing}
+  def respond_to_missing?(method_name, *rest)
+    destructive_method?(method_name) ? super : to_source.send(:respond_to?, method_name, *rest)
+  end
+
+  ##################
+  private
+  ##################
+
+  def destructive_method?(method_name)
+    met = method_name.to_s
+    (/!$/ =~ met) || DESTRUCTIVE_METHODS.include?(met)
+  end
+  private :destructive_method?
+
+  def warn_hash
+    klass = self.class
+    verbosity_loc = (klass.instance_variable_defined?(:@verbosity) ? klass.instance_variable_get(:@verbosity) : nil)
+    if ((verbosity_loc.nil? && !$VERBOSE.nil?) || verbosity_loc) && @hash != @source.hash
+      str = @source[@pos, @isize].inspect
+      # Suppresses the length only for warning (not the standard inspect), which would be printed repeatedly.
+      str = str[0,60]+'..."' if str.size > 64
+      # warn() would not run if $VERBOSE.nil? (in this case it should run if @verbosity is true).
+      $stderr.printf("WARNING: source string has destructively changed: %s[%d,%d]%s\n", self.class.name, @pos, @isize, str)
+    end
+  end
+  private :warn_hash
+end
+

data/lib/sub_object/sub_array.rb

@@ -0,0 +1,26 @@
+# -*- coding: utf-8 -*-
+
+require 'sub_object'  # Gem: {SubObject}[http://rubygems.org/gems/sub_object]
+
+class SubObject
+
+  # Child class of SubObject for Array: SubObject::SubArray
+  #
+  # See for detail the full reference in the top page
+  # {SubObject}[http://rubygems.org/gems/sub_object]
+  # and in {Github}[https://github.com/masasakano/sub_object]
+  #
+  # @author Masa Sakano (Wise Babel Ltd)
+  #
+  class SubArray < SubObject
+    # Symbol of the method that projects to (returns) the original-like instance;
+    # e.g., :to_str for String. The value should be overwritten in the child class of {SubObject}.
+    TO_SOURCE_METHOD = :to_ary
+    alias_method TO_SOURCE_METHOD, :to_source
+
+    ar = %w( append delete delete_at delete_if fill keep_if push pop shift unshift )
+    # @note Add to the list of destructive method: append delete delete_at delete_if fill keep_if push pop shift unshift
+    DESTRUCTIVE_METHODS.concat ar 
+  end
+end
+

data/sub_object.gemspec

@@ -0,0 +1,52 @@
+# -*- encoding: utf-8 -*-
+
+require 'rake'
+require 'date'
+
+Gem::Specification.new do |s|
+  s.name = %q{sub_object}.sub(/.*/){|c| (c == File.basename(Dir.pwd)) ? c : raise("ERROR: s.name=(#{c}) in gemspec seems wrong!")}
+  s.version = "1.0"
+  # s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  # s.bindir = 'bin'
+  # %w(sub_object).each do |f|
+  #   path = s.bindir+'/'+f
+  #   File.executable?(path) ? s.executables << f : raise("ERROR: Executable (#{path}) is not executable!")
+  # end
+  s.authors = ["Masa Sakano"]
+  s.date = %q{2019-11-05}.sub(/.*/){|c| (Date.parse(c) == Date.today) ? c : raise("ERROR: s.date=(#{c}) is not today!")}
+  s.summary = %q{Parent class for memory-efficient sub-Something}
+  s.description = %q{Class SubObject that is the parent class for Ruby SubString and SubArray classes and alike, providing the base interface. This and child classes use negligible memory space, as their instance holds the positional information only.  It behaves exactly like the source object (duck-typing), except destructive modification is prohibited.  If the original source object is destructively altered, the corresponding instance can detect it and issue warning.}
+  # s.email = %q{abc@example.com}
+  s.extra_rdoc_files = [
+     #"LICENSE.txt",
+     "README.en.rdoc",
+  ]
+  s.license = 'MIT'
+  s.files = FileList['.gitignore','lib/**/*.rb','[A-Z]*','test/**/*.rb', '*.gemspec'].to_a.delete_if{ |f|
+    ret = false
+    arignore = IO.readlines('.gitignore')
+    arignore.map{|i| i.chomp}.each do |suffix|
+      if File.fnmatch(suffix, File.basename(f))
+        ret = true
+        break
+      end
+    end
+    ret
+  }
+  s.files.reject! { |fn| File.symlink? fn }
+
+  # s.add_runtime_dependency 'rails'
+  # s.add_development_dependency "bourne", [">= 0"]
+  s.homepage = %q{https://www.wisebabel.com}
+  s.rdoc_options = ["--charset=UTF-8"]
+
+  # s.require_paths = ["lib"]	# Default "lib"
+  s.required_ruby_version = '>= 2.0'  # respond_to_missing?
+  s.test_files = Dir['test/**/*.rb']
+  s.test_files.reject! { |fn| File.symlink? fn }
+  # s.requirements << 'libmagick, v6.0' # Simply, info to users.
+  # s.rubygems_version = %q{1.3.5}      # This is always set automatically!!
+
+  s.metadata["yard.run"] = "yri" # use "yard" to build full HTML docs.
+end
+

data/test/test_sub_object.rb

@@ -0,0 +1,211 @@
+# -*- encoding: utf-8 -*-
+
+# @author Masa Sakano (Wise Babel Ltd)
+
+#require 'open3'
+require 'sub_object'
+require 'sub_object/sub_array'
+
+$stdout.sync=true
+$stderr.sync=true
+# print '$LOAD_PATH=';p $LOAD_PATH
+
+#################################################
+# Unit Test
+#################################################
+
+gem "minitest"
+# require 'minitest/unit'
+require 'minitest/autorun'
+
+class TestUnitSubObject < MiniTest::Test
+  T = true
+  F = false
+  SCFNAME = File.basename(__FILE__)
+  EXE = "%s/../bin/%s" % [File.dirname(__FILE__), File.basename(__FILE__).sub(/^test_(.+)\.rb/, '\1')]
+
+  class MyA
+  end
+
+  class MyB
+    def [](a)
+    end
+  end
+
+  class MyC
+    attr_reader :x
+    def initialize(a)
+      @x = a
+    end
+
+    def [](a, b)
+      raise TypeError if a.respond_to? :to_hash
+      MyC.new(@x+a+b)
+    end
+
+    def plus1
+      @x+1
+    end
+    def to_s
+      @x.to_s
+    end
+
+    def dest!
+    end
+
+    # Without this you could not compare (once it is frozen)
+    def ==(other)
+      @x == other.x
+    end
+      
+    # Test of hash values
+    def hash
+      @x
+    end
+    def modify_self!
+      @x = @x * 9
+    end
+    def reverse_self!
+      @x = @x / 9
+    end
+  end
+
+  def setup
+  end
+
+  def teardown
+  end
+
+  def test_sub_object01
+    err = assert_raises(TypeError){ SubObject.new MyA.new, 2, 3 }
+    assert_match( /\] method/, err.message )
+    err = assert_raises(TypeError){ SubObject.new MyB.new, 2, 3 }
+    assert_match( /type method/, err.message )
+    err = assert_raises(TypeError){ SubObject.new MyC.new(8), 2, Hash.new[3] }
+    assert_match( /type for/, err.message )
+
+    myo = MyC.new(1)
+    assert            myo.is_a?(MyC)
+    assert_equal "1", myo.to_s
+    assert_equal  2,  myo.plus1
+    assert_nil        myo.dest!
+    assert_equal  1,  myo.hash
+
+    obj = SubObject.new myo, 2, 3
+    assert_equal myo,           obj.source
+    refute_equal myo.object_id, obj.source.object_id  # b/c the latter is frozen
+    assert_equal myo.object_id, obj.instance_variable_get(:@source).object_id
+    assert_equal   2,           obj.pos
+    assert_equal   3,           obj.subsize
+    assert_equal [2, 3],        obj.pos_size
+    assert_equal MyC.new(myo.x+2+3), obj.to_source
+    assert_equal "SubObject", obj.class.name
+    assert_equal "6", obj.to_s
+    assert            myo.respond_to?(:to_s)
+    assert            obj.respond_to?(:to_s)
+    assert            myo.respond_to?(:plus1)
+    assert            obj.respond_to?(:plus1)
+    refute            myo.respond_to?(:naiyo)
+    refute            obj.respond_to?(:naiyo)
+    assert_equal  7,  obj.plus1
+    assert            (SubObject === obj)
+    assert_instance_of(SubObject, obj)
+    refute            obj.kind_of?(SubObject)
+    refute            obj.is_a?(   SubObject)
+    refute            (MyC       === obj)
+    refute_instance_of(MyC, obj)
+    assert            obj.kind_of?(MyC)
+    assert            obj.is_a?(   MyC)
+    err = assert_raises(NoMethodError){ obj.to_str }
+    err = assert_raises(NoMethodError){ obj.dest! }
+
+    assert_equal   1,  myo.hash
+    assert_equal   1,  obj.instance_variable_get(:@hash)
+    myo.modify_self!
+    assert_equal   1,  obj.instance_variable_get(:@hash)
+    assert_equal   9,  myo.hash
+    assert_equal myo.object_id, obj.instance_variable_get(:@source).object_id
+    assert_equal myo.hash, obj.instance_variable_get(:@source).hash
+    assert_equal 9, obj.instance_variable_get(:@source).hash
+    assert_output('', /destructively/){ obj.source }
+    assert_output('', /destructively/){ obj.plus1 }
+    assert_output('', /destructively/){ obj.to_s }
+    ## The following is true and it is as expected,
+    #  However, you do not care what it returns once the source
+    #  has been destructively modified... Hence taken out of this test.
+    # assert_equal "14", obj.to_s
+
+    mutex = Mutex.new
+    exclu = Thread.new {
+      mutex.synchronize {
+      org_verbose = $VERBOSE
+      assert_output('', ''){ _ = SubObject.verbose }
+      begin
+        $VERBOSE = true
+        assert_nil          SubObject.verbose
+        SubObject.verbose=nil;
+        assert_nil          SubObject.verbose
+        assert_output('', /destructively/){ obj.source }
+        $VERBOSE = false
+        assert_output('', /destructively/){ obj.source }
+        $VERBOSE = nil
+        assert_output('', ''){ obj.source }
+
+        SubObject.verbose = true
+        assert_equal true,  SubObject.verbose
+        assert_equal true,  SubObject.instance_variable_get(:@verbosity)
+        assert_output('', /destructively/){ obj.source }
+        SubObject.verbose = false
+        assert_equal false, SubObject.verbose
+        assert_output('', ''){ obj.source }
+        $VERBOSE = true
+        assert_output('', ''){ obj.source }
+        SubObject.verbose=nil;
+        assert_output('', /destructively/){ obj.source }
+
+        # Original String recovered, hence its hash value.
+        myo.reverse_self!
+        assert_output('', ''){ obj.source }
+      ensure
+        $VERBOSE = org_verbose
+        SubObject.verbose=nil;
+      end
+      }
+    }
+    exclu.join
+  end
+
+  def test_sub_array01
+    assert_raises(TypeError){ SubObject::SubArray.new "bad", -3, 2 }
+
+    ary = [2,4,6,8,10]
+    obj = SubObject::SubArray.new ary, -3, 2
+    assert_equal( -3,           obj.pos)
+    assert_equal   2,           obj.subsize
+    assert_equal [-3, 2],       obj.pos_size
+    assert_equal ary[-3, 2],    obj.to_source
+    assert_equal :to_ary, SubObject::SubArray::TO_SOURCE_METHOD
+    assert_equal :itself, SubObject::TO_SOURCE_METHOD
+    assert_raises(TypeError){ SubObject::SubArray.new ary, -3, :a }
+    assert            (SubObject === obj)
+    assert            (SubObject::SubArray === obj)
+    assert            obj.instance_of?(SubObject::SubArray)
+    refute            obj.instance_of?(SubObject)
+    refute            obj.kind_of?(SubObject)
+    refute            obj.is_a?(   SubObject)
+    refute            obj.kind_of?(SubObject::SubArray)
+    refute            obj.is_a?(   SubObject::SubArray)
+    assert_equal [6,8], obj.to_ary
+    assert_equal obj, [6,8]
+    assert_equal [6,8], obj
+    assert_equal [6,8,9], obj+[9]
+    assert            obj.respond_to?(:to_ary)
+    assert            obj.respond_to?(:map)
+    refute            obj.respond_to?(:map!)
+    refute            obj.respond_to?(:naiyo)
+    assert_raises(NoMethodError){ obj.push 5 }
+    assert_raises(NoMethodError){ obj.keep_if{} }
+  end
+
+end # class TestUnitSubObject < MiniTest::Test
+

metadata

@@ -0,0 +1,60 @@
+--- !ruby/object:Gem::Specification
+name: sub_object
+version: !ruby/object:Gem::Version
+  version: '1.0'
+platform: ruby
+authors:
+- Masa Sakano
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2019-11-05 00:00:00.000000000 Z
+dependencies: []
+description: Class SubObject that is the parent class for Ruby SubString and SubArray
+  classes and alike, providing the base interface. This and child classes use negligible
+  memory space, as their instance holds the positional information only.  It behaves
+  exactly like the source object (duck-typing), except destructive modification is
+  prohibited.  If the original source object is destructively altered, the corresponding
+  instance can detect it and issue warning.
+email: 
+executables: []
+extensions: []
+extra_rdoc_files:
+- README.en.rdoc
+files:
+- ".gitignore"
+- LICENSE.txt
+- Makefile
+- README.en.rdoc
+- Rakefile
+- lib/sub_object.rb
+- lib/sub_object/sub_array.rb
+- sub_object.gemspec
+- test/test_sub_object.rb
+homepage: https://www.wisebabel.com
+licenses:
+- MIT
+metadata:
+  yard.run: yri
+post_install_message: 
+rdoc_options:
+- "--charset=UTF-8"
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.3
+signing_key: 
+specification_version: 4
+summary: Parent class for memory-efficient sub-Something
+test_files:
+- test/test_sub_object.rb