X-Git-Url: http://git.vpit.fr/?p=perl%2Fmodules%2Fwith.git;a=blobdiff_plain;f=README;h=601f9f9cec53e016cdaf398fd48555cb2a8c03fa;hp=b90723bd1cccb88f61554d8ef90eeebbe2cde456;hb=HEAD;hpb=7d694e6f49e219b9c5f62d323666ca2854d51f50

diff --git a/README b/README
index b90723b..601f9f9 100644
--- a/README
+++ b/README
@@ -2,7 +2,13 @@ NAME
     with - Lexically call methods with a default object.
 
 VERSION
-    Version 0.01
+    Version 0.03
+
+WARNING
+    This module was an early experiment which turned out to be completely
+    unpractical. Therefore its use is officially deprecated. Please don't
+    use it, and don't hesitate to contact me if you want to reuse the
+    namespace.
 
 SYNOPSIS
         package Deuce;
@@ -11,6 +17,7 @@ SYNOPSIS
 
         sub hlagh { my $self = shift; print "Deuce::hlagh $self->{id}\n" }
 
+
         package Pants;
 
         sub hlagh { print "Pants::hlagh\n" }
@@ -25,7 +32,7 @@ SYNOPSIS
          use with \$deuce;
          hlagh;        # Deuce::hlagh 1
          Pants::hlagh; # Pants::hlagh
- 
+
          {
           use with \Deuce->new(2);
           hlagh;       # Deuce::hlagh 2
@@ -47,19 +54,19 @@ DESCRIPTION
     will be the last specified one.
 
 HOW DOES IT WORK
-    The main problem to address is that lexical scope and source
-    modifications can only occur at compile time, while object creation and
+    The main problem to address is that lexical scoping and source
+    modification can only occur at compile time, while object creation and
     method resolution happen at run-time.
 
     The "use with \$obj" statement stores an address to the variable $obj in
     the "with" field of the hints hash "%^H". It also starts a source filter
     that replaces function calls with calls to "with::defer", passing the
     name of the original function as the first argument. When the replaced
-    function is part of Perl core, the call is deferred to a corresponding
-    wrapper generated in the "with" namespace. Some keywords that couldn't
-    possibly be replaced are also completely skipped. "no with" undefines
-    the hint and deletes the source filter, stopping any subsequent
-    modification in the current scope.
+    function has a prototype or is part of the core, the call is deferred to
+    a corresponding wrapper generated in the "with" namespace. Some keywords
+    that couldn't possibly be replaced are also completely skipped. "no
+    with" undefines the hint and deletes the source filter, stopping any
+    subsequent modification in the current scope.
 
     When the script is executed, deferred calls first fetch the default
     object back from the address stored into the hint. If the object "->can"
@@ -67,15 +74,15 @@ HOW DOES IT WORK
     namespace is inspected for a subroutine with the proper name, and if
     it's present the program "goto"s into it. If that fails too, the core
     function with the same name is recalled if possible, or an "Undefined
-    subroutine" warning is thrown.
+    subroutine" error is thrown.
 
 IGNORED KEYWORDS
-    A call will never dispatch to methods whose name is part of :
+    A call will never be dispatched to a method whose name is one of :
 
         my our local sub do eval goto return
-        if else elsif unless given when or and 
+        if else elsif unless given when or and
         while until for foreach next redo last continue
-        eq ne lt gt le ge
+        eq ne lt gt le ge cmp
         map grep system exec sort print say
         new
         STDIN STDOUT STDERR
@@ -90,6 +97,16 @@ CAVEATS
 
     Don't put anything on the same line of "use with \$obj" or "no with".
 
+    When there's a function in the caller namespace that has a core function
+    name, and when no method with the same name is present, the ambiguity is
+    resolved in favor of the caller namespace. That's different from the
+    usual perl semantics where "sub push; push @a, 1" gets resolved to
+    CORE::push.
+
+    If a method has the same name as a prototyped function in the caller
+    namespace, and if a called is deferred to the method, it will have its
+    arguments passed by value.
+
 DEPENDENCIES
     perl 5.9.4.
 
@@ -102,8 +119,7 @@ DEPENDENCIES
 AUTHOR
     Vincent Pit, "<perl at profvince.com>", <http://www.profvince.com>.
 
-    You can contact me by mail or on #perl @ FreeNode (vincent or
-    Prof_Vince).
+    You can contact me by mail or on "irc.perl.org" (vincent).
 
 BUGS
     Please report any bugs or feature requests to "bug-with at rt.cpan.org",
@@ -123,7 +139,7 @@ ACKNOWLEDGEMENTS
     order to add hints support and more placeholder patterns.
 
 COPYRIGHT & LICENSE
-    Copyright 2008 Vincent Pit, all rights reserved.
+    Copyright 2008,2017 Vincent Pit, all rights reserved.
 
     This program is free software; you can redistribute it and/or modify it
     under the same terms as Perl itself.