# HG changeset patch
# User Paul Boddie <paul@boddie.org.uk>
# Date 1208730918 -7200
# Node ID 5a13e435dd0ed25c5b148b7d96a10d347a65a721
# Parent  29af5aa16abf2f6d58d053924e28687fcc444527
Added invocation summary.

diff -r 29af5aa16abf -r 5a13e435dd0e docs/invocation.txt
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/invocation.txt	Mon Apr 21 00:35:18 2008 +0200
@@ -0,0 +1,48 @@
+Invocations in classic Python:
+
+  f(1, 2, 3)      # positional
+  f(1, 2)         # positional with defaults
+  f(1, 2, c=3)    # keywords
+  f(1, c=3)       # keywords with defaults
+  f(1, 2, 3, 4)   # extra positional arguments
+  f(1, 2, 3, d=4) # extra keyword arguments
+  f(1, 2, *args)  # positional bundles (possibly with defaults)
+  f(1, 2, **kw)   # keyword bundles (possibly with defaults)
+
+  Note that f is never fixed before run-time in Python.
+
+Comparison to C:
+
+  f(1, 2, 3)      # positional, f known at compile-time
+  f(1, 2, 3)      # positional, f is appropriate function pointer
+                  # ie. (*f)(A, B, C)
+
+Least expensive cases:
+
+  f(1, 2, 3)      # put arguments on stack
+                  # if f is not known, add arguments vs. parameters check
+  f(1, 2)         # to handle defaults, introduce default "filling" where
+                  # not enough arguments are given
+                  # if f is not known, this is obviously done at run-time
+
+More expensive cases:
+
+  f(1, 2, c=3)    # prepare stack using parameter details
+                  # (provided c is a known parameter)
+                  # if f is not known, this is obviously done at run-time
+  f(1, c=3)       # as with the previous case, with default "filling" done
+                  # where not enough arguments are given
+                  # if f is not known, this is obviously done at run-time
+                  # but with all defaults copied in before keywords are
+                  # assigned (since their positions and thus the positions
+                  # of missing parameters cannot be known)
+
+Awkward cases:
+
+  f(1, 2, 3, 4)   # extra positional arguments
+  f(1, 2, 3, d=4) # extra keyword arguments
+  f(1, 2, *args)  # positional bundles (possibly with defaults)
+  f(1, 2, **kw)   # keyword bundles (possibly with defaults)
+
+  These cases require additional structures to be created, potentially at
+  run-time.