Output File Specifications

An output file specification gives the name of one or more output files. It can either be a filename like myfile.txt, or a wildcard expression like ***/*.bak, where the names of the input files will determine how the wildcards will be resolved.

In the cop and rena commands, the output file specification is the second parameter.

Example

> cop myfile.txt outfile.txt

In other commands, such as filter, the output file specification is given with the -output option (which can be abbreviated to -o).

Example

> filter -trim myfile.txt -output=outfile.txt

The defaults for the output specification vary between commands.

Syntax

The simplest output file specification is when you just give a filename, without any wildcards.

Example

> cop source.dat target.xyz

The output file specification is target.xyz, and a file with that name will be created in the current working directory.

Wildcards

We can also use the "*" wildcard for either the name or the extension (or both) in the output file specification. The "*" means "same name or extension as the input file" in this context. The single asterisk, with no other characters, is the only wildcard permitted for either the short name or the extension in an output file specification.

Filenames containing wildcards must be placed within quotes under Linux.

Default name and extension

The default output file specification in the cop and rena commands is "*.*", so the wildcards for short name and extension can often be omitted in output file specifications.

Examples (Windows)

Examples (Linux)

Specifying an empty extension

The cop and rena programs both apply ".*" as the default extension, so if we write

> rena alice.txt bob

the name of the file will become bob.txt and nothing else.

If we really want to get rid of the extension we must specify the empty extension explicitly. The command

> rena alice.txt bob.

(with a dot at the end of the output filename) will the rename the file to bob. on a Windows system, and just bob (without any dot) on Linux. There is no way to specify that the output filename should actually end with a single dot on a Linux system.

To specify an empty short name, in order to get a filename that starts with a dot, you must use the -nodefault option described below.

Multiple Output Files

Example

If we have the files a.dat, b.dat, and c.dat in the current working directory, the command

> cop '*.dat' '*.xyz'

will create the files a.xyz, b.xyz, and c.xyz.

We can omit the * wildcard in the output specification and just write .xyz, but the wildcard in the input file specification *.dat is required, as there are no defaults for the input file specification in the cop command.

Example

To copy all files that have the extension .hpp or .cpp from another directory, we can write

> cop '/somewhere/else/*.[hc]pp' .

Each of the created files will keep its original short name and extension when they are copied to the current working directory.

Even though the default output specification is *.* (which is what we want), we must still type something as the output file specification, or the cop command will generate a "required parameter missing" error message. A single dot signifying the current working directory is the shortest output specification we can use.

Directory

The default for cop is to put all the output files in the current working directory. The default for rena is to leave the files in their original directories, and just rename them.

These defaults can be overridden by specifying a directory as part of the output file specification.

Writing to a single output directory

Example (Windows)

> cop myfile.* old\

Copies all files with the short name myfile to the subdirectory old\. The subdirectory must already exist.

When you specify an output directory, the trailing "\" backslash is required. If you leave it out, the program cannot know if you really meant old\ (put them in the subdirectory), or old.* (copy them to this directory with the name old and their original extensions). If old exists as a subdirectory and you specify just old as the output specification, you'll get an error message.

If the name does not exist as a subdirectory, an output specification that neither has an extension nor a trailing slash will be interpreted as a short name.

Example (Windows)

> cop myfile.* newname

Works as long as newname is not the name of an existing directory. Same meaning as newname.* would have.

Writing to multiple output directories

Example (Windows)

> cop somedir\***\*.*.* newdir\***

This will copy all files from somedir\ to newdir\, all from somedir\x\ to newdir\x\ etc.

When the *** wildcard is used in the output file specification, the output directories will be created as needed, and do not have to exist beforehand. This includes the top directory, newdir in the example.

If we had omitted the *** wildcard in the output specification, and just left it in the input file specification, the entire directory tree would have been collapsed into the single directory newdir (provided that that directory already existed). This would normally not be what we wanted, although there are a few times when it is useful to be able to collect files that are spread over a directory tree into a single directory.

*** is the only wildcard that is allowed in the directory part of the output file specification, and it may only appear once. To describe it formally, it's semantics are "all the subdirectories after the first wildcard in the input file specification". This rule applies even if the directory part of the input file specification contained more complex wildcards.

Example (Windows)

> cop somedir\***\doc\***\*.*.* newdir\***

This will copy the contents of all subdirectories called doc to appropriate subdirectories under newdir.

The files in somedir\doc\ will be copied to newdir\doc\, those in somedir\doc\subdir\ to newdir\doc\subdir\, and those in somedir\x\doc\ to newdir\x\doc\, etc.

Version Number

See File Version Numbers: Output Files for a description of how the version numbers work.

Default version number handling

Normally, there is no need to specify any version number in the output file specification, and it's recommended that you leave it out. If you do, the program will automatically assign version numbers as appropriate to the output file(s).

This works properly if there are multiple versions of the input files as well.

Example

> cop 'dir1/*.*.*' 'dir2/*'

The command will copy all versions of all files in the input directory, and give them version numbers so that they appear in the proper order in the new directory. Programs such as cop always start from the back of the list of input files, so that if the input file specification contained multiple versions of the same file, the oldest input files will be copied first. This makes them the oldest in the target directory as well.

(Note to former VAX/VMS users: by doing it this way we avoid the problems that VMS had with the semantics for backup/new_version, which would happily turn every directory upside down if you did not pay close attention to it at all times.)

Explicit version number

The tildes will be added automatically in they are omitted, so we can (and normally would) write just ".3" instead of ".~3~".

Negative version numbers are not permitted in output file specifications, and are treated as a syntax error.

Version number wildcard

When you copy multiple file versions in the recommended way, with a command like

> cop 'dir1/*.*.*' 'dir2/*'

If the output directory did not contain any files with the same name before the copy or rename operation, the oldest version of each file will get number 1, the second oldest number 2 etc. If there were already files with conflicting names in the directory, the version numbers will be set so that the newly copied file(s) appear at the top. In this way, any filename conflicts are resolved, and the files can always be copied.

If you need the copied files to have the same version numbers that they did in the input directory, you give an output specification that contains the version number wildcard ".*".

Example

> cop 'dir1/*.*.*' 'dir2/*.*.*'

-nodefault

Example

> cop emacs.ini .emacs -nodefault

Example

> filter -trim emacs.ini -output=.emacs -nodefault

Options

The cop and rena commands both have *.* as the default output name and extension. This is normally what we want, and allows us to write

> cop alice.txt .bak

to create the output file alice.bak.

This presents a problem, however, if we actually want the short name to be empty.

Suppose that we have a file called emacs.ini, and we want to copy it to a file called .emacs . If we just write

> cop emacs.ini .emacs

the name of the output file will be emacs.emacs, since the output file specification with the default added will be *.emacs . This is not what we wanted in this case.

To prevent the *.* default from being added to the output file specification we use the option -nodefault. The command

> cop emacs.ini .emacs -nodefault

will produce the desired result and create a file called .emacs .

When we specify the -nodefault option on the command line like this, it also suppresses any defaults for the input file specification, as well as for the output file specification. Normally this does not change anything, since no defaults are added to the input file specifications of cop and rena anyway.