fileutil::multi::op(n)

📦

version 2.0 · 2 versions

2.0 · fedora 43, fedora 44, nixos 26.05, nixpkgs unstable (latest)
1.21 · alpine 3.24, epel 9, opensuse-leap 16.0

, in fedora 43, fedora 44, nixos 26.05, nixpkgs unstable

💖 fileutil::multi::op — the manual page, but make it make sense 💖

okay bestie, welcome to fileutil::multi::op(n) from the file utilities corner of the world. this is part 1, so don't go anywhere, there's more coming. 🌸

✨ NAME ✨

fileutil::multi::op — multi-file operation, scatter/gather. it's giving "do stuff to a whole bunch of files at once" energy. 🦋

✨ SYNOPSIS ✨

package require Tcl 8.5 9

package require fileutil::multi::op ?0.5.4?

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?

✨ DESCRIPTION ✨

so like, this package hands you objects that can do actions on multiple files that get picked out by glob patterns. no cap. 🎀

at the very core of it there's a whole domain specific language that makes it easy-peasy to specify multi-file copy and/or move and/or deletion operations. alternate names for this whole thing would be scatter/gather processor, or honestly maybe even assembler. it's iconic like that. 👑

✨ CLASS API ✨

the main character command of the package is:

::fileutil::multi::op ?opName? ?word...? — this one creates a brand new multi-file operation object, and it comes with an associated global Tcl command whose name is opName. you use that command to invoke all the various possible file operations. its general form goes like this:

opName option ?arg arg ...?

Option and the args are what determine the exact behavior of the command. periodt.

if you pass the string %AUTO% as the opName, the package will generate a unique name all on its own. self-sufficient queen. 💅

if one or more words are specified, they get interpreted as an initial set of file commands to execute. meaning: the method do of the newly constructed object is implicitly invoked, using the words as its arguments. sneaky but cute. ✨

✨ OBJECT API ✨

here's every method a multi-file operation object can do:

$opName do ?word...? — this method reads the specified words as file commands to execute. head to the FILE API section for the whole list of acceptable commands, their syntax, and their semantics. the result of the method is whatever result the last file command it executed produced. last one wins, slay. 🔥

✨ FILE API ✨

both the object constructor and the method do take a list of words and interpret them as file commands to execute. the names were literally chosen so you can build operations that read like sentences in near-natural language. most of these commands only mess with the state of the object — like, they're just setting up the configuration that the command triggering the actual action is gonna use. setup era. 🧚

into directory — specifies the destination directory for operations.
in directory — alias for into.
to directory — alias for into.
from directory — specifies the source directory for operations.
not pattern — specifies a glob pattern for paths to be excluded from the operation. not today, bestie. 🙈
for pattern — alias for not.
exclude pattern — alias for not.
but — has no arguments of its own, but it looks ahead in the list of words and executes all not commands immediately following it. this lets you build "but not" and "but exclude" clauses so your specification of excluded paths sounds all natural and cute.
except — a semi-alias for but. no arguments of its own, but it looks ahead in the list of words and executes all for commands immediately following it. this lets you build "except for" clauses for a more natural sounding way to say which paths are excluded. 💜
as name — specifies a new name for the first file handled by the current operation. i.e. this is for renaming a single file during the operation. glow-up for one file only. ✨
recursive — signals that file expansion should happen across the whole directory hierarchy, not just the directory itself. go deep. 🌊
recursively — an alias for recursive.
copy — signals that the operation is copying files from source to destination directory, per the inclusion and exclusion patterns you specified.
move — signals that the operation is moving files from source to destination directory, per the specified inclusion and exclusion patterns.
remove — signals that the operation is removing files in the destination directory, per the specified inclusion and exclusion patterns. bye bye 💀
expand — signals that there's no operation at all, just the calculation of the set of files from the include and exclude patterns. heads up: this operation is not available if the-set is used. 🚫
invoke cmdprefix — signals that your user-specified command prefix cmdprefix is the operation to perform. the command prefix is executed at the global level and gets handed the source directory, the destination directory, and the set of files (as a dictionary mapping from source to destination files), in that order. you're in charge now, main character. 👑
reset — forces the object back into the ground state, where every single part of the configuration has default values. factory reset energy.
( — saves a copy of the current object state onto a stack.
) — takes the state at the top of the state stack and restores it, i.e. makes it the new current object state.
cd directory — changes the destination directory to the sub-directory directory of the current destination. 📁
up — changes the destination directory to the parent directory of the current destination. climbing. 🦋
for-windows — checks that Windows is the current platform. aborts processing if it's not.
for-win — an alias for for-windows.
for-unix — checks that Unix is the current platform. aborts processing if it's not.
the pattern — this command specifies the files to operate on via a glob pattern, and it's also the active element — like, the command that actually performs the specified operation. every other command only modifies the object state to set the operation up, but does nothing else. this one does the thing. 💅

to allow for a more natural sounding syntax, this command also looks ahead in the list of words and executes several commands immediately following it before performing its own actions. those commands are as, but, exclude, except, from, and into (and their aliases). that way these commands act like qualifiers, and still take effect as if they had been written before this command. time travel but make it syntax. ⏳

after the operation has been performed, the object state — the exclude patterns and the alias name, if one was specified — are reset to their default values (i.e. empty). but nothing else gets reset. just those.

the-set varname — like the, except the set of files to use isn't specified implicitly via a glob pattern. instead it's contained in and loaded from the specified variable. and heads up: 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. 📥
strict — makes file expansion and the definition of the destination directory (in in and its aliases) strict, i.e. it reports errors for missing directories, and for empty expansion. no chill mode. 😤
!strict — the complement of strict. a missing destination directory or an empty expansion are not reported as errors. chill mode restored. 🌈
files — limits the search to files. default is to accept every type of path.
links — limits the search to symbolic links. default is to accept every type of path.
directories — limits the search to directories. default is to accept every type of path.
dirs — an alias for directories.
all — accepts all types of paths (this is the default).
state? — returns the current state of the object as a dictionary. here are the dictionary keys and what they mean:
- as — last setting made by as.
- excluded — list of currently known exclusion patterns.
- from — current source directory, set by from.
- into — current destination directory, set by into (and its aliases).
- operation — current operation to perform, set by copy, move, remove, expand, or invoke.
- recursive — current recursion status. set/unset by recursive and !recursive.
- strict — current strictness. set/unset by strict and !strict.
- type — current path type limiter. set by either files, directories, links, or all.
as? — returns the current alias name.
excluded? — returns the current set of exclusion patterns.
from? — returns the current source directory.
into? — returns the current destination directory.
operation? — returns the current operation to perform.
recursive? — returns the current recursion status.
strict? — returns the current strictness.
type? — returns the current path type limiter.

✨ EXAMPLES ✨

okay bestie these next bits assume one thing and one thing only: that the variable F is holding a reference to a multi-file operation object. that's it. that's the whole setup. 💅

      $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

lowkey you could also write # Alternatively use 'except for *.html'. if that hits different for you 🫶

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

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

now here's the iconic part: most of these commands literally just tweak the object state, which means we can go full goblin mode and use those more off forms as specifications instead of writing actual nearly-natural language sentences. iykyk. for example, that second example up there? you can rearrange it into this:

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

and not only is the result still a valid specification, it even stays relatively readable?? we love a flexible king. 👑

also also — important — the info collected by the but, except, and as commands gets automatically reset after the associated the was executed. but literally no other state resets that way, which is actually a feature, because it lets you avoid repeating unchanging info over and over like a broken record. 🌸

so for example, the second and third examples in this section can be merged and rewritten into the equivalent of:

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

ate. no crumbs. 🎀

💀 BUGS, IDEAS, FEEDBACK 💀

ngl bestie, this document and the package it describes will undoubtedly contain bugs and other problems. it's giving humble but also real. 😭 please report such things in the category fileutil of the Tcllib Trackers at [http://core.tcl.tk/tcllib/reportlist]. and while you're there, please also drop any ideas for enhancements you may have for either the package and/or the documentation — we want all of it. 🫶

when you're proposing code changes, please provide unified diffs, i.e the output of diff -u. ✨

and note further that attachments are strongly preferred over inlined patches. to attach something, go to the Edit form of the ticket immediately after its creation, and then use the left-most button in the secondary navigation bar. no cap. 💅

🌈 KEYWORDS 🌈

copy
file utilities
move
multi-file
remove

⭐ CATEGORY ⭐

Programming tools

and that's a wrap on the whole page, bestie 🎀 this one came from tcllib, version 0.5.4, and the manpage goes by fileutil::multi::op(n) — go forth and multi-file responsibly, mwah 💖✨

📦 where this page comes from

fedora 43: tcllib 2.0-3.fc43 · TCL
fedora 44: tcllib 2.0-4.fc44 · TCL
nixos 26.05: tcllib 2.0
nixpkgs unstable: tcllib 2.0
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-18: a language model's rewrite of the original, under its terms