quoting.pod

=begin pod

=TITLE Quoting Constructs

=DESCRIPTION Writing strings, word lists, and regexes in Perl 6

=head1 The Q Lang

Strings are usual represented in Perl 6 code using some form of quoting
construct. The most minimalistic of these is C<Q>, usable via the
shortcut C<｢…｣>, or via C<Q> followed by any pair of delimiters
surrounding your text. Most of the time, though, the most you'll need
is C<'…'> or C<"…">, described in more detail in the next sections.

=head2 Literal strings: Q

=for code :allow<B>
B<Q[>A literal stringB<]>
B<｢>More plainly.B<｣>
B<Q ^>Almost any non-word character can be a delimiter!B<^>

Delimiters can nested, but in the plain C<Q> form, backslash escapes
aren't allowed.  In other words, basic C<Q> strings are as literal as
possible.

=for code :allow<B>
Q<Make sure you B«<»matchB«>» opening and closing delimiters>
Q{This is still a closing brace → B<\>}

These examples produce:

    A literal string
    More plainly.
    Almost any non-word character can be a delimiter!
    Make sure you <match> opening and closing delimiters
    This is still a closing brace → \

The other quote forms add on to this basic functionality:

=head2 Escaping: q

=for code :allow<B>
B<'>Very plainB<'>
B<q[>This backB<\s>lash staysB<]>
B<q[>This backB<\\>slash staysB<]> # Identical output
B<q{>This is not a closing brace → B<\}>, but this is → B<}>
B<Q :q $>There're no backslashes here, only lots of B<\$>B<\$>B<\$>!B<$>
B<'>(Just kidding. ThereB<\'>s no money in that string)B<'>
B<'>No $interpolation {here}!B<'>
B<Q:q#>Just a literal "\n" hereB<#>

The C<q> form allows for escaping characters that would otherwise end
the string using a backslash. The backslash itself can be escaped, too,
as in the third example above. The usual form is C<'…'> or C<q> followed
by a delimiter, but it's also available as an adverb on C<Q>, as in the
fifth and last example above.

These examples produce:

    Very plain
    This back\slash stays
    This back\slash stays
    This is not a closing brace → } but this is →
    There's no backslashes here, only lots of $$$!
    (Just kidding. There's no money in that string)
    No $interpolation {here}!
    Just a literal "\n" here

=head2 Interpolation: qq

=for code :allow<B L>
my $color = 'blue';
L<say> B<">My favorite color is B<$color>!B<">

    My favorite color is blue!

The C<qq> form, usually written using double quotes, allows for
interpolation of variables, i.e, they allow you to write variables
within the string, so that the content of the variable gets added to the
string. C<qq> also allows escaping of these variables:

=for code :allow<B>
say B<">The B<\>$color variable contains the value '$color'B<">;

    The $color variable contatins the value 'blue'

Another feature of C<qq> is the ability to interpolate Perl 6 code from
within the string, using curly braces:

=for code :allow<B L>
my ($x, $y, $z) = 4, 3.5, 3;
say "This room is B<$x> m by B<$y> m by B<$z> m."
say "That means its volume should be B<{ $x * $y * $z }> m³!"

    This room is 4 m by 3.5 m by 3 m.
    That means its volume should be 42 m³!

By default, only variables with the C<$> sigil are interpolated
normally. This way, when you write C<"documentation@perl6.org">, you
aren't interpolating the C<@perl6> variable. If that's what you want to
do, append a C<[]> to the variable name:

=for code :allow<B>
my @neighbors = "Felix", "Danielle", "Lucinda";
say "@neighborsB<[]> and I try our best to coexist peacefully."

    Felix Danielle Lucinda and I try our best to coexist peacefully.

Often, though a method call is more appropriate, and these are also
allowed within C<qq> quotes, as long as they have parentheses after the
call. This means that C<"@example.com"> produces C<@example.com>, but
that the following will work:

=for code :allow<B L>
say "@neighborsB<.L<join>(', ')>, and I try our best to coexist peacefully."

    Felix, Danielle, Lucinda, and I try our best to coexist peacefully.

=head2 Word quoting: qw

=for code :allow<B L>
B«<»a b cB«>» L<eqv> ('a', 'b', 'c')
B<qw|>! @ # $ % ^ & * \| < > B<|> eqv '! @ # $ % ^ & | < >'.words
B<Q:w {> [ ] \{ \} B<}> eqv ('[', ']', '{', '}')

The C<:w> form, usually written C«<…>» or C<qw>. It splits up the string into
words (which are, in this context, defined as sequences of non-whitespace
characters separated by whitespace). C<q:w> and C<qw> forms inherit the
interpolation and escape semantics of the C<q> and single quote string
delimiters, C<Qw> and C<Q:w> inherit the non-escaping semantis of the C<Q>
quoter.

This form is used in preference to writing out many quotation marks and
commas for lists of strings. For example, where you could write:

    my @directions = 'left', 'right,', 'up', 'down';

It's easier to write and to read this:

    my @directions = <left right up down>;

=head2 Shell quoting: qqw

TODO

=head2 Heredocs: :to

TODO

=head1 Regexes

TODO -- or just point to regexes.pod?


=end pod