Quote-Like Operators

Quote-Like Operators

• q/STRING/
• 'STRING'

  A single-quoted, literal string. A backslash represents a backslash unless followed by the delimiter or another backslash, in which case the delimiter or backslash is interpolated.

  $foo = q!I said, "You said, 'She said it.'"!;
  $bar = q('This is it.');
  $baz = '\n';		# a two-character string
  

• qq/STRING/
• "STRING"

  A double-quoted, interpolated string.

    $_ .= qq
          (*** The previous line contains the naughty word "$1".\n)
  if /\b(tcl|java|python)\b/i;      # :-)
    $baz = "\n";		# a one-character string
  

• qx/STRING/
• `STRING`

  A string which is (possibly) interpolated and then executed as a system command with /bin/sh or its equivalent. Shell wildcards, pipes, and redirections will be honored. The collected standard output of the command is returned; standard error is unaffected. In scalar context, it comes back as a single (potentially multi-line) string, or undef if the command failed. In list context, returns a list of lines (however you've defined lines with $/ or $INPUT_RECORD_SEPARATOR ), or an empty list if the command failed.

  Because backticks do not affect standard error, use shell file descriptor syntax (assuming the shell supports this) if you care to address this. To capture a command's STDERR and STDOUT together:

  $output = `cmd 2>&1`;
  

  To capture a command's STDOUT but discard its STDERR:

  $output = `cmd 2>/dev/null`;
  

  To capture a command's STDERR but discard its STDOUT (ordering is important here):

  $output = `cmd 2>&1 1>/dev/null`;
  

  To exchange a command's STDOUT and STDERR in order to capture the STDERR but leave its STDOUT to come out the old STDERR:

  $output = `cmd 3>&1 1>&2 2>&3 3>&-`;
  

  To read both a command's STDOUT and its STDERR separately, it's easiest to redirect them separately to files, and then read from those files when the program is done:

  system("program args 1>program.stdout 2>program.stderr");
  

  The STDIN filehandle used by the command is inherited from Perl's STDIN. For example:

  open(SPLAT, "stuff")   || die "can't open stuff: $!";
  open(STDIN, "<&SPLAT") || die "can't dupe SPLAT: $!";
  print STDOUT `sort`;
  

  will print the sorted contents of the file named "stuff".

  Using single-quote as a delimiter protects the command from Perl's double-quote interpolation, passing it on to the shell instead:

  $perl_info  = qx(ps $$);            # that's Perl's $$
  $shell_info = qx'ps $$';            # that's the new shell's $$
  

  How that string gets evaluated is entirely subject to the command interpreter on your system. On most platforms, you will have to protect shell metacharacters if you want them treated literally. This is in practice difficult to do, as it's unclear how to escape which characters. See perlsec for a clean and safe example of a manual fork() and exec() to emulate backticks safely.

  On some platforms (notably DOS-like ones), the shell may not be capable of dealing with multiline commands, so putting newlines in the string may not get you what you want. You may be able to evaluate multiple commands in a single line by separating them with the command separator character, if your shell supports that (for example, ; on many Unix shells and & on the Windows NT cmd shell).

  Perl will attempt to flush all files opened for output before starting the child process, but this may not be supported on some platforms (see perlport). To be safe, you may need to set $| ($AUTOFLUSH in English) or call the autoflush() method of IO::Handle on any open handles.

  Beware that some command shells may place restrictions on the length of the command line. You must ensure your strings don't exceed this limit after any necessary interpolations. See the platform-specific release notes for more details about your particular environment.

  Using this operator can lead to programs that are difficult to port, because the shell commands called vary between systems, and may in fact not be present at all. As one example, the type command under the POSIX shell is very different from the type command under DOS. That doesn't mean you should go out of your way to avoid backticks when they're the right way to get something done. Perl was made to be a glue language, and one of the things it glues together is commands. Just understand what you're getting yourself into.

  See I/O Operators for more discussion.

• qw/STRING/

  Evaluates to a list of the words extracted out of STRING, using embedded whitespace as the word delimiters. It can be understood as being roughly equivalent to:

  split(" ", q/STRING/);
  

  the differences being that it generates a real list at compile time, and in scalar context it returns the last element in the list. So this expression:

  qw(foo bar baz)
  

  is semantically equivalent to the list:

  "foo", "bar", "baz"
  

  Some frequently seen examples:

  use POSIX qw( setlocale localeconv )
  @EXPORT = qw( foo bar baz );
  

  A common mistake is to try to separate the words with commas or to put comments into a multi-line qw-string. For this reason, the use warnings pragma and the -w switch (that is, the $^W variable) produces warnings if the STRING contains the "," or the "#" character.

• tr/SEARCHLIST/REPLACEMENTLIST/cdsr
• y/SEARCHLIST/REPLACEMENTLIST/cdsr

  Transliterates all occurrences of the characters found in the search list with the corresponding character in the replacement list. It returns the number of characters replaced or deleted. If no string is specified via the =~ or !~ operator, the $_ string is transliterated.

  If the /r (non-destructive) option is present, a new copy of the string is made and its characters transliterated, and this copy is returned no matter whether it was modified or not: the original string is always left unchanged. The new copy is always a plain string, even if the input string is an object or a tied variable.

  Unless the /r option is used, the string specified with =~ must be a scalar variable, an array element, a hash element, or an assignment to one of those; in other words, an lvalue.

  A character range may be specified with a hyphen, so tr/A-J/0-9/ does the same replacement as tr/ACEGIBDFHJ/0246813579/. For sed devotees, y is provided as a synonym for tr. If the SEARCHLIST is delimited by bracketing quotes, the REPLACEMENTLIST has its own pair of quotes, which may or may not be bracketing quotes; for example, tr[aeiouy][yuoiea] or tr(+\-*/)/ABCD/.

  Characters may be literals or any of the escape sequences accepted in double-quoted strings. But there is no interpolation, so "$" and "@" are treated as literals. A hyphen at the beginning or end, or preceded by a backslash is considered a literal. Escape sequence details are in the table near the beginning of this section. It is a bug in Perl v5.22 that something like

  tr/\N{U+20}-\N{U+7E}foobar//
  

  does not treat that range as fully Unicode.

  Note that tr does not do regular expression character classes such as \d or \pL . The tr operator is not equivalent to the tr(1) utility. If you want to map strings between lower/upper cases, see lc and uc, and in general consider using the s operator if you need regular expressions. The \U , \u , \L , and \l string-interpolation escapes on the right side of a substitution operator will perform correct case-mappings, but tr[a-z][A-Z] will not (except sometimes on legacy 7-bit data).

  Note also that the whole range idea is rather unportable between character sets--and even within character sets they may cause results you probably didn't expect. A sound principle is to use only ranges that begin from and end at either alphabets of equal case (a-e, A-E), or digits (0-4). Anything else is unsafe. If in doubt, spell out the character sets in full.

  Options:

    c	Complement the SEARCHLIST.
    d	Delete found but unreplaced characters.
    s	Squash duplicate replaced characters.
        r	Return the modified string and leave the original string
  untouched.
  

  If the /c modifier is specified, the SEARCHLIST character set is complemented. If the /d modifier is specified, any characters specified by SEARCHLIST not found in REPLACEMENTLIST are deleted. (Note that this is slightly more flexible than the behavior of some tr programs, which delete anything they find in the SEARCHLIST, period.) If the /s modifier is specified, sequences of characters that were transliterated to the same character are squashed down to a single instance of the character.

  If the /d modifier is used, the REPLACEMENTLIST is always interpreted exactly as specified. Otherwise, if the REPLACEMENTLIST is shorter than the SEARCHLIST, the final character is replicated till it is long enough. If the REPLACEMENTLIST is empty, the SEARCHLIST is replicated. This latter is useful for counting characters in a class or for squashing character sequences in a class.

  Examples:

  $ARGV[1] =~ tr/A-Z/a-z/;	# canonicalize to lower case ASCII
  
  $cnt = tr/*/*/;		# count the stars in $_
  
  $cnt = $sky =~ tr/*/*/;	# count the stars in $sky
  
  $cnt = tr/0-9//;		# count the digits in $_
  
  tr/a-zA-Z//s;		# bookkeeper -> bokeper
  
  ($HOST = $host) =~ tr/a-z/A-Z/;
   $HOST = $host  =~ tr/a-z/A-Z/r;   # same thing
  
  $HOST = $host =~ tr/a-z/A-Z/r    # chained with s///r
                =~ s/:/ -p/r;
  
  tr/a-zA-Z/ /cs;		# change non-alphas to single space
  
  @stripped = map tr/a-zA-Z/ /csr, @original;
  # /r with map
  
  tr [\200-\377]
            [\000-\177];		# wickedly delete 8th bit
  

  If multiple transliterations are given for a character, only the first one is used:

  tr/AAA/XYZ/
  

  will transliterate any A to X.

  Because the transliteration table is built at compile time, neither the SEARCHLIST nor the REPLACEMENTLIST are subjected to double quote interpolation. That means that if you want to use variables, you must use an eval():

  eval "tr/$oldlist/$newlist/";
  die $@ if $@;
  
  eval "tr/$oldlist/$newlist/, 1" or die $@;
  

• <<EOF

  A line-oriented form of quoting is based on the shell "here-document" syntax. Following a << you specify a string to terminate the quoted material, and all lines following the current line down to the terminating string are the value of the item.

  The terminating string may be either an identifier (a word), or some quoted text. An unquoted identifier works like double quotes. There may not be a space between the << and the identifier, unless the identifier is explicitly quoted. (If you put a space it will be treated as a null identifier, which is valid, and matches the first empty line.) The terminating string must appear by itself (unquoted and with no surrounding whitespace) on the terminating line.

  If the terminating string is quoted, the type of quotes used determine the treatment of the text.

  • Double Quotes

    Double quotes indicate that the text will be interpolated using exactly the same rules as normal double quoted strings.

       print <<EOF;
    The price is $Price.
    EOF
    
       print << "EOF"; # same as above
    The price is $Price.
    EOF
    

  • Single Quotes

    Single quotes indicate the text is to be treated literally with no interpolation of its content. This is similar to single quoted strings except that backslashes have no special meaning, with \\ being treated as two backslashes and not one as they would in every other quoting construct.

    Just as in the shell, a backslashed bareword following the << means the same thing as a single-quoted string does:

    $cost = <<'VISTA';  # hasta la ...
       That'll be $10 please, ma'am.
       VISTA
    
    $cost = <<\VISTA;   # Same thing!
       That'll be $10 please, ma'am.
       VISTA
    

    This is the only form of quoting in perl where there is no need to worry about escaping content, something that code generators can and do make good use of.

  • Backticks

    The content of the here doc is treated just as it would be if the string were embedded in backticks. Thus the content is interpolated as though it were double quoted and then executed via the shell, with the results of the execution returned.

       print << `EOC`; # execute command and get results
    echo hi there
    EOC
    

  It is possible to stack multiple here-docs in a row:

     print <<"foo", <<"bar"; # you can stack them
  I said foo.
  foo
  I said bar.
  bar
  
     myfunc(<< "THIS", 23, <<'THAT');
  Here's a line
  or two.
  THIS
  and here's another.
  THAT
  

  Just don't forget that you have to put a semicolon on the end to finish the statement, as Perl doesn't know you're not going to try to do this:

     print <<ABC
  179231
  ABC
     + 20;
  

  If you want to remove the line terminator from your here-docs, use chomp().

  chomp($string = <<'END');
  This is a string.
  END
  

  If you want your here-docs to be indented with the rest of the code, you'll need to remove leading whitespace from each line manually:

  ($quote = <<'FINIS') =~ s/^\s+//gm;
     The Road goes ever on and on,
     down from the door where it began.
  FINIS
  

  If you use a here-doc within a delimited construct, such as in s///eg, the quoted material must still come on the line following the <<FOO marker, which means it may be inside the delimited construct:

  s/this/<<E . 'that'
  the other
  E
   . 'more '/eg;
  

  It works this way as of Perl 5.18. Historically, it was inconsistent, and you would have to write

  s/this/<<E . 'that'
   . 'more '/eg;
  the other
  E
  

  outside of string evals.

  Additionally, quoting rules for the end-of-string identifier are unrelated to Perl's quoting rules. q(), qq(), and the like are not supported in place of '' and "" , and the only interpolation is for backslashing the quoting character:

  print << "abc\"def";
  testing...
  abc"def
  

  Finally, quoted strings cannot span multiple lines. The general rule is that the identifier must be a string literal. Stick with that, and you should be safe.