more doc

1 files changed, 92 insertions, 8 deletions

diff --git a/README.md b/README.md
index 71c4913..834ef40 100644
--- a/README.md
+++ b/README.md
@@ -329,13 +329,16 @@ If one wants a named argument call, `object:method{name1=arg1, ...}` stands for
 ```lua
 method(object, {name1=arg1, ...})
 ```
+Note that handling such cases is not that trivial, because in normal
+(non-method) named calls, only one table is allowed as argument (and not a
+first argument followed by a table).
 
 Argcheck handles nicely these type of calls, as long as the object argument is named
 `self`. Here is a complete example:
 
 ```lua
 -- the Rectangle class metatable
-local Rectangle = {}
+Rectangle = {}
 
 -- the constructor
 Rectangle.new = argcheck{
@@ -364,13 +367,17 @@ Rectangle.display = argcheck{
 }
 
 -- create a new Rectangle
-local rect = Rectangle.new(5, 7, 10, 20)
+rect = Rectangle.new(5, 7, 10, 20)
 
 -- display it 3 times
-rect:display(3)
+> rect:display(3)
+
+Rectangle x=5 y=7 w=10 h=20
+Rectangle x=5 y=7 w=10 h=20
+Rectangle x=5 y=7 w=10 h=20
 
 -- show the help
-rect:display()
+> rect:display()
 
 display N times the object
 
@@ -389,11 +396,87 @@ Note: in the above example we do not check the type of the object
 be explained later in the advanced usage section.
 * * *
 
-### Multiple cases
+#### Generating both a function and a method at once
+
+In an object-oriented settings, it is sometimes useful to provide a way to
+call a method `object:method(arg1, ...)` as a function `method(object, arg1, ...)`. If
+one does not use named argument calls, the function generated by argcheck for the method
+should be fine. However, with named argument calls, for a given method
+```lua
+object:method{name1=arg1, ...}
+```
+one would probably like a function `func` which does the same with:
+```lua
+func{obj=object, name1=arg1, ...}
+```lua
+instead of
+```lua
+method(object, {name1=arg1, ...})
+```
+which looks more awkward.
+
+Argcheck allows you to generate both these method and function at once, and even alter
+the arguments (e.g. if they are optional or not) between the function and the method versions.
+
+Following the previous Rectangle class example, here is what could be done:
+```lua
+display, Rectangle.display = argcheck{
+   {help='display N times the object',
+    self='obj', -- specify which argument is going to act as 'self' for the method
+    {name='obj'},
+    {name='N', type='number', opt=true, method={opt=false}}}, -- non-optional argument for the method version
+   function(self, N)
+      N = N or 1
+      for i=1,N do
+         print(string.format('Rectangle x=%g y=%g w=%g h=%g',
+                             self.x, self.y, self.w, self.h))
+      end
+   end
+}
+
+-- create a new Rectangle
+> rect = Rectangle.new(5, 7, 10, 20)
+
+-- use the method
+> rect:display(3)
+
+Rectangle x=5 y=7 w=10 h=20
+Rectangle x=5 y=7 w=10 h=20
+Rectangle x=5 y=7 w=10 h=20
+
+-- use the function
+> display(rect)
+
+Rectangle x=5 y=7 w=10 h=20
+
+-- usage for the function
+> display()
+
+display N times the object
+
+> arguments:
+{
+   obj            -- 
+  [N   = number]  -- 
+}
+     
+-- usage for the method
+> rect:display()
+
+display N times the object
 
-In some cases, one would like that the same function handles several very
+> arguments:
+{
+   self           -- 
+   N    = number  -- 
+}   
+```
+
+### Handling multiple heterogeneous cases
+
+Sometimes one would like that the same function handles several very
 different cases. Take the example of a fictive `inc()` function, which
-would add one to a number, if a number is given as argument, or would
+would add one to a number if a number is given as argument, or would
 concatenate a letter to a string, if a string and a letter bytecode are
 given as argument.
 
@@ -446,7 +529,7 @@ inc = argcheck{ -- note the difference here
 
 > = inc()
 
-Increment a number or a string.                                                                                                                
+Increment a number or a string.
 
 Increment a number by 1
 
@@ -466,3 +549,4 @@ Add a letter to a string
 }
 
 ```
+