## XXCOPY TECHNICAL BULLETIN #051

From:    Kan Yabumoto           tech@xxcopy.com
To:      XXCOPY users
Subject: XXCOPY's enhanced inclusion feature in a nutshell
Date:    2014-11-01
===============================================================================

With v.3.50.0, XXCOPY's inclusion feature started to support the Wild-Wildcard
scheme where wildcard characters (* and ?) can be placed anywhere in the
include-item for any number of times.

(/IN:<include-item>) without delving into details which can wait for another
article (XXTB#52).

======================================================================
In addition to the filename-matching pattern supported in the past
(now called U-Class), two more classes of include-item are supported.

U-Class (Über Class):  matches the filename component only.
D-Class (Directory):   matches directory path.
F-Class (File):        matches path and filename.

Note that the source specifier in the command line can be thought
of as a special case of D-Class or F-Class include-item.
======================================================================

Let us study a realistic case of the enhanced include feature:

The example below is illustrated using XXCOPY'S command file (/CF)
switch that allows for in-line comments.

xxcopy /cf:myjob1.xcf // the command line

myjob1.xcf            // the contents of this file shown below
------------------------------------------------------------------
\src\*.txt           // src specifier (\src\ is the Src Base Dir)
\dst\                // dst specifier (\dst\ is the Dst Base Dir)
/in:*.doc                 // U-Class include-item
/in:*.xml                 // U-Class include-item
/in:\src\abc\             // D-Class include-item
/in:\src\def\ghi?\        // D-Class include-item
/in:\src\jkl\*.jpg        // F-Class include-item
------------------------------------------------------------------

In this operation, the following directories are Terminal Directories
where component files are searched for matches with filename patterns.
(See Footnote for its definition).

\src\             // from the src specifier
\src\abc\
\src\def\ghi1\
\src\def\ghi2\
\src\def\ghi3\    // there may be more that match the pattern "ghi?"
\src\jkl\

Furthermore, there are two U-Class include-items:

*.doc
*.xml

U-Class include-items are to be applied "Universally" to all Terminal
Directories; hence its alternate name, Über Class.

On the other hand, the filename-matching component in the source
specifier (*.txt) is not a U-Class item.  Neither is the filename-
matching component in the F-Class include-item (*.jpg).  These
non-U-Class filename-matching patterns are applied only within the
context where they appear.

Some details in the include feature:

(Listed approximately by the order of their relative importance)

1.  U-Class include-items are applied to all of the Terminal Directories.
Therefore, the two U-Class items (*.doc and *.xml) in the example will
be searched for from all the Terminal Directories.

2.  The filename matching pattern that appears in the source specifier
(*.txt) will be applied only in the \src\ directory.  Similarly,
the filename matching pattern (*.jpg) that appears in the F-Class
include-item will be applied only in the \src\jkl\ directory.

3.  If no U-Class include-items were present in the command (that is, if
the /in:*.doc and /in:*.xml switches were not present in the example),
then, all the files in the directories that match the D-Class include-
items (\src\abc\ and \src\def\ghi?\) would be selected for action.

4.  If one or more D-Class or F-Class include-items are present, the source
specifier that ends with a backslash without a Base Directory Marker
(see XXTB#48) will be treated as a Non-Terminal Directory.  That is,
the source specifier in such a case is present solely in order to furnish
what is the Source Base Directory in the current operation.

5.  If no D-Class nor F-Class include-items are present, the source
specifier that ends with a backslash is a Terminal Directory where
the files therein will be matched against the U-Class include-items.
Furthermore, if no U-class include-items are present, then all files
in the source directory will be selected in action.

This rule preserves the backward-compatibility; before XXCOPY started
to support the D-Class and F-Class include-items, the source specifier
that ends with a backslash implicitly selected all the files present
in the source directory.  And, XXCOPY still exhibits this behavior.

(More on this rule in XXTB#52)

6.  Any include-item that resides outside of the Source Base Directory

7.  The /EIN switch provides a variation in the inclusion mechanism which
provides the path of a text file that contains a list of include-items.
The relationship between /IN and /EIN is parallel to that of /X and /EX.
(XXTB#37).

8.  The long awaited support for a list of file paths is implemented by
the use of /EIN switch that accepts the path of a list file.  You may
use the /EIN switch more than once.  Unlike its competing products,
XXCOPY allows wildcard characters in the filename paths inside the
list file.

* * * * *

Wild-Wildcard compliant complex directory and file matching patterns.
In the past, the distinction of the three classes of exclude-items
were not articulated in the documentation.  However, the descriptions
of the three classes of include-items (U-Class, D-Class, and F-Class)
apply to the exclude-items with the exception discussed in Section 10
below.

10.  A U-Class exclude-item (file-matching exclude-item) applies to
the files in Terminal Directories (which are entered as include-items,
not as the exclude-items).

11.  When the source specifier contains a filename-matching pattern
(as opposed to being a directory-matching pattern --- which always
ends with a backlash characer)

13.  The include-item may be in the form of relative path (that does not
starts at the root of a volume).  In such a case, it will be interpreted
as relative to the Source Base Directory.  The same rule applies to
the case for exclude-items.

You may specify an include-item (also an exclude-item) that contains
components that lie outside the scope of the Source Base Directory
which will not, of course, partake in the operation.

E.g.,  xxcopy c:\abc\def\ \dst\  /in:c:\*\def\*.txt

(We expect more rules will be appended here .)

[ Footnote ]  ----------------------------------------------------------------

Terminal Directory:

A Terminal Directory is a directory that is the longest directory path
that matches the source specifier or any of include-items (of D-Class or
F-Class).  Files in a Terminal Directory will be searched for matching
name in the U-Class include-items (and U-Class exclude-items).

------------------------------------------------------------------
This idea is quite natural in XXCOPY.  For example:

xxcopy c:\abc\def\ghi\jkl\mno\   \dst\

In this case, the files in the directory with the full path
(c:\abc\def\ghi\jkl\mno\) is the only directory (Terminal
Directory) whose contents will be copied to the destination.
Any of the directories with a shorter path (e.g., c:\abc\def\)
is a Non-terminal Directory that will not be involved in the
file-copy operation.
------------------------------------------------------------------

For a given D-Class or F-Class include-item, there exists one or more
Terminal Directory.  It is always the longest directory path within
a branch of the directory tree (by the virtue of a wildcard character
within the path-specifier component).  Here are a few examples:

Include-item            Terminal Directory (could be 2 or more)
----------------------------------------------------------------------
c:\abc\def\ghi\*.doc    c:\abc\def\ghi\
\jkl\mn?\               \jkl\mn1\, \jkl\mn2\,...
\pqr\*\stu\*.txt        \pqr\stu\, \pqr\dir1\stu\, \pqr\dir2\stu\,...
----------------------------------------------------------------------

The first example above shows a simple case where the include-item
has no wildcard characters within the directory-path component (hence
no branches).  The second and third examples show the cases with
branches where one (longest) path within each branch becomes the
Terminal Directory.