<commit_before>= MetaProgramming

Various meta-programming methods and 'spells' for Ruby

== Resources

Install

* sudo gem install meta_programming

Use

* require 'meta_programming'

Concepts/Terminology

* Metaprogramming_Ruby[http://pragprog.com/titles/ppmetr/metaprogramming-ruby]

Example Code

* why_not[http://github.com/jeffp/why_not/blob/master/lib/why_not.rb]
* easy_nils[http://github.com/jeffp/easy_nils/blob/master/lib/easy_nils.rb]

== Beta Status

I consider this Gem in personal beta and suspect it will be in this state for
a while.  If you use it, expect changes that may break your code until the
lexigraph has a chance to mature.

If you include metaprogramming in your projects, I suggest you limit the version
dependency to 0.2.x, something like

  s.add_dependency('meta_programming', '>= 0.2.0', '< 0.3.0')

Any 0.2.x version will be backward compatible with any earlier 0.2.x version.  A
bump to 0.3.0 cannot be guaranteed backward compatible.

I welcome comments and collaborators who
would like to develop a library for simplifying common patterns and limit
the pitfalls of Ruby meta-programming.

== Changelog

* 0.2.0

Removes object parameter from method blocks and lambda matchers in define_ghost_method, and
adds more descriptive error handling.  define_ghost_method block and matchers are now
evaluated in the context of the object instance.

I've bumped the version to 0.2.0 because this changes the interface.

* 0.0.8

initial implementation


== Issues

=== 1.9 vs 1.8

There are considerable differences with the way that Ruby 1.9 and 1.8 handle dynamic
methods, procs and lambdas.  For instance, Ruby 1.8.x cannot handle default parameter
values in the block parameter list

  call_some_method(*args) do |param1, param2=nil| #oops for Ruby 1.8
    ...
  end

This raises support issues for this library.  Should the library fully support both versions
of Ruby, cripple 1.8 at the expense of 1.9, or kiss the past good-bye and only support version 1.9?
Of course, the latter is clearer and easier, and may be the best path to pursue.

	
== Description

Current Methods
* eigenclass (or metaclass)
* safe_alias_method_chain
* define_chained_method
* define_method_missing_chain
* define_ghost_method
* blank_slate


== Usage

=== define_ghost_method

+define_ghost_method+ creates a 'ghost' method for an undefined method that corresponds
to the 'matcher' parameter.

  define_ghost_method(matcher) do |method_name_symbol, *args|
    ...method body...
  end

A block must be present and it takes (optionally) the receiving object, the method name (as
a symbol with exception of a lambda matcher) and the method arguments.  As of 0.2.0, the
block and lambda matcher is evaluated in the context of the object.

The matcher may be any of a symbol, string, regular expression or Proc/lambda.

==== String, symbols and regular expression matchers

  define_ghost_method('my_method) {|sym, *args| ... }
  define_ghost_method(:my_method) {|sym, *args| ... }
  define_ghost_method(/^my_method$/) {|sym, *args| ... }

String and symbol matchers will only process the method if its name matches the string
or symbol exactly.  Regular expressions provide greater flexibility and care must be
taken to define scrutinizing regular expression matchers.  It is a good practice to use
the /^ and $/ matchers to limit the scope.

In all cases, the method name is passed in the second parameter as a symbol to the
method block.  This is not the case with lambda matchers.

==== Proc/lambda matchers

Lambda matchers provide an opportunity to greatly scrutinize the method call.  The method is
invoked for any lambda not evaluating to nil or false.

  proc = lambda{|method_name, *args| ...matching code... }
  define_ghost_method(proc) {|proc_result, *args| ... }

Proc and lambda matchers differ from the other matcher in that the second parameter passes
the result of the Proc/lambda matcher to the method block.  This feature lets the matcher
pre-process the name of the method passed to the body.

  proc = lambda{|sym, *args| sym =~ /^not_(.+\?)$/ && self.class.method_defined?($1.to_sym) && $1.to_sym }

The lambda matcher is evaluated in the context of the object and can
call methods of the object as in the above example.  The lambda matcher is also called
in the respond_to? method, so it is a good idea to avoid usind respond_to? in the lambda
matcher to avoid a stack overflow error.  Instead call method_defined? on the class object.

The extra flexibility comes at greater responsibility.  If you only want to pass the
method name symbol to the method block, don't forget to return it from the lambda.

  proc = lambda{|sym, *args| sym =~ /^not_.+\?$/ && sym }


==== Critique

2010.04.30

I'm not satisfied with the ghost method implementation.

2010.05.02

I like the fact that define_ghost_method blocks and lambda matchers are now evaluated
in the context of the object and that the object is no longer passed into the method block
and lambda matcher.  The method feels more akin to its cousin, +define_method+.

== Testing

Passes for Ruby
* 1.8.7
* 1.9.1

== Dependencies

none<commit_msg>updates README<commit_after>= MetaProgramming

Various meta-programming methods and 'spells' for Ruby

== Resources

Install

* sudo gem install meta_programming

Use

* require 'meta_programming'

Concepts/Terminology

* Metaprogramming_Ruby[http://pragprog.com/titles/ppmetr/metaprogramming-ruby]

Example Code

* why_not[http://github.com/jeffp/why_not/blob/master/lib/why_not.rb]
* easy_nils[http://github.com/jeffp/easy_nils/blob/master/lib/easy_nils.rb]

== Beta Status

I consider this Gem in personal beta and suspect it will be in this state for
a while.  If you use it, expect changes that may break your code until the
lexigraph has a chance to mature.

If you include metaprogramming in your projects, I suggest you limit the version
dependency to 0.2.x, something like

  s.add_dependency('meta_programming', '>= 0.2.0', '< 0.3.0')

Any 0.2.x version will be backward compatible with any earlier 0.2.x version.  A
bump to 0.3.0 cannot be guaranteed backward compatible.

I welcome comments and collaborators who
would like to develop a library for simplifying common patterns and limit
the pitfalls of Ruby meta-programming.

== Changelog

* 0.2.0

Removes object parameter from method blocks and lambda matchers in define_ghost_method, and
adds more descriptive error handling.  define_ghost_method block and matchers are now
evaluated in the context of the object instance.

I've bumped the version to 0.2.0 because this changes the interface.

* 0.0.8

initial implementation


== Issues

=== 1.9 vs 1.8

There are considerable differences with the way that Ruby 1.9 and 1.8 handle dynamic
methods, procs and lambdas.  For instance, Ruby 1.8.x cannot handle default parameter
values in the block parameter list

  call_some_method(*args) do |param1, param2=nil| #oops for Ruby 1.8
    ...
  end

This raises support issues for this library.  Should the library fully support both versions
of Ruby, cripple 1.8 at the expense of 1.9, or kiss the past good-bye and only support version 1.9?
Of course, the latter is clearer and easier, and may be the best path to pursue.

	
== Description

Current Methods
* eigenclass (or metaclass)
* safe_alias_method_chain
* define_chained_method
* define_method_missing_chain
* define_ghost_method
* blank_slate


== Usage

=== define_ghost_method

+define_ghost_method+ creates a 'ghost' method for an undefined method that corresponds
to the 'matcher' parameter.

  define_ghost_method(matcher) do |method_name_symbol, *args|
    ...method body...
  end

A block must be present and it takes (optionally) the receiving object, the method name (as
a symbol with exception of a lambda matcher) and the method arguments.  As of 0.2.0, the
block and lambda matcher is evaluated in the context of the object.

The matcher may be any of a symbol, string, regular expression or Proc/lambda.

==== String, symbols and regular expression matchers

  define_ghost_method('my_method) {|sym, *args| ... }
  define_ghost_method(:my_method) {|sym, *args| ... }
  define_ghost_method(/^my_method$/) {|sym, *args| ... }

String and symbol matchers will only process the method if its name matches the string
or symbol exactly.  Regular expressions provide greater flexibility and care must be
taken to define scrutinizing regular expression matchers.  It is a good practice to use
the /^ and $/ matchers to limit the scope.

In all cases, the method name is passed in the second parameter as a symbol to the
method block.  This is not the case with lambda matchers.

==== Proc/lambda matchers

Lambda matchers provide an opportunity to greatly scrutinize the method call.  The method is
invoked for any lambda not evaluating to nil or false.

  proc = lambda{|method_name| ...matching code... }
  define_ghost_method(proc) {|proc_result, *args| ... }

Proc and lambda matchers differ from the other matcher in that the second parameter passes
the result of the Proc/lambda matcher to the method block.  This feature lets the matcher
pre-process the name of the method passed to the body.

  proc = lambda{|sym| sym =~ /^not_(.+\?)$/ && self.class.method_defined?($1.to_sym) && $1.to_sym }

The lambda matcher is evaluated in the context of the object and can
call methods of the object as in the above example.  The lambda matcher is also called
in the respond_to? method, so it is a good idea to avoid usind respond_to? in the lambda
matcher to avoid a stack overflow error.  Instead call method_defined? on the class object.

The extra flexibility comes at greater responsibility.  If you only want to pass the
method name symbol to the method block, don't forget to return it from the lambda.

  proc = lambda{|sym| sym =~ /^not_.+\?$/ && sym }


==== Critique

2010.04.30

I'm not satisfied with the ghost method implementation.

2010.05.02

I like the fact that define_ghost_method blocks and lambda matchers are now evaluated
in the context of the object and that the object is no longer passed into the method block
and lambda matcher.  The method now behaves similarly to its cousin, +define_method+.

== Testing

Passes for Ruby
* 1.8.7
* 1.9.1

== Dependencies

none
{'fraction_non_alphanumeric': 0.07087075361187037, 'fraction_numerical': 0.013861772745021476, 'mean_word_length': 4.140491721023583, 'pattern_counts': {'":': 0, '<': 5, '<?xml version=': 0, '>': 5, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4169800', 'n_tokens_mistral': 3111, 'n_tokens_neox': 2930, 'n_words': 1379}