# syntax for indicating a filename
# Copyright (C) 2014 Rocky Bernstein <rocky@cpan.org>

=begin comment

The intent of this file is to live in both in the github wiki and as
part of on-line help documentation
lib/Devel/Trepan/CmdProcess/Command/Help/...

=end comment

=head1 Filename Syntax

There are two ways you can give a file name:

=over

=item * unadorned (without double-quotes) with possible escapes

=item * a double-quoted string with possible escapes in the string

=back

Probably most of the time a file name will be specified in the first
form, without using quotes. If the file name however has a space or a
colon in it, escape that character with a backslash. Also, if you need
to enter a backslash and the character following that is unlucky
enough to be a colon, space, or backslash use two backslashes. Some
examples:

   gcd.pl       => gcd.pl
   /tmp/gcd.pl  =>  /tmp/gcd.pl
   C\:gcd.pl    =>  C:gcd.pl
   C\:\gcd.pl   =>  C:\gcd.pl
   C\:\\gcd.pl  =>  C:\gcd.pl  # Note: double slash not needed
   \\new.pl     =>  \new.pl     # Note: double slash, or filename has newline
   my\ file.pl  =>  my file.pl


The quoted string is useful if you have a file name that contains
several characters that normally confuse the debugger parser, notably
a space, newline, or a colon. The quoted string starts with a double
quote ("). Escape sequences are allowed inside the string to be able
to enter tabs or newlines, or a double quote inside the string. The
list of translations is as follows:

   \t => <tab>
   \n => <newline>
   \" => "
   \\ => \

Here are some examples of quoted filenames:

  "This is a file with blanks.pm" => This is a file with blanks.pm
  "/tmp/PerlProgram\"foo\".pm    => /tmp/PerlProgram"foo".pm
  "/Perl\nProgram.pl"             => /tmp/Perl
                                     Program.pl