konstructor 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: c470538008607d588c03a3f68fefb7800a88f83b
-  data.tar.gz: 6517dba98cd9ad1f387d9410dcbbc7d04b19accb
+  metadata.gz: 1a639335de2f050fdd01c8504178cc934204ada8
+  data.tar.gz: d6a81f610da6159060b39b9209a4a0913b2fe7c2
 SHA512:
-  metadata.gz: 0f4bcbf89a42a476af95f78bc08f33d314696f8da99f7c2120f059931d693c4eee149fd39bc64fbec79897d626f2c720a5a85d4def50ddedeae31422492f25d8
-  data.tar.gz: 0ff11473769c2673730bf80222699ee2501067c7cc4e37432a3ab14882ad005a45f75fd4188a6499998ae47460d8d626c80f93a8b2084df2db4e136f36433d5a
+  metadata.gz: ae74c9aedf9971bd55fd2d709014631f39d1cff931d3d460b8084f30de57fe881599b264c657aa5431178d2aea5fa900d6820bc32e76c9b6f91422788f0e7707
+  data.tar.gz: eb8be3d92e5c96bd2a15580f8ec1dde0bf5d0a0648f58eabec393d321e27ffc74f3871aa62e931074f2e52cec1f58bb065dec898390c5b3e23dae5a9595bd6a7

data/README.md

@@ -11,7 +11,7 @@
 Konstructor is a small gem that gives you multiple
 constructors in Ruby.
 
-Use `konstructor` keyword to define constructors additional to the defaul one:
+Use `konstructor` keyword to declare constructors additional to the defaul one:
 ```ruby
 class SomeClass
   konstructor
@@ -44,40 +44,43 @@ You can also install it without Bundler:
 
     $ gem install konstructor
 
-If you wish to manually include Konstructor in your classes only when
-you need it, see [Manual include](https://github.com/snovity/konstructor/wiki/Manual-include) page.
+If you are a gem author or just wish to manually include `konstructor` 
+keyword in your classes only when you need it, see 
+[Manual include](https://github.com/snovity/konstructor/wiki/Manual-include) page.
    
 ## Usage
 
-In simplest form `konstructor` creates a constructor from the next method.
+In its simplest form `konstructor` declaration creates a 
+constructor from the next method.
 
  ```ruby
- konstructor
- def create
- end
+  konstructor
+  def create
+  end
  
- konstructor
- def recreate
- end
+  konstructor
+  def recreate
+  end
  ```
  
 When method names are given, it creates constructors from 
 those methods without affecting the next method.
  
  ```ruby
- konstructor :create, :recreate
+  konstructor :create, :recreate
  
- def not_constructor
- end
+  def not_constructor
+  end
  
- def create
- end
+  def create
+  end
  
- def recreate
- end
+  def recreate
+  end
  ```
  
- Call with method names can be placed anywhere in class definition.
+ Declaration with method names can be placed anywhere in 
+ class definition.
  
  ```ruby
   def create
@@ -89,7 +92,7 @@ those methods without affecting the next method.
   end
  ```
  
- In all above cases the class will have the default constructor 
+ In all above cases `SomeClass` will have the default constructor 
  and two additional ones.
  
  ```ruby
@@ -98,18 +101,28 @@ those methods without affecting the next method.
  obj2 = SomeClass.recreate
  ```
  
-### Same as default constructor
+ If you decide to remove the default Ruby constructor for some reason,
+ you can effectively do it by marking it as private using Ruby 
+ method `private_class_method`:
+ 
+ ```ruby
+ class SomeClass
+   private_class_method :new
+ end   
+ ```
+  
+#### Same as default constructor
  
-Additional constructors work exactly the same way as 
-built-in Ruby constructor. 
+Additional constructors work exactly the same way as the default one.
 
 You can pass blocks to them. 
 
 ```ruby
-konstructor
-def create(val)
-  @val = yield val
-end
+  konstructor
+  def create(val)
+    @val = yield val
+  end
+  #...
 
 obj = SomeClass.create(3) { |v| v*3 }
 obj.val # 9
@@ -135,64 +148,45 @@ end
 obj = SomeSubclass.create(2, 3)
 obj.val # 6
 ``` 
-Once method is a marked as konstructor in hierarchy, 
-it is always a konstructor.
-                                   
-Methods inherited from superclasses can't become konstructors in 
-subclasses. To achieve the effect, define a new method, 
-mark it as konstructor and call the inherited one. 
-
-### Reserved names
-
-Using reserved method names `new` and `initialize` for additional 
-constructor declaration will raise an error:
-```ruby
-konstructor
-def initialize # raises Konstructor::ReservedNameError
-end
-```
-or
-```ruby
-konstructor
-def new # raises Konstructor::ReservedNameError
-end
-```
-
-### Defining konstructors in Modules
+Once method is declared as `konstructor` in hierarchy, 
+it is always a constructor.
 
-Modules can't have konstructors. Use `ActiveSupport::Concern` and 
-define konstructor in `included` block.
+There are certain limitations to what can be declared as `konstructor`, 
+see 
+[Limitations page](https://github.com/snovity/konstructor/wiki/Limitations)
+for details.
 
-### Using with other gems
+#### Using with other gems
 
 Konstructor doesn't affect other gems, including those
-that depend on metaprogramming, such as [rake](https://github.com/ruby/rake), [thor](https://github.com/erikhuda/thor), [contracts](https://github.com/egonSchiele/contracts.ruby), etc.
+that depend on metaprogramming, such as 
+[rake](https://github.com/ruby/rake),
+[thor](https://github.com/erikhuda/thor), 
+[contracts](https://github.com/egonSchiele/contracts.ruby), etc.
 
-For instnace, this is how Konstructor works with contracts gem:
+For instnace, this is how Konstructor works with contracts:
 ```ruby
-  class SomeClass
-    konstructor
-    Contract Num => SomeClass
-    def create(some_number)
-      @number = some_number
-    end
-  end    
+class SomeClass
+  konstructor
+  Contract Num => SomeClass
+  def create(some_number)
+    @number = some_number
+  end
+end    
 ```
   
 If you stumble upon a metaprogramming gem that 
-conflicts with Konstructor, please [open an issue](https://github.com/snovity/konstructor/issues/new).
+conflicts with Konstructor, please 
+[open an issue](https://github.com/snovity/konstructor/issues/new).
+  
+## Details
 
-### Removing default constructor
+Ruby constructor is a pair consisting of public factory method defined
+on a class and a private instance method. Therefore, to achieve 
+its goal `konstructor` marks instance method as private and defines a 
+corresponding public class method with the same name.
 
-You can effectively remove default Ruby constructor
-by marking it as private:
-```ruby
-class SomeClass
-  private_class_method :new
-end   
-```
- 
-## Performance
+#### Performance
  
 Konstructor does all its work when class is being defined. Once class
 has been defined, it's just standard Ruby instance creation.
@@ -200,34 +194,9 @@ Therefore, there is no runtime performance penalty.
 
 Konstructor doesn't depend on other gems.
   
-## Thread safety
+#### Thread safety
   
 Konstructor is thread safe.
-  
-## Details
-
-Ruby constructor is a pair consisting of public factory method defined
-on a class and a private instance method. Therefore, to achieve 
-its goal `konstructor` marks instance method as private and defines a 
-corresponding public class method with the same name.
-
-You can check if certain instance method name has been declared as 
-constructor or is a default constructor by running.
-```ruby
-Konstructor.is?(SomeClass, :initialize) # true
-Konstructor.is?(SomeClass, :create) # true
-Konstructor.is?(SomeClass, :recreate) # true
-Konstructor.is?(SomeClass, :something_else) # false
-``` 
- 
-It will return true even if no such constructor has 
-been defined yet. Like:
-```ruby
-class SomeClass
-  konstructor :create
-end
-```
-Konstructor body may be supplied in subclasses.
 
 ## Contributing
 

data/lib/konstructor/exceptions.rb

@@ -10,7 +10,14 @@ module Konstructor
   class IncludeInModuleError < StandardError
     def initialize(base)
       super "Konstructor can't be included in module '#{base.name}' directly, " +
-            "please, use ActiveSupport::Concern or included hook directly."
+            "please, use ActiveSupport::Concern or standard included hook."
+    end
+  end
+
+  class DeclaringInheritedError < StandardError
+    def initialize(name)
+      super "You are declaring an inherited method '#{name}' as konstructor, "
+            "this is not allowed."
     end
   end
 

data/lib/konstructor/factory.rb

@@ -29,9 +29,9 @@ module Konstructor
       if @next_method_is_konstructor
         @next_method_is_konstructor = false
         @konstructor_names << name
-        define(name)
+        process_declaration(name)
       elsif declared?(name)
-        define(name)
+        process_declaration(name)
       end
     end
 
@@ -58,29 +58,41 @@ module Konstructor
       @konstructor_names.concat(new_names)
 
       new_names.each do |name|
-        if has_own_method?(name)
-          define(name)
+        if method_in_hierarchy?(name)
+          process_declaration(name)
         else
-          # not sure if konstructor ever will be defined,
-          # but informing about the problem anyway
-          validate_name(name)
+          # not sure if method will ever be defined,
+          # but validating its name anyway
+          validate_name!(name)
         end
       end
     end
 
-    def has_own_method?(name)
-      method_defined = @klass.method_defined?(name) || @klass.private_method_defined?(name)
-      superclass_method_defined = @klass.respond_to?(:superclass) && (
-        @klass.superclass.method_defined?(name) || @klass.superclass.private_method_defined?(name)
-      )
-      method_defined && !superclass_method_defined
+    def method_in_hierarchy?(name)
+      method_defined?(@klass, name)
+    end
+
+    def method_on_superclass?(name)
+      @klass.respond_to?(:superclass) && method_defined?(@klass.superclass, name)
+    end
+
+    def method_defined?(klass, name)
+      klass.method_defined?(name) || klass.private_method_defined?(name)
     end
 
     # this method is idempotent
-    def define(name)
-      validate_name(name)
+    def process_declaration(name)
+      validate_name!(name)
 
-      # defining class method
+      if method_on_superclass?(name) && !declared_in_superclass?(name)
+        raise DeclaringInheritedError, name
+      end
+
+      define_factory(name)
+      mark_as_private(name)
+    end
+
+    def define_factory(name)
       @klass.instance_eval <<-RUBY, __FILE__, __LINE__ + 1
         def #{name}(*args, &block)
           instance = allocate
@@ -88,12 +100,13 @@ module Konstructor
           instance
         end
       RUBY
+    end
 
-      # marking instance method as private
+    def mark_as_private(name)
       @klass.__send__(:private, name)
     end
 
-    def validate_name(name)
+    def validate_name!(name)
       if Konstructor.reserved?(name)
         raise ReservedNameError, name
       end

data/lib/konstructor/version.rb

@@ -1,3 +1,3 @@
 module Konstructor
-  VERSION = '0.2.0'
+  VERSION = '0.3.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: konstructor
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Dima Lashkov