Content-type: text/html Manpage of bydate

bydate

Section: User Commands (1)
Updated: 21 August, 2007
Index Return to Main Contents

NAME

bydate - rename a file to include the current date in the filename

SYNOPSIS

bydate [-dp=pattern -t -z[=path]] file ...

DESCRIPTION

bydate is an aid to building an archive of periodically created files by changing the filename to include the current date. By default the entire filename apart from the extension, if any, is replaced by the current date formatted as ccyymmdd so the name can be sorted. There is an option to provide a pattern that specifies how the new filename(s) are to be constructed from elements of the current date and time, constant strings and parts of the original file name. It also allows the file extension to be replaced.

The program first validates the pattern's elements to ensure they are syntactically correct, stopping with diagnostic message(s) if errors are discovered. If no pattern errors are found the file list is processed, renaming each file in turn. A file will be skipped and diagnostics output if any errors are found while generating its new filename or if a file with that name already exists. This means that no files can be accidentally destroyed. If any files were skipped, bydate exits with an error after the list has been processed.

OPTIONS

-?: display summary help for bydate
-d: display debugging output. This option may appear more than once, each appearance causing debugging output to be more verbose.
-p=pattern: specify the pattern to be used to construct the new name for each file in the list. See below under PATTERN for details.
-t: Run in testing mode. This fixes the time to 04 June 2009 at 10:15:30 so that regression testing compares files renamed by bydate against known file names.
-z=path: read the list of arguments to be processed from path. If =path is absent the arguments will be read from standard input.

PATTERN

The new filename pattern is defined with the -p=pattern option where pattern is a list of pattern elements which specify the format of the new name to be given to the file. Unless explicitly stated otherwise, each element only operates on the part of the filename to the left of the first '.' in the name. The file extension is copied unchanged unless the e element is specified.

If the filename is an absolute or relative pathname the list of directories etc. up to and including the rightmost path separator are used unchanged and are not referenced by any pattern elements. The effect of this is that the renamed file will remain in the same directory.

Elements that select parts of the filename operate on the part of the name to the left of the first '.' in the name: everything to the right of that is considered to form the file extension. These elements are parsed when the pattern is being prepared for use and their arguments are checked for presence and validity but are not compared with the list of files at this stage. As each file in the list is handled the arguments are checked against the filename. If any element can't be completely filled because a part of it is outside the file name an error will be reported and the file will be skipped. This is intended to prevent unrecognisable filenames being generated and applied.

The elements are applied left to right, with each element specifying a part of the filename, until the pattern is exhausted. The resulting string has the extension, if any, appended to it to form the new file name. Elements may reference parts of the current date, fixed strings of characters, or parts of the original filename. The elements are:

c: this element is replaced by two digits representing the current century, e.g. 20
y: this element is replaced by two digits representing the current year, e.g. 07
m: this element is replaced by two digits representing the current month.
d: this element is replaced by two digits representing the current day of the month.
H: this element is replaced by two digits representing the current hour.
M: this element is replaced by two digits representing the current minute.
S: this element is replaced by two digits representing the current second.
pn: this element is replaced by the first n characters of the original file name where n can have any value from 0 to 255. If it is absent or set to zero the whole original filename is included. If it is non-zero then an error will reported if the original filename is not long enough to provide all the required characters.
sn: this element is replaced by the last n characters of the original file name where n can have any value from 1 to 255. An error will reported if the original filename is not long enough to provide all the required characters.
f(n,m): this element is replaced by m characters from the original file name starting at the nth character. Characters are numbered from 1: f(1,2) is equivalent to p2. An error will reported if the original filename is not long enough to provide all the required characters.
t(str): this element is replaced by str where str can be any set of characters that can legitimately be used to form a filename apart from ( and ).
e(str): if used, this must be the last element in the pattern. It causes the file extension to be replaced by str where str can be any set of characters that can legitimately be used to form a filename apart from ( and ). This is the only element that can reference or change the file extension.

If you are having problems with a pattern definition try running bydate with a single -d option, which will show how the pattern is prepared for use and, if the pattern has been accepted, it will show each file as it is processed. The original and new names are shown for each file together with the error, if any, that caused it to be skipped.

EXAMPLES

-p=cymd: This pattern is equivalent to the default pattern.
-p=pe(html): This pattern just replaces the extension, so if the file list is *.eml the files will all have their extensions changed from .eml to .html but note that the pattern -p=e(html) will attempt to rename all the files to .html because the pattern doesn't contain any elements that create the part of the name to the left of the '.'. If the intention was to change the extension while providing the default left part of the name it can be achieved with the -p=cymde(html) pattern.
-p=p1t(_)ymd: If the input file is called forecast.gif and the date is 14th August, 2007 it will be renamed to f_070814.gif
-p=pcymd: If the input file is called forecast.gif and the date is 14th August, 2007 it will be renamed to forecast20070814.gif
-p=ymdt(-)HMS: If the input file is called visual.gif and the date is 14th August, 2007 at 15:30:10 it will be renamed to 070814-153010.gif
-p=t(e-mail_)cymde(html): If the input file is called saved_email.eml and the date is 14th August, 2007 it will be renamed to e-mail_20070814.html
-p=t(e-mail_)pt(-)cymde(html): If the input file is called saved_mail/mcg.eml and the date is 14th August, 2007 it will be renamed to saved_mail/e-mail_mcg-20070814.html
-p=cymdt(:)f(12,2)t(-forecast): If the input file is called prediction-12pm.jpg and the date is 14th August, 2007 it will be renamed to 20070814:12-forecast.jpg

BUGS

If bydate is compiled under Windows 95, 98 or ME the compiler that's used will determine whether a file can be renamed to have a long, mixed case name or just FAT-16 style 8:3 name. If the compiler imposes this limitation the new filename will built to the full length and then be truncated to a maximum of 8 characters before the '.'. Following this, the file is then renamed. This behaviour will occur if the Borland C version 4.5 compiler is used. Current versions of the DJGPP port of the GNU gcc compiler will generate code that handles long, mixed case names.

If a Borland compiler is used the wildcards option should be used or the program will not handle wildcarded filenames correctly.

This version of bydate cannot be used to modify "hidden files", i.e. those starting with a '.'. This is a consequence of it using a somewhat simplistic way of recognising the file extension. It assumes that everything to the right of the initial '.' is the extension and does not make an exception if this happens to be the leftmost character.

If all files in the list have the same extension and the output pattern is defaulted to the current date or does not include unique parts of the original filenames the program will not be able to process more than a single file. This is because new names of the second and subsequent files in the list will all match the new name of the first file and so will be reported as matching an existing file and otherwise ignored.

If your command shell treats ( and ) as special (bash, sh and ksh all do this) you'll need to enclose the pattern in single or double quotes if it includes the f , t or e elements. These all use ( and ) as argument delimiters so you must quote the pattern to prevent the shell from interpreting them.

bydate makes no attempt to check that the characters supplied within the arguments of the t and e pattern elements are valid in file names accepted by your operating system. If they are invalid you may get unexpected results and/or misleading error messages depending on how your operating system handles them. In particular, DOS/Windows may complain that it cannot find the required file or directory rather than saying that the output name contains invalid characters.

This document was created by man2html, using the manual pages.
Time: 17:39:33 GMT, April 17, 2010