# HG changeset patch
# User Paul Boddie <paul@boddie.org.uk>
# Date 1242430443 -7200
# Node ID 398f466a7011d7b64f5f80818aec2cc358ffdc49
# Parent  3063e2b7ff639b58aad1c2f8ad5de6fc3e7214fe
Added notes about star parameter handling approaches.
Made minor documentation/comment fixes.

diff -r 3063e2b7ff63 -r 398f466a7011 docs/concepts.txt
--- a/docs/concepts.txt	Mon May 11 02:17:12 2009 +0200
+++ b/docs/concepts.txt	Sat May 16 01:34:03 2009 +0200
@@ -221,6 +221,8 @@
 removed and the attrcode is not specified for classes: the presence of an
 attrcode indicates that a given object is an instance.
 
+See below for details of attrcodes.
+
 Invocation Reference
 --------------------
 
@@ -301,7 +303,7 @@
 the attribute locations to store their elements, where each element is a
 reference to a separately stored object.
 
-Testing Instance Compatibility with Classes (attrcode)
+Testing Instance Compatibility with Classes (Attrcode)
 ------------------------------------------------------
 
 Although it would be possible to have a data structure mapping classes to
diff -r 3063e2b7ff63 -r 398f466a7011 docs/invocation.txt
--- a/docs/invocation.txt	Mon May 11 02:17:12 2009 +0200
+++ b/docs/invocation.txt	Sat May 16 01:34:03 2009 +0200
@@ -40,9 +40,9 @@
 Awkward cases (extra arguments):
 
   f(1, 2, 3, 4)   # put arguments in frame
-                  # if f is not known, add arguments vs. parameters check
-                  # target unpacks superfluous arguments from the end of the
-                  # frame
+                  # if f is not known, add arguments vs. parameters check;
+                  # to handle superfluous arguments, make a suitable object
+                  # and fill it with all such arguments
 
 Very awkward cases:
 
@@ -179,3 +179,52 @@
                   # gives context c
   fn(1, 2)        # instance context -> no explicit context required
                   # context c inserted in call
+
+Star parameters are a convenience:
+
+  max(1, 2, 3)    # call to max(*args) where args == (1, 2, 3)
+  max((1, 2, 3))  # but why not just do this instead?
+
+  One motivation: avoid explicitly making sequences.
+  Opportunity: avoid expensive dynamic allocation of sequences?
+
+Star parameters, known callables and sequences:
+
+  g(1, 2, 3, 4)   # g known as function g(a, *args) at compile-time
+
+    g   -> don't get any context information
+    1   -> argument #1
+    2   -> reference to sequence containing arguments #2, #3, #4
+
+  (This according to approach #1 described for unknown callables. With approach
+   #2, normal argument positioning would occur.)
+
+Star parameters, unknown callables:
+
+  g(1, 2, 3, 4)   # g not known at compile-time
+
+    g   -> g
+        -> load context for argument #1
+    1   -> argument #2
+    2   -> argument #3
+    3   -> argument #4
+    4   -> argument #5
+
+  Then, check the context and shift the frame if necessary (described above).
+
+  If g has a star parameter - g(a, *args) - then...
+
+  Approach #1 - move arguments #3, #4, #5 (or shifted to #2, #3, #4) into a
+                sequence, adding a reference to the sequence in their place
+
+  Approach #2 - maintain special access rules to arguments #3, #4, #5 (perhaps
+                shifted to #2, #3, #4) as a C-like array
+
+Tradeoffs for star parameter approaches:
+
+  Approach #1 - potentially costly at run-time as arguments need moving around,
+                but the arguments would behave normally in functions
+
+  Approach #2 - need to track usage of the star parameter and to possibly copy
+                its contents if assigned, as well as providing special access
+                mechanisms, but the invocation procedure would be simpler
diff -r 3063e2b7ff63 -r 398f466a7011 micropython/ast.py
--- a/micropython/ast.py	Mon May 11 02:17:12 2009 +0200
+++ b/micropython/ast.py	Sat May 16 01:34:03 2009 +0200
@@ -596,11 +596,6 @@
             extend = ExtendFrame()
             self.new_op(extend)
 
-            # Handle * parameters.
-            # NOTE: Not handling ** parameters yet.
-
-            # Make a tuple from the arguments corresponding to the * parameter.
-
             self.dispatch(node.code)
             if not isinstance(self.last_op(), Return):
                 self.dispatch(compiler.ast.Name("None"))
diff -r 3063e2b7ff63 -r 398f466a7011 micropython/trans.py
--- a/micropython/trans.py	Mon May 11 02:17:12 2009 +0200
+++ b/micropython/trans.py	Sat May 16 01:34:03 2009 +0200
@@ -719,6 +719,9 @@
             if target.has_star or target.has_dstar:
                 frame_size = max(nargs, nargs_max)
 
+                # NOTE: We now need to pack these arguments into a suitable
+                # NOTE: structure for the * parameter.
+
             # For other parameter lists, only accept as many arguments as we are
             # allowed.
 
diff -r 3063e2b7ff63 -r 398f466a7011 rsvp.py
--- a/rsvp.py	Mon May 11 02:17:12 2009 +0200
+++ b/rsvp.py	Sat May 16 01:34:03 2009 +0200
@@ -424,8 +424,6 @@
             self.exception = self.attr_error
             return self.RaiseException()
 
-    # NOTE: LoadAttrIndexContextCond will test context compatibility.
-
     def StoreAttrIndex(self):
         context, ref = self.value
         data = self.load(ref)