Changeset 9958 for docs/Perl6/FAQ

Timestamp:

04/15/06 15:24:04 (3 years ago)

Author:

audreyt

Message:

* Perl6::FAQ::Capture - PODification.

Files:

• docs/Perl6/FAQ/Capture.pod (modified) (14 diffs)

docs/Perl6/FAQ/Capture.pod

@@ -1 @@
-= Q: What happened to references?
-
-A: They have been superseded by Captures.
-
-
-= Q: What is a Capture?
+=head1 NAME
+
+Perl6::FAQ::Capture - Capture objects
+
+=head1 DESCRIPTION
+
+This FAQ answers questions about B<Capture> objects, as well as their uses in
+bindings and function calls.
+
+=head2 What happened to references?
+
+They have been superseded by Capture objects.
+
+=head2 What is a Capture?
 
 A Capture is an object representing arguments in a function call.
 
-For example, the arguments in say("Hello", "World") is a Capture object
-denoted by \("Hello", "World").
-
-
-= Q: Can I see how captures look like? Does \$x no longer work?
-
-Prefix \ is now the Capture constructor.  These are all equivalent:
+For example, the arguments in C<say("Hello", "World")> is a Capture object
+denoted by C<\("Hello", "World")>.
+
+=head2 Can I see how captures look like? Does \$x no longer work?
+
+Prefix C<\> is now the Capture constructor.  These are all equivalent:
 
   my $xcap1 = \$x;
@@ -20 +27 @@
   my $xcap3 = \($x :);
 
-All three represent an argument list with a single invocant $x, and hence are
+All three represent an argument list with a single invocant C<$x>, and hence are
 all equivalent with each other:
 
   $xcap1 === $xcap2 === $xcap3; # true
 
-
-= Q: What about capturing multiple arguments?
+=head2 What about capturing multiple arguments?
 
 Here's how Captures look like deferred argument lists:
@@ -42 +48 @@
   say "It has $car_cap<doors> doors" # 2 doors
 
-
-= Q: How do I extract all positional arguments or all named arguments?
+=head2 How do I extract all positional arguments or all named arguments?
 
 As you can see above, a Capture object holds both positional and named parts.
@@ -52 +57 @@
 
 Both forms flatten under list context, so they may be used interchangeably.
-However, only the postfix .[] form interpolates in a string.
-
-Similarly, access to named arguments is available by treating the Capture as a hash:
+However, only the postfix C<.[]> form interpolates in a string.
+
+Similarly, access to named arguments is available by treating the Capture
+as a hash:
 
   $cap{};  # postfix .{}
@@ -61 +67 @@
 Note that the positional parts do not include the invocant.
 
-= Q: What do you mean by "invocant"?
-
-When you call a object's method, the "self" inside the method is set to that
+=head2 What do you mean by "invocant"?
+
+When you call a object's method, the C<self> inside the method is set to that
 object. These are all equivalent:
 
@@ -83 +89 @@
   $x === $(\$x);
 
-
-= Q: What about multimethod dispatch and cases where there is more than one invocant?
+=head2 What about multimethod dispatch and cases where there is more than one invocant?
 
 There's always one invocant, but it may be an Array of several values (see below).
 
-
-= Q: What happens when a named argument is repeated?
+=head2 What happens when a named argument is repeated?
 
 Let's look at some examples:
@@ -100 +104 @@
 
 A Capture object may hold named arguments that occur twice or more.  When it's
-bound to a variable in the Signature, if the sigil is "@", then it expands to a
-list of all arguments (in the order they were specified).  Otherwise (i.e. if
-it's bound to a scalar or a slurpy hash), the last argument overrides the
-previous ones.
-
-
-= Q: What do *$x, *@x and *%x mean?
-
-The prefix * method casts an object into a Capture object, and merges it
+bound to a variable in the Signature, if the sigil is C<@>, then it expands to a
+list of all arguments (in the order they were specified).
+
+Otherwise (i.e. if it's bound to a scalar or a slurpy hash), the last argument
+overrides the previous ones.
+
+=head2 What do *$x, *@x and *%x mean?
+
+The prefix C<*> method casts an object into a Capture object, and merges it
 into the Capture being currently constructed (e.g. an argument list):
 
@@ -121 +125 @@
     my $p = (x => 42);  f(*$p);     # f(x => 42)
 
-
-= Q: What does $x = \@y mean?
-
-The same as $x = (@y: ). That is, a Capture of one array as invocant. 
+=head2 What does $x = \@y mean?
+
+The same as C<$x = (@y: )>. That is, a Capture of one array as invocant. 
 
 Unlike in Perl 5, this means that you can get back the Array object with:
@@ -139 +142 @@
   
 Note the need for the extra $ sigil, implying we are accessing the captured invocant.
-@$x.push() would mean an attempt to add an extra positional argument into $x; however,
-this is forbidden by the spec, as all parts are immutable in an Capture object.
+C<@$x.push()> would mean an attempt to add an extra positional argument into
+C<$x>; this would fail as all parts are immutable in an Capture object.
 
 (Captures are immutable; their underlying data may not be.)
 
-
-= Q: So $x = @y does not mean $x = \@y anymore. What does it mean then?
-
-Assign $x with the object @y is bound to (typically an Array object).
-
-This does not create Capture objects; to get back @y, @$x would do.
+=head2 So $x = @y does not mean $x = \@y anymore. What does it mean then?
+
+It means assigning C<$x> with the object bound to C<@y> (typically an Array object).
+
+This does not create Capture objects; to get back C<@y>, C<@$x> would do.
 
 Also note that all these forms mean the same thing:
@@ -160 +162 @@
   @y[][][];
 
-= Q: Does this mean I can't have something akin to a refrence to a reference?
+=head2 Does this mean I can't have something akin to a refrence to a reference?
 
 You can, as a Capture can contain another capture object in its invocant slot:
@@ -167 +169 @@
     say $$$x; # same as "say 3"
 
-= Q: Can I create a "pass-through" function that captures all arguments?
-
-Yes, using the \$ signature:
+=head2 Can I create a "pass-through" function that captures all arguments?
+
+Yes, using the C<\$> signature:
 
     sub f (\$args) { g(*$args) }
     f(1, 2, x => 42);   # same as g(1, 2, x => 42)
 
-The $args above becomes a Capture object.
-
-= Q: How is @x = (1, 2, 3) different from @y := (1, 2, 3) ?
-
-The latter is an error. :-)  The := operator binds its left hand side (a Signature object)
-to its right hand side (a Capture object), so the latter form is akin to:
+The C<$args> above becomes a Capture object.
+
+=head2 How is @x = (1, 2, 3) different from @y := (1, 2, 3) ?
+
+The latter is an error. :-)
+
+The C<:=> operator binds its left hand side (a Signature object) to its right
+hand side (a Capture object), so the latter form is akin to:
 
   sub foo (@y is rw) { ... }
@@ -193 +197 @@
 But they are still different from the assignment form.
 
-
-= Q: How is @x = (1, 2, 3) different from *@y := (1, 2, 3), then?
-
-This means that while @y holds the values 1, 2, and 3, you cannot modify the
+=head2 How is @x = (1, 2, 3) different from *@y := (1, 2, 3), then?
+
+This means that while C<@y> holds the values 1, 2, and 3, you cannot modify the
 container itself, so this won't work:
 
@@ -207 +210 @@
   my @x;        # implicitly does the same thing
 
-so @x = (1, 2, 3) would simply populate the previously allocated Array object
+so C<@x = (1, 2, 3)> would simply populate the previously allocated Array object
 with new elements.
 
-
-= Q: Is there any difference between $x = (1, 2, 3) and @y = (1, 2, 3)?
+=head2 Is there any difference between $x = (1, 2, 3) and @y = (1, 2, 3)?
 
 Yes.  The right-hand side in both case is a single List object constructed with
-the list-associative infix:<,> operator, but it is flattened in the second
+the list-associative C<< infix:<,> >> operator, but it is flattened in the second
 case, and its elements are put into the previously allocated Array container
-bound to @y:
+bound to C<@y>:
 
     $x.push(0); # error: cannot find method: List.push
     @y.push(0); # works just fine
 
-
-= Q: Is there any difference between $x = [1, 2, 3] and @y = [1, 2, 3]?
-
-Yes.  As in Perl 5, the Array constructor [...] does not flatten under list
-context, so @y receives a List with one element (an Array object), which then
-becomes @y[0]:
+=head2 Is there any difference between $x = [1, 2, 3] and @y = [1, 2, 3]?
+
+Yes.  As in Perl 5, the Array constructor C<circumfix:[ ]> does not flatten
+under list context, so C<@y> receives a List with one element (an Array
+object), which then becomes C<@y[0]>:
 
     $x.elems; # 3
@@ -237 +238 @@
     @y.push(0);     # works - @y.elems becomes 2 
 
-
-= Q: Is there any difference between $x := [1, 2, 3] and @y := [1, 2, 3]?
+=head2 Is there any difference between $x := [1, 2, 3] and @y := [1, 2, 3]?
 
 For the usual method-based operations, they are pretty much interchangeable: