XXCOPY
[ Back to Table of Contents ] [ << ] [ >> ]

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.

This article provides an overall picture of the enhanced inclusion feature
(/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
      will be discarded.


  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.


                                 * * * * *

            You may stop here at your first reading, and come back
            to this page to finish with the remaining details later.


  9.  XXCOPY also supports exclusion feature that had already supported the
      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.


©2015 Copyright Pixelab All rights reserved.

[ XXCOPY Home ] [ Table of Contents ] [ << ] [ >> ]

Join the XXCOPY group