betterobject 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 17e2da8e7bbc0099c4d397ac0ecbc619ce9ba46c
+  data.tar.gz: 7b0350db719f6ba417e65e197032262a4507ce14
+SHA512:
+  metadata.gz: aa69cb58b0152b7f729cb0a66f66eb737b2b701c5e6dd477f462fe313d18e157801ddd3024cf31582a1e1780005dae396c56539c56476611f28b90780c6453fe
+  data.tar.gz: 6fc1f62ef608d31bff14911771aa19d96f74d7bd741c732503a5f8c2d5c4d3414c29404a839cf9be9cb7443086a95de73dbc9a8e9145028caaff50d4888a4929

data/.gitignore

@@ -0,0 +1,9 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/

data/.rspec

@@ -0,0 +1,2 @@
+--format documentation
+--color

data/.travis.yml

@@ -0,0 +1,4 @@
+language: ruby
+rvm:
+  - 2.3.0
+before_install: gem install bundler -v 1.11.2

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,49 @@
+# Contributor Code of Conduct
+
+As contributors and maintainers of this project, and in the interest of
+fostering an open and welcoming community, we pledge to respect all people who
+contribute through reporting issues, posting feature requests, updating
+documentation, submitting pull requests or patches, and other activities.
+
+We are committed to making participation in this project a harassment-free
+experience for everyone, regardless of level of experience, gender, gender
+identity and expression, sexual orientation, disability, personal appearance,
+body size, race, ethnicity, age, religion, or nationality.
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery
+* Personal attacks
+* Trolling or insulting/derogatory comments
+* Public or private harassment
+* Publishing other's private information, such as physical or electronic
+  addresses, without explicit permission
+* Other unethical or unprofessional conduct
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+By adopting this Code of Conduct, project maintainers commit themselves to
+fairly and consistently applying these principles to every aspect of managing
+this project. Project maintainers who do not follow or enforce the Code of
+Conduct may be permanently removed from the project team.
+
+This code of conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community.
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting a project maintainer at bryan@bdlsys.com. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. Maintainers are
+obligated to maintain confidentiality with regard to the reporter of an
+incident.
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 1.3.0, available at
+[http://contributor-covenant.org/version/1/3/0/][version]
+
+[homepage]: http://contributor-covenant.org
+[version]: http://contributor-covenant.org/version/1/3/0/

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in betterobject.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2017 Bryan Colvin
+
+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/README.md

@@ -0,0 +1,584 @@
+# Betterobject
+
+This gem installs several class methods to Object which in turn generates both class and instance methods but only when you are ready.
+In order to prevent name pollution, you have the ability to manage the generators to pick alternate names if you prefer.
+After scouring the RubyGems site, some of the better Class upgrades are included here as well as some of my own.
+The gem creates the backbone upon which future upgrades should be forthcoming.
+As a teaser, some of the generators presently include: obj.local_methods, obj.inherited_methods, obj.in?, COBJ.comes_from?, COBJ.derives_from?, COBJ.define_presence_of, obj.find_def. This first release installs 14 generators.
+Calling `Object.better_install_all` will install all of the generators.
+You can also generate a subset by calling `Object.better_install :generator_name` or `Object.better_install array_of_gen_names`.
+The generator names are also the method names which can be renamed by calling `Object.better_rename(old_name, new_name)`;
+this must be done before you generate the method.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'betterobject'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install betterobject
+    
+Or as a stand-alone:
+
+    $ require "betterobject"   
+
+## Usage
+
+The class methods installed on Object must be called before something useful will happen.
+Somewhere in the installation, you will need to run the generators. If you open `irb`, you can try this:
+
+```ruby
+require "betterobject" # load gem
+
+Object.better_install_all # install all generators
+5.in? 1..9  # true ... 
+class Fred
+  def a
+  end
+end  
+fred = Fred.new
+fred.local_methods     # [:a]
+fred.inherited_methods # [bunch of stuff not including :a]
+String.derives_from? Comparable  # true
+String.derives_from? String      # false
+String.comes_from? Comparable    # true
+String.comes_from? String        # true
+
+String.define_presence_of :i_am_a_string?  # updates Object and String
+"hello".i_am_a_string? # true
+1234.i_am_a_string? # false
+Arrray.define_presence_of(:i_am_not_an_array?, false)
+[1,2,3].i_am_not_an_array?  # false
+"".i_am_not_an_array?  # true
+```
+
+You can see the motivation. In the event that one of these generators conflicts with some other method, you can elect to not execute that generator.
+Or if you really need the functionality, you can rename the generator. First close the `irb` then reopen it, then try this:
+
+```ruby
+require "betterobject"
+
+Object.better_rename(:in?, :in_the_thing_to_the_right?)
+Object.better_rename(:local_methods, :methods_by_me)
+Object.better_install [:in_the_thing_to_the_right?, :methods_by_me]  # or better_install_all
+5.in? 1..9    # undefined method ...
+5.in_the_thing_to_the_right? 1..9  # true
+"".local_methods    # undefined method ...
+"".methods_by_me    # [...] 
+```
+
+You can control which methods names get generated. Now let's dive into the other class methods of `betterobject`.
+
+#### Object class methods created from the `betterobject` gem
+* `Object.better_installed_instance_methods`
+* `Object.better_installed_class_methods`
+* `Object.better_installed`
+* `Object.better_explain`
+* `Object.better_source_code`
+* `Object.better_list`
+* `Object.better_install`
+* `Object.better_install_all`
+* `Object.better_uninstall`
+* `Object.better_uninstall_all`
+* `Object.better_skip`
+* `Object.better_unskip`
+* `Object.better_skipped`
+* `Object.better_rename`
+
+
+Note that there are no instance methods created by this gem until you install a generator.
+Also, each and every method must be called from Object.
+
+#### Object.better_install_all
+
+This will install every defined generator. In the event that a generator is renamed, the new name will be generated, while the old name
+will no longer exist. This is similar to renaming a file. Note that the generator essence never goes away, as it will exist under some new name.
+It is simply tucked away until needed. Also, generators marked as skipped will not be installed.
+
+#### Object.better_skip(gen or [gen1, gen2, ...] or gen1, gen2, ...)
+
+This is to prevent a generator from installing by adding a skip attribute.
+Additionally, skipped generators cannot be uninstalled until the skip flag is removed.
+If a generator is first installed then given this skip attribute, it cannot be uninstalled.
+This acts as a protection.
+
+#### Object.better_unskip(gen or [gen1, gen2, ...] or gen1, gen2, ...)
+
+This removes the skip attribute enabling the generator to be installed or uninstalled.
+
+#### Object.better_skipped
+
+This returns an array of skipped generators.
+
+#### Object.better_install(gen or [gen1, gen2, ...] or gen1, gen2, ...)
+
+This will install a specific generator. 
+If you rename a generator, the old name no longer exists, so you must use the new name. See below:
+
+```ruby
+Object.better_rename(:in?, :is_in?)
+Object.better_install(:in?)          # Error
+Object.better_install(:is_in?)       # true
+Object.better_install(:is_in?)       # false  ... already installed
+
+str = "The cat in the hat is back"
+'cat'.is_in? str  # true
+```
+
+#### Object.better_uninstall_all
+
+This will remove all the generators from Object. Note that some generators spawn additional generators such as `:define_presence_of`.
+If this generator is ever run, `Object.better_uninstall_all` will not remove these second generation methods.
+Note that generators marked with the skip flag will not be uninstalled.
+
+#### Object.better_uninstall(gen or [gen1, gen2, ...] or gen1, gen2, ...)
+
+This will uninstall a specific generator or a set of generators.
+This method returns false if the generator is skipped, or already uninstalled; otherwise true is returned.
+If you installed a generator and wish to rename it, you must first uninstall it before you can rename it.
+See below:
+
+```ruby
+Object.better_install :local_methods
+"a string".local_methods  # [list of local methods]
+Object.better_rename(:local_methods, :methods_by_me)  # Error ... installed methods cannot be renamed
+Object.better_uninstall :local_methods
+Object.better_rename(:local_methods, :methods_by_me)
+Object.better_install :methods_by_me
+"a string".methods_by_me # [list of local methods]
+```
+
+#### Object.better_list(include_skip=false)
+
+This returns an array of generators that can be installed. Skipped generators can also be listed if you call this method with the value `true`.
+
+#### Object.better_installed
+
+This returns a list of installed generators. This does not list what the generators generate.
+
+#### Object.better_installed_instance_methods
+
+This gives us a list of generators that created instance methods. This does not list what the generators generate.
+
+#### Object.better_installed_class_methods
+
+This give us a list of generators that created class methods. This does not list what the generators generate.
+
+#### Object.better_rename(old_name, new_name)
+
+This allows us to rename a generator which in turn (most likely) renames what gets generated.
+This is an important feature as placing methods at the Object level has the danger of bumping into potential name conflicts.
+See the example below:
+
+```ruby
+Object.better_list.each do |old_name|
+  new_name = ("bjc_" + old_name.to_s).to_sym  # my initials
+  Object.better_rename(old_name, new_name) 
+end
+Object.better_install_all
+sorted_hash = {zoo:"animals", banana:"fruit"}.bjc_sort!  # == {banana:"fruit", zoo:"animals"}
+sorted_hash.bjc_tag?  # false
+sorted_hash.bjc_tag!
+sorted_hash.bjc_tag?  # true
+:zoo.bjc_in? hash  # true
+```
+
+#### Object.better_explain(:generator_name, pts=true)
+
+Calling this method without a generator name gives us a general list of the generators.
+Further details are revealed when a generator name is provided. The last default parameter puts the string to STOUT when true; otherwise,
+a string is returned.
+See example below:
+
+```ruby
+Object.better_explain(:in?)  #  obj.in?(enum) # ex:  3.in? [3,4,5] == true
+```
+
+#### Object.better_source_code(:generator_name, return_string = false, inner_only = false, type=:code)
+
+This will revel the source code for the generator. You can then copy and paste this in `irb` and experiment with it. See below:
+
+```ruby
+Object.better_source_code(:in?)
+
+class Object
+  def in?(enum)
+    enum.include? self
+  end    
+end
+```
+
+The parameter `return_string` will return a string instance when set true.
+The parameter `inner_only` when set true will remove the `class Object` and enclosing `end` statements.
+The final parameter is set to either `:code` or `:rm` depending on if you need the creation code or the deletion code.
+
+#### Object.better_define(meth_name, code, type, doc="*Undocumented*", rm_code=nil)
+
+This installs a user-defined generator. As an example we will create a `whotheheckami` generator as follows.
+```ruby
+doc = "same as .class"
+type = :both  # declares that :class and :instance will both be present
+meth_name = :whotheheckami
+code = "
+  def self.BO_METH_NAME
+    self.class
+  end
+  def BO_METH_NAME
+    self.class
+  end
+"
+Object.better_define(meth_name, code, type, doc)
+Object.better_list.include? :whotheheckami  # true
+Object.better_install :whotheheckami
+"".whotheheckami      # String
+String.whotheheckami  # Class
+```
+
+Note that we used the identifier name `BO_METH_NAME` instead of `whotheheckami`.
+This allows our generator to be renamed. 
+Generally speaking, the generator name need not be coupled with the method name, but that is the convention.
+Also, you can target a foreign object if you wish.
+The following example demonstrates updating String and also decouples the rename associations.
+
+```ruby
+doc = "some cool string methods"
+type = :instance
+meth_name = :string_methods
+code = "
+  String.class_eval do
+    def sort
+      self.split('').sort.join('')
+    end
+    def sort!
+      replace self.split('').sort.join('')
+    end
+    def histogram
+      hash = {}
+      self.split('').sort.each do |ch|
+        hash[ch] = hash[ch].nil? ? 1 : 1 + hash[ch]
+      end
+      return hash
+    end
+  end  
+"
+rm_code = "
+  String.class_eval do
+    undef sort
+    undef sort!
+    undef histogram 
+  end
+"
+Object.better_define(meth_name, code, type, doc, rm_code)
+Object.better_list.include? :string_methods  # true
+Object.better_install :string_methods
+"".string_methods      # Error
+"everybody".sort       # "bdeeorvyy"
+```
+
+In this case if you rename `:string_methods` you will only rename the generator.
+This method was used as a tool to create some of the generators. 
+Note that if you decouple the method name from the generator name, or target a foreign object,
+you must provide code to remove your methods.
+
+#### Generator list
+* `:local_methods`
+* `:inherited_methods`
+* `:replaced_methods`
+* `:derives_from?`
+* `:comes_from?`
+* `:define_presence_of`
+* `:in?`
+* `:to_literal`
+* `:pluralize`
+* `:parent`
+* `:sort!`
+* `:find_def`
+* `:tag`
+* `:functionize`
+
+
+#### Generator :local_methods(include_singleton_methods=true)
+
+This is an instance generator on Object. It is used on all objects that derive from Object (which is pretty much everything).
+The purpose is to view methods generated by the class of the instance and not the methods inherited by that class.
+This reduces the clutter considerably while introspecting the methods. See the example below:
+
+```ruby
+Object.better_install :local_methods  # run the generator
+
+class Fred < String
+  def a
+  end
+  def b
+  end
+end
+
+fred = Fred.new
+def fred.c; end
+fred.singleton_methods  # [:c]
+fred.local_methods  # [:a, :b, :c]
+fred.local_methods(false)  #[:a, :b]
+fred.methods        # [:a, :b, :dup, :clone, etc ...]  
+```
+
+#### Generator :inherited_methods
+
+This is an instance generator on Object. It is similar to `#methods`, except all locally defined methods are excluded.
+The combination of `#local_methods` and `#inherited_methods` is the same as `#methods`. See below:
+
+```ruby
+Object.better_install [:local_methods, :inherited_methods]
+
+class Fred < String
+  def a
+  end
+  def b
+  end
+end
+
+fred = Fred.new
+fred.methods.sort == [fred.local_methods + fred.inherited_methods].sort  # true
+``` 
+
+#### Generator :replaced_methods
+
+This is an instance generator on Object. This lets us discover which methods have been replaced during inheritance, or replaced due to a singleton method using the same name as an instance method. See the example below:
+
+```ruby
+Object.better_install :replaced_methods
+
+class Fred < String
+  def length
+  end
+end
+
+fred = Fred.new
+def fred.to_s
+end
+
+fred.replaced_methods  # [:length, :to_s]
+``` 
+
+#### Generators :derives_from? and :comes_from?
+
+These methods are both class methods on Object. The purpose is to test hierarchy of derived objects.
+The two class methods once generated are identical except `comes_from?` is more inclusive.
+See the example below:
+
+```ruby
+Object.better_install :derives_from?, :comes_from?
+
+class Fred < String
+  def a
+  end
+  def b
+  end
+end
+
+Fred.derives_from? String # true
+Fred.derives_from? Fred   # false
+Fred.derives_from? Object # true
+Fred.comes_from? Fred     # true
+Fred.comes_from? String   # true
+Fred.comes_from? Object   # true
+``` 
+
+#### Generators :define_presence_of(:target_method_name, target_default_value = true)
+
+This generator generates a generator!
+When installed, a class method is created on Object called `#define_presence_of`.
+This is called from a derived class such as String or Integer.
+The intent is to create a test for a certain type.
+This is a short-hand way of using the `#kind_of(CLASS_NAME)` method.
+See the example below:
+
+```ruby
+
+t1 = "fred"
+t2 = 123
+t1.kind_of? String  # true ... old way of doing things
+t2.kind_of? String  # false
+
+Object.better_install :define_presence_of
+
+String.define_presence_of(:string?)
+String.define_presence_of(:not_string?, false)
+Integer.define_presence_of(:int?, true)
+Integer.define_presence_of(:not_int?, false)
+
+t1.string?      # true
+t2.not_string?  # true
+t1.int?         # false
+t2.int?         # true
+[4].int?        # false ... it is an array
+``` 
+
+As we can see from the above code, we now have a shorter way of doing type checking.
+The generated generator defines an instance method on Object as well as the descendant class that calls it.
+Each method returns an opposite result.
+There are several base class gems (not mine) that force a certain naming convention; this one let's you pick the name!
+
+#### Generators :in?
+
+This generator allows us to swap the order of the standard `#include?` method with an improved comprehensive ordering.
+I saw this in another gem called ("object-in" by Tim Rogers), so I give him credit for the idea. It is included here because
+it is cool. This is probably the best name, but others (which you could rename to) could be: `:member_of`, `:is_in?`, `:in`, or `:element_of`. 
+See the example below:
+
+```ruby
+
+[1,2,3].include? 2  # true ... old way of doing things
+
+Object.better_install :in?
+
+2.in? [1,2,3]   # true
+'i'.in? "team"  # false
+``` 
+
+#### Generators :pluralize(meth_name, alt=nil)
+
+This generator installs a generator that mimics another method using a pluralized name.
+One of my pet peves is poorly named methods that are grammatically incorrect.
+From the String class, the method named `#start_with` should have been named `#starts_with`.
+This class method can be called from Object, String, or any class you wish.
+The pluralization is pretty smart, but if it does not quite work, you can provide the altername name in the second parameter. The new method name is returned. See the example below  
+
+```ruby
+
+Object.better_install :pluralize  # installs the first-level generator
+Object.pluralize :include?        # returns :includes?
+[1,2,3].includes? 2               # true
+
+String.pluralize :start_with?     # returns :starts_with?
+"whatever".starts_with? "wh"      # true
+
+Object.pluralize :respond_to?     # :responds_to?
+17.responds_to? :to_s             # true
+```
+
+#### Generators :parent
+
+This generator finds the first non-module ancestor of a class.
+The class Object's parent is always Object.
+This is a class method installed on Object.
+
+#### Generators :to_literal
+
+This is an alias for `#inspect`. In the event inspect fails, `#to_s` is then called.
+
+#### Generators :tag
+
+This generator creates a family of instance methods. If unrenamed, you will get: `#tag`, `#tag!`, `#untag`, `#tag?` and `#tag=`.
+If you rename this generator to :fred, you will get these: `#fred`, `#fred!`, `#unfred`, `#fred?`, `#fred=`.
+Note that uninstall will remove all five methods even if renamed.
+This method attaches a property to an instance of an Object or a derivative object. 
+Note that objects that have no constructors such as Integer, Float, NilClass, TrueClass, FalseClass and Symbol cannot be tagged.
+Also, frozen object instances cannot be tagged.
+You will need to place such objects either in a wrapper class or a use a container such as Array.
+A good container system is the gem `primitive_wrapper`.
+See the example below:
+
+```ruby
+ Object.better_install :tag
+
+ #tag        get current tag value
+ #tag=(val)  set tag's value to `val`
+ #tag!       set tag's value to true ... same as #tag=true
+ #tag?       returns true if tag's value is anything but nil, or false
+ #untag      set tag's value to false ... same as #tag=false
+
+ var1 = "Something to remember"
+ var1.tag?  # false
+ var1.tag   # nil
+ var1.tag!  # true
+ var1.tag   # true
+ var1.tag?  # true
+ var1.untag # false
+ var1.tag?  # false
+ var1.tag= "don't forget me!"
+ var1.tag?  # true
+ var1.tag   # "don't forget me!"
+ var1.untag # false
+ var1.tag?  # false
+ var1.tag   # false
+```
+
+#### Generators :sort!
+
+This method targets only the Hash class and creates the `#sort!` method.
+Hash has a method `#sort` that returns a sorted array of key value pairs.
+Obviously, they omitted the self modifying version because `Arrays` are not `Hashes`.
+See the example below:
+
+```ruby
+hash = {:zoo=>"Animals", :fruit=>"Banana", :better=>"Object"}
+hash.keys                         # [:zoo, :fruit, :better]
+Object.better_install :sort!
+Hash.respond_to? :sort!           # true
+hash.sort!         
+Hash.keys                         # [:better, :fruit, :zoo]
+```
+
+#### Generators :find_def
+
+This method locates the owner of either an instance method or a class method.
+The method expects a symbol representation of the method.
+The value `nil` is returned in the event that the method is undefined. 
+See the example below:
+
+```ruby
+Object.better_install :find_def
+tst = "".find_def :<        # tst = Comparable
+tst = 7.find_def  :<        # tst = Fixnum
+tst = 7.find_def  :to_int   # tst = Integer
+tst = 7.find_def  :to_c     # tst = Numeric
+tst = Fixnum.find_def :to_s # tst = Module
+tst = Fixnum.find_def :new  # tst = nil
+tst = "nope".find_def :foo  # tst = nil
+```
+
+#### Generators :functionize(meth = :new)
+
+This method makes your class look like a method that you simply call on the class constant.
+If you examine the `Rational` class, there is no `#new` constructor at all.
+Instead, you call `Rational(2,3)` which creates the object.
+On your own class object, the default will call `#new` adding shorter syntax candy.
+This allows less typing to create the object.
+You can also provide any class method you wish, but because you only get one, probably best if it were a constructor.
+See the example below:
+
+```ruby
+Object.better_install :functionize
+class Clown
+  def initialize(prm1, prm2)
+    @prms = [prm1, prm2]
+  end
+end
+
+Clown.functionize
+obj1 = Clown(:one, :two)         # fast way
+obj2 = Clown.new(:three, :four)  # slow way
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`.
+
+## Contributing
+
+I need to control this for the time being.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
+