1. Manuals
  2. Tumbleweed
  3. tcllib
  4. multiop(n)

Scroll to navigation

fileutil::multi::op(n) file utilities fileutil::multi::op(n) 





NAME


fileutil::multi::op - Multi-file operation, scatter/gather






SYNOPSIS


package require Tcl 8.4


package require fileutil::multi::op ?0.5.3?


package require wip ?1.0?


::fileutil::multi::op ?opName? ?word...?


opName option ?arg arg ...?


$opName do ?word...?


into directory


in directory


to directory


from directory


not pattern


for pattern


exclude pattern


but


except


as name


recursive


recursively


copy


move


remove


expand


invoke cmdprefix


reset


(


)


cd directory


up


for-windows


for-win


for-unix


the pattern


the-set varname


-> varname


strict


!strict


files


links


directories


dirs


all


state?


as?


excluded?


from?


into?


operation?


recursive?


strict?


type?










DESCRIPTION


This package provides objects which are able to perform actions on
    multiple files selected by glob patterns.


At the core is a domain specific language allowing the easy
    specification of multi-file copy and/or move and/or deletion operations.
    Alternate names would be scatter/gather processor, or maybe even
  assembler.






CLASS API


The main command of the package is:



  
::fileutil::multi::op ?opName? ?word...?

  
The command creates a new multi-file operation object with an associated
      global Tcl command whose name is opName. This command can be used
      to invoke the various possible file operations. It has the following
      general form:







  

  
Option and the args determine the exact behavior of the
      command.






If the string %AUTO% is used as the opName then the
    package will generate a unique name on its own.


If one or more words are specified they are interpreted as
    an initial set of file commands to execute. I.e. the method do of the
    newly constructed object is implicitly invoked using the words as its
    arguments.






OBJECT API


The following methods are possible for multi-file operation
    objects:



  
$opName do ?word...?

  
This method interprets the specified words as file commands to execute.
      See the section FILE API for the set of acceptable commands, their
      syntax, and semantics.
    
The result of the method is the result generated by the last
        file command it executed.

  








FILE API


Both object constructor and method do take a list of words
    and interpret them as file commands to execute. The names were chosen to
    allow the construction of operations as sentences in near-natural language.
    Most of the commands influence just the state of the object, i.e. are simply
    providing the configuration used by the command triggering the actual
    action.



  

  
Specifies the destination directory for operations.

  

  
Alias for into.

  

  
Alias for into.

  

  
Specifies the source directory for operations.

  

  
Specifies a glob pattern for paths to be excluded from the operation.

  

  
Alias for not.

  

  
Alias for not.

  

  
Has no arguments of its own, but looks ahead in the list of words and
      executes all not commands immediately following it. This allows the
      construction of "but not" and "but exclude" clauses
      for a more natural sounding specification of excluded paths.

  

  
A semi-alias for but. Has no arguments of its own, but looks ahead
      in the list of words and executes all for commands immediately
      following it. This allows the construction of "except for"
      clauses for a more natural sounding specification of excluded paths.

  

  
Specifies a new name for the first file handled by the current operation.
      I.e. for the renaming of a single file during the operation.

  

  
Signals that file expansion should happen in the whole directory hierarchy
      and not just the directory itself.

  

  
An alias for recursive.

  

  
Signals that the operation is the copying of files from source to
      destination directory per the specified inclusion and exclusion
    patterns.

  

  
Signals that the operation is the moving of files from source to
      destination directory per the specified inclusion and exclusion
    patterns.

  

  
Signals that the operation is the removal of files in the destination
      directory per the specified inclusion and exclusion patterns.

  

  
Signals that there is no operation but the calculation of the set of files
      from the include and exclude patterns. This operation is not available if
      the-set is used.

  

  
Signals that the user-specified command prefix cmdprefix is the
      operation to perform. The command prefix is executed at the global level
      and given the source directory, destination directory, and set of files
      (as dictionary mapping from source to destination files), in this
    order.

  

  
Forces the object into the ground state where all parts of the
      configuration have default values.

  
(

  
Saves a copy of the current object state on a stack.

  
)

  
Takes the state at the top of the state stack and restores it, i.e. makes
      it the new current object state.

  

  
Changes the destination directory to the sub-directory directory of
      the current destination.

  

  
Changes the destination directory to the parent directory of the current
      destination.

  

  
Checks that Windows is the current platform. Aborts processing if
    not.

  

  
An alias for for-windows.

  

  
Checks that Unix is the current platform. Aborts processing if not.

  

  
This command specifies the files to operate on per a glob pattern, and is
      also the active element, i.e. the command which actually performs the
      specified operation. All the other commands only modified the object state
      to set the operation up, but di nothing else.
    
To allow for a more natural sounding syntax this command also
        looks ahead in the list of words looks and executes several commands
        immediately following it before performing its own actions. These
        commands are as, but, exclude, except,
        from, and into (and aliases). That way these commands act
        like qualifiers, and still take effect as if they had been written
        before this command.

    
After the operation has been performed the object state the
        exclude patterns and the alias name, if specified, are reset to their
        default values (i.e. empty), but nothing else.

  

  

  
Like the, however the set of files to use is not specified
      implicitly per a glob pattern, but contained and loaded from the specified
      variable. The operation expand is not available if this command is
      used.

  
-> varname

  
Saves the set of files from the last expansion into the specified
      variable.

  

  
Make file expansion and definition of destination directory (in and
      aliases) strict, i.e. report errors for missing directories, and empty
      expansion.

  
!strict

  
Complement of strict. A missing destination directory or empty
      expansion are not reported as errors.

  

  
Limit the search to files. Default is to accept every type of path.

  
  
Limit the search to symbolic links. Default is to accept every type of
      path.

  

  
Limit the search to directories. Default is to accept every type of
    path.

  

  
An alias for directories.

  

  
Accept all types of paths (default).

  

  
Returns the current state of the object as dictionary. The dictionary keys
      and their meanings are:







  

  
Last setting made by as.

  

  
List of currently known exclusion patterns.

  

  
Current source directory, set by from.

  

  
Current destination directory, set by into (and aliases).

  

  
Current operation to perform, set by copy, move,
      remove, expand, or invoke.

  

  
Current recursion status. Set/unset by recursive and
      !recursive.

  

  
Current strictness. Set/unset by strict and !strict.

  

  
Current path type limiter. Set by either files, directories,
      links, or all.







  

  
Returns the current alias name.

  

  
Returns the current set of exclusion patterns.

  

  
Returns the current source directory.

  

  
Returns the current destination directory.

  

  
Returns the current operation to perform.

  

  
Returns the current recursion status.

  

  
Returns the current strictness.

  

  
Returns the current path type limiter.








EXAMPLES


The following examples assume that the variable F contains
    a reference to a multi-file operation object.






    $F do copy                       \
	the  *.dll                    \
	from c:/TDK/PrivateOpenSSL/bin \
	to   [installdir_of tls]









    $F do move      \
	the  *       \
	from /sources \
	into /scratch  \
	but not *.html


    # Alternatively use 'except for *.html'.









    $F do           \
	move         \
	the  index    \
	from /sources  \
	into /scratch   \
	as   pkgIndex.tcl









    $F do         \
	remove     \
	the *.txt  \
	in /scratch




Note that the fact that most commands just modify the object state allows us to
  use more off forms as specifications instead of just nearly-natural language
  sentences. For example the second example in this section can re-arranged
  into:





    $F do            \
	from /sources \
	into /scratch  \
	but not *.html \
	move           \
	the  *




and the result is not only still a valid specification, but even stays
  relatively readable.

Further note that the information collected by the commands
    but, except, and as is automatically reset after the
    associated the was executed. However no other state is reset in that
    manner, allowing the user to avoid repetitions of unchanging information.
    For example the second and third examples of this section can be merged and
    rewritten into the equivalent:




$F do                   \


    move                 \


    the  *                \


    from /sources          \


    into /scratch           \


    but not *.html not index \


    the  index               \


    as   pkgIndex.tcl









BUGS, IDEAS, FEEDBACK


This document, and the package it describes, will undoubtedly
    contain bugs and other problems. Please report such in the category
    fileutil of the Tcllib Trackers
    [http://core.tcl.tk/tcllib/reportlist]. Please also report any ideas for
    enhancements you may have for either package and/or documentation.


When proposing code changes, please provide unified diffs,
    i.e the output of diff -u.


Note further that attachments are strongly preferred over
    inlined patches. Attachments can be made by going to the Edit form of
    the ticket immediately after its creation, and then using the left-most
    button in the secondary navigation bar.






KEYWORDS


copy, file utilities, move, multi-file, remove






CATEGORY


Programming tools







  

    0.5.3
    tcllib