
				      WRen
				Wildcard Rename

			   Copyright Jason Hood 2002

			     Freeware. Version 1.00


    ===========
    Description
    ===========

    WRen is a substitute for the standard DOS REN command.  It	uses  simple
    pattern  matching  to provide greater control in renaming files. It will
    also check for existing files and new file conflicts  before  performing
    the rename. The rename can be undone.


    =====
    Usage
    =====

    As with REN, the first  parameter  is  the	pattern  for  current  names
    ("pattern")  and  the  second  is  the  pattern  for new names ("substi-
    tution"). If no substitution is  given,  WRen  acts  as  a  simple  file
    lister.   Unlike  REN,  both patterns can contain a path. If the pattern
    has a path, but the  substitution  doesn't,  WRen  acts  likes  REN  and
    renames  files within the same directory. However, if both patterns have
    a path, WRen will move files to the new directory. Both paths must be on
    the same drive.

    WRen has a number of options to control the renaming process.  An option
    begins with "-".  Multiple options can be combined.

	-a	all files (include hidden and system files)
	-c	match case
	-d	include directories
	-t	test (display instead of rename)
	-u	undo the previous rename
	-h	help


    a - All files
    d - Directories

    Normally hidden and/or system files and directories  are  excluded	from
    the search.  These options will include them.


    c - Case sensitive

    By default, files are matched ignoring case. This option will cause case
    to	be  significant  (ie: "file" will not match "FILE"). Of course, this
    option is only relevant on LFN systems, where case is preserved.


    t - Test

    This option will display the current  name	along  with  its  new  name,
    instead  of actually performing the rename. It still checks for existing
    files and renaming conflicts. If used without a  substitution,  it	will
    display each name (without path) with colons separating the subpatterns.


    u - Undo

    The list of files currently being renamed is written to disk in the file
    "wrenundo.lst",  in  the  directory  pointed  to by the TEMP environment
    variable (or TMP or C:\). This  option  (which  will  ignore  all  other
    options  and parameters), will access this list and restore the files to
    their original names. The list is then deleted. Undoing a rename  should
    be performed as soon as possible, from the same directory.


    h - Help

    WRen without any parameters will display a	brief  usage  message.	This
    option  (or  "/?"  or "--help"), will display the same message, adding a
    description of the pattern matching.


    ================
    Pattern Matching
    ================

    WRen has an extended wildcard syntax. Briefly:

	*	match zero or more characters (maximise)
	**	match zero or more characters (minimise)
	?	match exactly one character
	#	match a digit (0-9)
	[set]	match one character in the set of characters
	[!set]	match one character NOT in the set (can also use "^")
	:	force the start of a new subpattern (within literals only)

    Like DOS, "*" will match zero or more characters and "?" will match  any
    one  character  (including the dot).  Normally "*" will try and match as
    much as possible, which might be too much; "**" will match as little  as
    possible. Eg: given the file "one.two.three":

	*.*	will match as "one.two" and "three"
	**.*	will match as "one" and "two.three"

    Unlike DOS, "*.*" will NOT match all files - it will  only  match  files
    that  contain  a dot. However, "*." will match files that do not contain
    an extension.

    A set can contain a group of characters ("[aeiou]") and/or  a  range  of
    characters ("[a-z]"). If the set starts with "!" or "^", only characters
    NOT in the set will match. A set can also contain "#", which  represents
    "0-9".   To include "-", place it first or last; to include "]" place it
    first; to include "#", prefix it with "$" (which will also work with the
    previous  two  characters).  If  the  set  contains  "?",  matching  the
    character is optional.  Eg: given the files "test", "test1" and "testa",
    the pattern "test[1?]" will match "test" and "test1", but NOT "testa".

    The matching filename is broken up into subpatterns.  Each	wildcard  is
    its  own subpattern, and each group of literals forms a subpattern.  If,
    for some reason, you need to separate a group of literals into more than
    one  subpattern,  use ":" to indicate the separation. Eg: "read:me" will
    match "readme" as two subpatterns, not one. If the second character is a
    colon  and	the  first  is	a  letter, it is taken as a drive specifier,
    rather than a subpattern; prefix with "./" to work around it.

    To specify a subpattern in the substitution pattern, use "$n", with  "n"
    being  the	subpattern  number.   Subpatterns  are numbered from left to
    right, starting with 1; 0 is the original filename. Wildcards  can	also
    be	used  in  the  substitution,  with  each  one  corresponding  to its
    numerical equivalent in the pattern (note that "**" and "[set]"  in  the
    pattern  are  just	"*"  and  "[" in the substitution).  A range of sub-
    patterns can be selected by "$n-m", with "n" being the first  subpattern
    and  "m" the last.  If "m" is smaller than "n", then it is taken as "$n"
    and "-m".  "$n+" will select all subpatterns from the nth.

    Subpatterns can be lowercased,  uppercased	or  capitalised  (where  the
    first  letter  is  uppercased  and	the remainder are lowercased). To do
    this, place a "-", "+" or "^", respectively, immediately after "$".  Eg:
    "$-0"  will  lowercase the entire filename. The default character map is
    suitable for code page 437; users of other code  pages  might  run	into
    problems with wrong conversions.

    "$" is used as a special character (escape) in both patterns. To include
    a  literal	"$",  double it up. Eg: to match the file "tmp.$$$", use the
    pattern "tmp.$$$$$$". Similarly, to include "#" or  "["  as  characters,
    rather than wildcards, precede them with "$".


    ========
    Examples
    ========

	 Old		   New		    Pattern	Substitution
    global.info-1.gz	global.i1z	    *.i*#*	  *.i#z
    global.info-2.gz	global.i2z
    global.info-3.gz	global.i3z

    README		READ_ME.txt	    read:me*	  $1_$2*.txt
    readme.1st		read_me.1st.txt
    reader.exe		<not renamed>

    "Song - Artist.mp3"	"Artist - Song.mp3" "* - *.mp3"   $3$2$1$4

    "Song - Artist1 - Artist2.mp3"
	     "Artist1 - Artist2 - Song.mp3" "** - *.mp3"  $3$2$1$4


    ============
    Return Value
    ============

	0	no problems
	1	invalid option, option without pattern
	2	unable to compile pattern
	3	no files matched the pattern (not when listing)
	4	not enough memory to store the filenames
	5	a renamed file already exists
	6	a renamed file occurs twice
	7	unable to rename, no undo file


    ===============
    Acknowledgments
    ===============

    Ralf Brown's Interrupt List.
    Vesa Kolhinen: the original pattern matching was taken from Delen.


    =======
    Contact
    =======

    mailto:jadoxa@yahoo.com.au
    http://wren.adoxa.cjb.net/

    Jason Hood
    11 Buckle Street
    North Rockhampton
    Qld 4701
    Australia


    ============
    Distribution
    ============

    The original zipfile can be freely distributed, by any means. However, I
    would  like  to  be  informed if it is placed on a CD-ROM (other than an
    archive compilation).  Modified versions may be distributed, as long  as
    the original zipfile is included (I would prefer to be contacted).


    ==============================
    Jason Hood, 27 November, 2002.
