Named Parameters

Makes your methods callable with named parameters

Get it

Surprisingly it is this easy:

gem install named_parameters

Use it

First, include NamedParameters:

class AnyClass
    include NamedParameters
end

Second, call the macro:

class AnyClass
    include NamedParameters
    named_parameters
end

Last, but not least, define your method:

class AnyClass
    include NamedParameters
    named_parameters
    def some_method(a,b,c)
        #... do something
    end
end

Call it

any_object = AnyClass.new
any_object.some_method(a: "here comes the 'a' parameter",
                       c: "this is for c"
                       b: 42)

Optional parameters

You may also define optional parameters with defaults values:

class AnyClass
    named_parameters(a: "default a", b: "default b")
    def some_method(a,b)
        [a,b]
    end
end

The call is just the same:

any_object.some_method(a: "actual a") # =>  ["actual a", "default b"]
any_object.some_method(b: "actual b") # =>  ["default a", "actual b"]
any_object.some_method                # =>  ["default a", "default b"]

Optional and mandatory parameters

You can have both optional and mandatory parameters for the same method. All parameters with no default value are mandatory:

class AnyClass
    named_parameters(a: "default a")
    def some_method(a,b,c)
        [a,b,c]
    end
end
any_object.some_method(b: "given",
                       c: nil) # => ["default a", "given", nil]
any_object.some_method(b: "given",
                       a: "overwritten") # =>  Error: Mandatory parameter 'c' not given

Blocks

Blocks are not interfered by named_parameters. You can just use them as usual.

class AnyClass
    named_parameters(a: [])
    def some_method(a)
        a.each {|e| yield e}
    end
end
any_object.some_method(a: %w(hello world)) {|s| s.upcase!} # => ["HELLO", "WORLD"]

Strict mode

Strict mode means, that keys in the named parameters hash, that are not part of the parameter definition of your method, will raise a RuntimeError. You can use it like this:

class AnyClass
    named_parameters_strict(a: "default a")
    def some_method(a)
        a
    end
end
any_object.some_method(a: "given",
                       b: "more parameters") # => Error 'Parameter "b" is not accepted by method "some_method"'

Super mode

Super mode means, that the super method will be called, with the named parameter hash as only parameter. This can be useful if some library, that makes use of named parameters, demands you to call super. Remember you cannot access the actual named parameters hash. Use the super mode like this:

class SomeLibraryClass
    def setup(options)
        @d = options[:d]
    end
end
class AnyClass
    named_parameters_super
    def setup(a,b,c)
        @a = a
        @b = b
        @c = c
    end
end
any_object.setup(a: "a",
                 b: "b",
                 c: "c",
                 d: "d")
any_object.a # => "a"
any_object.b # => "b"
any_object.c # => "c"
any_object.d # => "d"

Combine super and strict

In case you need to combine super and strict mode, do:

class AnyClass < SomeLibraryClass
    named_parameters_strict_super # or named_parameters_super_strict
    def some_method(a,b,c)
        # do something with a and b, maybe something with c will be done in super
    end
end

<my_method>_has_named_parameters

There are actually two ways to make a your method accessible with named parameters. You can either declare the named parameters just before the method definition (this is done above) or you can define them anytime after the method definition:

class AnyClass
    def some_method(a,b,c)
        # do something with a, b and c
    end
    # lots of other code, if you like so
    # ...
    some_method_has_named_parameters(a: "a", b: "b")
end

This will do the same as:

class AnyClass
    named_parameters(a: "a", b: "b")
    def some_method(a,b,c)
        # do something with a, b and c
    end
end

With this method you can also use super and strict mode as usual

Acknowledgements

Kudos to Juris Galang and his gem named-parameters. (www.rubygems.org/gems/named-parameters) Definitely have a look at this gem also, if you want to use named parameters.

Changelog

1.1.1

• Added documentation for ghost methods “my_method_has_named_parameters”

1.1.0

• Added ghost methods “my_method_has_named_parameters”

1.0.2

• Removed unimportant methods from documentation (again)

1.0.1

• Removed unimportant methods from documentation

1.0.0

• Added strict and super modes

• Smoother implementation

  * Better structured code
  * More comments
  * Proper around alias instead of rebinding the method
  

• Is not strict on default any more

0.1.4

• Changed visibility in documentation

0.1.3

• Made LICENSE visible to documentation (Sorry for that)

• Made actual name space and NamedParameters#named_parameters macro visible to documentation

0.1.2

• Changed headings in documentation

0.1.1

• Added documentation for blocks

0.1.0

• First release