Newer
Older
tren / tren.py
#!/usr/bin/env python
# tren.py
# Copyright (c) 2010 TundraWare Inc.
# For Updates See:  http://www.tundraware.com/Software/tren

# Program Information

PROGNAME = "tren.py"
BASENAME = PROGNAME.split(".py")[0]
PROGENV  = BASENAME.upper()
RCSID = "$Id: tren.py,v 1.156 2010/02/24 00:00:35 tundra Exp $"
VERSION = RCSID.split()[2]

# Copyright Information

CPRT         = "(c)"
DATE         = "2010"
OWNER        = "TundraWare Inc."
RIGHTS       = "All Rights Reserved."
COPYRIGHT    = "Copyright %s %s, %s  %s" % (CPRT, DATE, OWNER, RIGHTS)

PROGVER      = PROGNAME + " " + VERSION + (" - %s" % COPYRIGHT)
HOMEPAGE     = "http://www.tundraware.com/Software/%s\n" % BASENAME



#----------------------------------------------------------#
#            Variables User Might Change                   #
#----------------------------------------------------------#



#------------------- Nothing Below Here Should Need Changing ------------------#


#----------------------------------------------------------#
#                       Imports                            #
#----------------------------------------------------------#

import copy
import getopt
import os
from   stat import *
import sys


#----------------------------------------------------------#
#                 Aliases & Redefinitions                  #
#----------------------------------------------------------#



#----------------------------------------------------------#
#                Constants & Literals                      #
#----------------------------------------------------------#



#####
# General Program Constants
#####

MAXINCLUDES  =  50          # Maximum number of includes allowed
MAXNAMELEN   =  255         # Maximum file or directory name length
MINNAMELEN   =  1           # Minimum file or directory name length

#####
# Message Formatting Constants
#####

# Make sure these make sense: ProgramOptions[MAXLINELEN] > PADWIDTH + WRAPINDENT
# because of the way line conditioning/wrap works.

PADCHAR      =  " "         # Padding character
PADWIDTH     =  30          # Column width
LSTPAD       =  13          # Padding to use when dumping lists
WRAPINDENT   =   8          # Extra indent on wrapped lines
MINLEN       =  PADWIDTH + WRAPINDENT + 1  # Minimum line length


#####
# Literals
#####

ARROW        =  "--->"      # Used for formatting renaming messages
COMMENT      =  "#"         # Comment character in include files
DEFLEN       =  80          # Default output line length
DEFSEP       =  "="         # Default rename command separator: old=new
DEFSUFFIX    =  ".backup"   # String used to rename existing targets
DEFESC       =  "\\"        # Escape character
INCL         =  "I"         # Include file command line option
INDENT       =  "    "      # Indent string for nested messages
NULLESC      =  "Escape string"                   # Cannot be null
NULLRENSEP   =  "Old/New separator string"        # Cannot be null
NULLSUFFIX   =  "Forced renaming suffix string"   # Cannot be null
OPTINTRO     =  "-"         # Option introducer

# Internal program state literals

DEBUG          =  "DEBUG"
CASESENSITIVE  =  "CASESENSITIVE"
ESCAPE         =  "ESCAPE"
ERRORCONTINUE  =  "ERRORCONTINUE"
EXISTSUFFIX    =  "EXISTSUFFIX"
FORCERENAME    =  "FORCERENAME"
GLOBAL         =  "GLOBAL"
MAXLINELEN     =  "MAXLINELEN"
QUIET          =  "QUIET"
REGEX          =  "REGEX"
RENSEP         =  "RENSEP"
TESTMODE       =  "TESTMODE"

# Rename target keys

BASE           =  "BASENAME"
PATHNAME       =  "PATHNAME"          
STATS          =  "STATS"
ORDERBYCMDLINE =  "ORDERBYCOMMANDLINE"
ORDERBYALPHA   =  "ORDERBYALPHA"
ORDERBYMODE    =  "ORDERBYMODE"
ORDERBYINODE   =  "ORDERBYINODE"
ORDERBYDEV     =  "ORDERBYDEV"
ORDERBYNLINK   =  "ORDERBYNLINK"
ORDERBYUID     =  "ORDERBYUID"
ORDERBYGID     =  "ORDERBYGID"
ORDERBYATIME   =  "ORDERBYATIME"
ORDERBYCTIME   =  "ORDERBYCTIME"
ORDERBYMTIME   =  "ORDERBYMTIME"
ORDERBYSIZE    =  "ORDERBYSIZE"

# Rename string keys

NEW            = "NEW"
OLD            = "OLD"



#----------------------------------------------------------#
#              Prompts, & Application Strings              #
#----------------------------------------------------------#


#####
# Debug Messages
#####

DEBUGFLAG     =   "-d"
dCMDLINE      =   "Command Line"
dCURSTATE     =   "Current State Of Program Options"
dDEBUG        =   "DEBUG"
dDUMPOBJ      =   "Dumping Object %s"
dINCLFILES    =   "Included Files:"
dPROGENV      =   "$" + PROGENV
dRENREQ       =   "Renaming Request:"
dRENTARGET    =   "Rename Target:"
dRESOLVEDOPTS =   "Resolved Command Line"
dSEPCHAR      =   "-"     # Used for debug separator lines
dSORTVIEW     =   "Sort View:"


#####
# Error Messages
#####

eARGLENGTH    =  "%s must contain exactly %s character(s)!"
eBADARG       =  "Invalid command line: %s!"
eBADINCL      =  "option -%s requires argument" % INCL
eBADNEWOLD    =  "Bad -r argument '%s'!  Requires exactly one new, old string separator (Default: " + DEFSEP + ")"
eBADLEN       =  "Bad line length '%s'!"
eERROR        =  "ERROR"
eFILEOPEN     =  "Cannot open file '%s': %s!"
eLINELEN      =  "Specified line length too short!  Must be at least %s" % MINLEN
eNAMELONG     =  "Renaming '%s' to new name '%s' too long! (Maximum length is %s.)"
eNAMESHORT    =  "Renaming '%s' to new name '%s' too short! (Minimum length is %s.)"
eNULLARG      =  "%s cannot be empty!"
eRENAMEFAIL   =  "Attempt to rename '%s' to '%s' failed : %s!"
eTOOMANYINC   =  "Too many includes! (Max is %d) Possible circular reference?" % MAXINCLUDES


#####
# Informational Messages
#####

iRENFORCED    =  "Target '%s' Exists.  Creating Backup."
iRENSKIPPED   =  "Target '%s' Exists. Renaming Of '%s' Skipped."
iRENAMING     =  "Renaming '%s' " + ARROW + " '%s'."

#####
# Usage Prompts
#####

uTable = [PROGVER,
          HOMEPAGE,
          "usage:  " + PROGNAME + " [-CcdEfGghqtvwXx] [-I file] [-r old=new]... [-S suffix] file|dir file|dir ...",
          "   where,",
          "         -C            Do case-sensitive renaming (Default)",
          "         -c            Collapse case when doing string substitution (Default: False)",
          "         -d            Dump debugging information (Default: False)",
          "         -E            Continue after an error is encountered (Default: False)",
          "         -f            Force renaming even if target file or directory name already exists (Default: False)",
          "         -G            Rename only the first instance of the specified string (Default)",
          "         -g            Replace all instances (global rename) of the old string with the new (Default: False)",
          "         -h            Print help information (Default: False)",
          "         -I file       Include command line arguments from file",
          "         -P char       Use 'char' as the escape sequence (Default: %s)" % DEFESC,
          "         -q            Quiet mode, do not show progress (Default: False)",
          "         -R char       Separator character for -r rename arguments (Default: %s)" % DEFSEP,
          "         -r old=new    Replace old with new in file or directory names",
          "         -S suffix     Suffix to use when renaming existing filenames (Default: %s)" % DEFSUFFIX,
          "         -t            Test mode, don't rename, just show what the program *would* do (Default: False)",
          "         -v            Print detailed program version information and continue (Default: False)",
          "         -w            Line length of diagnostic and error output (Default: %s)" % DEFLEN,
          "         -X            Treat the renaming strings literally (Default)",
          "         -x            Treat the old replacement string as a Python regular expression (Default: False)",
         ]

#----------------------------------------------------------#
#          Global Variables & Data Structures              #
#----------------------------------------------------------#

# Program toggle and option defaults

IncludedFiles     = []

ProgramOptions    = {

                     DEBUG         : False,     # Debugging off
                     CASESENSITIVE : True,      # Search is case-sensitive
                     ESCAPE        : DEFESC,    # Escape string
                     ERRORCONTINUE : False,     # Do not continue after error
                     EXISTSUFFIX   : DEFSUFFIX, # What to tack on when renaming existing targets
                     FORCERENAME   : False,     # Do not rename if target already exists
                     GLOBAL        : False,     # Only rename first instance of old string
                     MAXLINELEN    : DEFLEN,    # Width of output messages
                     QUIET         : False,     # Display progress
                     REGEX         : False,     # Do not treat old string as a regex
                     RENSEP        : DEFSEP,    # Old, New string separator for -r
                     TESTMODE      : False      # Global data structures
                    }


#--------------------------- Code Begins Here ---------------------------------#


#----------------------------------------------------------#
#             Object Base Class Definitions                #
#----------------------------------------------------------#


#####
# Container For Holding Rename Targets And Renaming Requests
#####

class RenameTargets:

    """ 
        This class is used to keep track of all the files and/or
        directories we're renaming.  After the class is constructed
        and the command line fully parsed, this will contain:

        self.RenNames    = { fullname : {BASE : basename, PATHNAME : pathtofile, STAT : stats}
                             ... (repeated for each rename target)
                           }

        self.SortViews   = {

                             ORDERBYCMDLINE : [fullnames in command line order],
                             ORDERBYALPHA   : [fullnames in alphabetic order],
                             ORDERBYMODE    : [fullnames in mode order],
                             ORDERBYINODE   : [fullnames in inode order],
                             ORDERBYDEV     : [fullnames in devs order],
                             ORDERBYNLINK   : [fullnames in nlinks order],
                             ORDERBYUID     : [fullnames in uids order],
                             ORDERBYGID     : [fullnames in gids order],
                             ORDERBYATIME   : [fullnames in atimes order],
                             ORDERBYCTIME   : [fullnames in ctimes order],
                             ORDERBYMTIME   : [fullnames in mtimes order],
                             ORDERBYSIZE    : [fullnames in size order]
                            }

        self.RenRequests =  [
                             { OLD           : old rename string,
                               NEW           : new rename string,
                               DEBUG         : debug flag,
                               CASESENSITIVE : case sensitivity flag,
                               ERRORCONTINUE : error continuation flag,
                               FORCERENAME   : force renaming flag,
                               GLOBAL        : global replace flag,
                               MAXLINELEN    : max output line length,
                               QUIET         : quiet output flag,
                               REGEX         : regular expression enable flag,
                               RENSEP        : old/new rename separator string,
                               TESTMODE      : testmode flag
                             } ... (repeated for each rename request)
                            ]

    """

    #####
    # Constructor
    #####

    def __init__(self, targs):

        # Dictionary of all rename targets and their stat info

        self.RenNames   =   {}

        # Dictionary of all possible sort views
        # We can load the first two right away since they're based
        # only on the target names provided on the command line

        i=0
        while i < len(targs):
            targs[i] = os.path.abspath(targs[i])
            i += 1

        alpha = targs[:]
        alpha.sort()
        self.SortViews  =   {ORDERBYCMDLINE : targs, ORDERBYALPHA : alpha}
        del alpha

        # Dictionary of all the renaming requests - will be filled in
        # by -r command line parsing.

        self.RenRequests = []


        # This data structure is used while we build up sort
        # orders based on stat information.

        SeqTypes = [ [ST_MODE,   {},  ORDERBYMODE],
                     [ST_INO,    {},  ORDERBYINODE],
                     [ST_DEV,    {},  ORDERBYDEV],
                     [ST_NLINK,  {},  ORDERBYNLINK],
                     [ST_UID,    {},  ORDERBYUID],
                     [ST_GID,    {},  ORDERBYGID],
                     [ST_ATIME,  {},  ORDERBYATIME],
                     [ST_CTIME,  {},  ORDERBYCTIME],
                     [ST_MTIME,  {},  ORDERBYMTIME],
                     [ST_SIZE,   {},  ORDERBYSIZE],
                   ]

        # Populate the data structures with each targets' stat information

        for fullname in targs:

            try:
                basename = os.path.basename(fullname)
                stats    = os.stat(fullname)
            except (IOError, OSError) as e:
                ErrorMsg(eFILEOPEN % (fullname, e.args[1]), EXIT=True)

            # Store fullname, basename, and stat info for this file

            self.RenNames[fullname] = {BASE : basename, PATHNAME : fullname.split(basename)[0], STATS : stats}

            # Incrementally build lists of keys that will later be
            # used to create sequence renaming tokens

            for seqtype in SeqTypes:

                statflag, storage, order = seqtype

                # Handle os.stat() values

                statval = stats[statflag]

                if statval in storage:
                    storage[statval].append(fullname)
                else:
                    storage[statval] = [fullname]


        # Create the various sorted views we may need for sequence
        # renaming tokens

        for seqtype in SeqTypes:

            statflag, storage, order = seqtype

            vieworder = storage.keys()
            vieworder.sort()            

            # Sort alphabetically when multiple filenames
            # map to the same key, creating overall
            # ordering as we go.

            t = []
            for i in vieworder:
                storage[i].sort()
                for j in storage[i]:
                    t.append(j)

            # Now store for future reference

            self.SortViews[order] = t

        # Release the working data structures

        del SeqTypes

    # End of '__init__()'


    #####
    # Debug Dump 
    #####

    def DumpObj(self):

        SEPARATOR = dSEPCHAR * ProgramOptions[MAXLINELEN]
        DebugMsg("\n")
        DebugMsg(SEPARATOR)
        DebugMsg(dDUMPOBJ % str(self))
        DebugMsg(SEPARATOR)


        # Dump the RenNames and SortView dictionaries

        for i, msg in ((self.RenNames, dRENTARGET), (self.SortViews, dSORTVIEW)):

            for j in i:
                DumpList(DebugMsg, msg, j, i[j])

        for rr in self.RenRequests:
            DumpList(DebugMsg, dRENREQ, "", rr)

        DebugMsg(SEPARATOR + "\n\n")

    # End of 'DumpObj()'


    #####
    # Go Do The Requested Renaming
    #####

    def ProcessRenameRequests(self):

        self.indentlevel = -1

        # Create a list of all renaming to be done.
        # This includes the renaming of any existing targets.

        for target in self.SortViews[ORDERBYCMDLINE]:

            oldname, pathname = self.RenNames[target][BASE], self.RenNames[target][PATHNAME]
            newname = oldname

            for renrequest in self.RenRequests:

                old, new = self.ResolveRenameTokens(renrequest[OLD], renrequest[NEW])
                oldstrings = []

                # Build a list of indexes to every occurence of the old string,
                # taking case sensitivity into account

                # Handle the case when old = "".
                # This means to *replace the entire* old name with new.
                    
                if not old:
                    old = oldname

                # Collapse case if requested

                name = oldname
                if not renrequest[CASESENSITIVE]:

                    name = name.lower()
                    old  = old.lower()

                i = name.find(old)
                while i >= 0:

                    oldstrings.append(i)
                    i = name.find(old, i + len(old))

                # If we found any matching strings, replace them

                if oldstrings:
                    
                    # Only process leftmost occurence if global replace is off

                    if not renrequest[GLOBAL]:
                        oldstrings = [oldstrings[0],]

                    # Replace selected substring(s).
                    # Substitute from R->L in original string
                    # so as not to mess up the replacement indicies.

                    oldstrings.reverse()
                    for i in oldstrings:
                        newname = newname[:i] + new + newname[i + len(old):]


            # Nothing to do, if old- and new names are the same

            if newname != oldname:

                # If we're in test mode, just show what we would do

                if ProgramOptions[TESTMODE]:

                    InfoMsg(iRENAMING % (pathname+oldname, pathname+newname))

                # Otherwise, actually do the renaming

                else:
                    self.__RenameIt(pathname, oldname, newname)
            
    # End of 'ProcessRenameRequests()'


    #####
    # Actually Rename A File
    #####

    def __RenameIt(self, pathname, oldname, newname):

        self.indentlevel += 1
        indent = self.indentlevel * INDENT
        newlen = len(newname)
        
        # First make sure the new name meets length constraints

        if newlen < MINNAMELEN:
            ErrorMsg(indent + eNAMESHORT% (oldname, newname, MINNAMELEN))
            return

        if newlen > MAXNAMELEN:
            ErrorMsg(indent + eNAMELONG % (oldname, newname, MAXNAMELEN))
            return

        # Get names into absolute path form

        fullold = pathname + oldname
        fullnew = pathname + newname

        # Let the user know what we're trying to do

        InfoMsg(indent + iRENAMING % (fullold, fullnew))

        # See if our proposed renaming is about to stomp on an
        # existing file, and create a backup if forced renaming
        # requested.  We such backups with a recursive call to
        # ourselves so that length and backups of backups are
        # enforced.


        if os.path.exists(fullnew):

            if ProgramOptions[FORCERENAME]:

                # Create the backup

                bkuname = newname + ProgramOptions[EXISTSUFFIX]
                InfoMsg(indent + iRENFORCED % fullnew)
                self.__RenameIt(pathname, newname, bkuname)
                
                # Rename the original

                self.__RenameIt(pathname, oldname, newname)


            else:
                InfoMsg(indent + iRENSKIPPED % (fullnew, fullold))

        # No target conflict, just do the requested renaming

        else:
            try:
                os.rename(fullold, fullnew)
            except OSError as e:
                ErrorMsg(eRENAMEFAIL % (fullold, fullnew, e.args[1]))

        self.indentlevel -= 1

    # End of '__RenameIt()'

    
    #####
    # Resolve Rename Strings
    #####

    """ This takes "old" and "new" renaming strings as input and resolves
        all outstanding renaming token references so that they can
        then be applied to the rename.
    """

    def ResolveRenameTokens(self, old, new):


        return [old, new]

    # End of 'ResolveRenameTokens()'


# End of class 'RenameTargets'
    

#----------------------------------------------------------#
#             Supporting Function Definitions              #
#----------------------------------------------------------#


#####
# Turn A List Into Columns With Space Padding
#####

def ColumnPad(list, PAD=PADCHAR, WIDTH=PADWIDTH):

    retval = ""
    for l in list:
        l = str(l)
        retval += l + ((WIDTH - len(l)) * PAD)

    return retval

# End of 'ColumnPad()'


#####
# Condition Line Length With Fancy Wrap And Formatting
#####

def ConditionLine(msg, 
                  PAD=PADCHAR, \
                  WIDTH=PADWIDTH, \
                  wrapindent=WRAPINDENT ):

    retval = []
    retval.append(msg[:ProgramOptions[MAXLINELEN]])
    msg = msg[ProgramOptions[MAXLINELEN]:]

    while msg:
        msg = PAD * (WIDTH + wrapindent) + msg
        retval.append(msg[:ProgramOptions[MAXLINELEN]])
        msg = msg[ProgramOptions[MAXLINELEN]:]

    return retval

# End of 'ConditionLine()'


#####
# Print A Debug Message
#####

def DebugMsg(msg):
 
   l = ConditionLine(msg)
   for msg in l:
        PrintStderr(PROGNAME + " " + dDEBUG + ": " + msg)

# End of 'DebugMsg()'


#####
# Debug Dump Of A List
#####

def DumpList(handler, msg, listname, content):

    handler(msg)
    itemarrow = ColumnPad([listname, " "], WIDTH=LSTPAD)
    handler(ColumnPad([" ", " %s %s" % (itemarrow, content)]))

# End of 'DumpList()'


#####
# Dump The State Of The Program
#####

def DumpState():

    SEPARATOR = dSEPCHAR * ProgramOptions[MAXLINELEN]
    DebugMsg(SEPARATOR)
    DebugMsg(dCURSTATE)
    DebugMsg(SEPARATOR)

    opts = ProgramOptions.keys()
    opts.sort()
    for o in opts:
        DebugMsg(ColumnPad([o, ProgramOptions[o]]))

    DebugMsg(SEPARATOR)


# End of 'DumpState()'


#####
# Print An Error Message, Exiting Program As Required
#####

def ErrorMsg(emsg, EXIT=False):

    l = ConditionLine(emsg)

    for emsg in l:
        PrintStderr(PROGNAME + " " + eERROR + ": " + emsg)

    if EXIT or not ProgramOptions[ERRORCONTINUE]:
        sys.exit(1)

# End of 'ErrorMsg()'

#####
# Split -r Argument Into Separate Old And New Strings
#####

def GetOldNew(arg):


    escaping = False
    numseps  = 0 
    sepindex = 0
    oldnewsep = ProgramOptions[RENSEP]

    i = 0
    while i < len(arg):

        # Scan string ignoring escaped separators

        if arg[i:].startswith(oldnewsep):

            if (i > 0 and (arg[i-1] != ProgramOptions[ESCAPE])) or i == 0:
                sepindex = i
                numseps += 1
            
            i += len(oldnewsep)

        else:
            i += 1


    if numseps != 1:
        ErrorMsg(eBADNEWOLD % arg, EXIT=True)

    else:
        old, new = arg[:sepindex], arg[sepindex + len(oldnewsep):]
        old = old.replace(ProgramOptions[ESCAPE] + oldnewsep, oldnewsep)
        new = new.replace(ProgramOptions[ESCAPE] + oldnewsep, oldnewsep)
        return [old, new]

# End of 'GetOldNew()'


#####
# Print An Informational Message
#####

def InfoMsg(imsg):

    l = ConditionLine(imsg)

    msgtype = ""
    if ProgramOptions[TESTMODE]:
        msgtype = TESTMODE

    if not ProgramOptions[QUIET]:
        for msg in l:
            PrintStdout(PROGNAME + " " + msgtype + ": " + msg)

# End of 'InfoMsg()'


#####
# Print To stderr
#####

def PrintStderr(msg, TRAILING="\n"):
    sys.stderr.write(msg + TRAILING)

# End of 'PrintStderr()'


#####
# Print To stdout
#####

def PrintStdout(msg, TRAILING="\n"):
    sys.stdout.write(msg + TRAILING)

# End of 'PrintStdout'


#####
# Process Include Files On The Command Line
#####

def ProcessIncludes(OPTIONS):

    """ Resolve include file references allowing for nested includes.
        This has to be done here separate from the command line options so
        that getopt() processing below will "see" the included statements.

        This is a bit tricky because we have to handle every possible
        legal command line syntax for option specification:

          -I filename
          -Ifilename
          -....I filename
          -....Ifilename
    """

    NUMINCLUDES = 0
    FoundNewInclude = True

    while FoundNewInclude:

        FoundNewInclude = False
        i = 0
        while i < len(OPTIONS):

            # Detect all possible command line include constructs,
            # isolating the requested filename and replaciing its
            # contents at that position in the command line.

            field = OPTIONS[i]
            if field.startswith(OPTINTRO) and (field.find(INCL) > -1):

                FoundNewInclude = True
                lhs, rhs = field.split(INCL)

                if lhs == OPTINTRO:
                    lhs = ""

                if rhs == "":

                    if i < len(OPTIONS)-1:

                        inclfile = OPTIONS[i+1]
                        OPTIONS = OPTIONS[:i+1] + OPTIONS[i+2:]

                    # We have an include without a filename at the end
                    # of the command line which is bogus.
                    else:
                        ErrorMsg(eBADARG % eBADINCL, EXIT=True)

                else:
                    inclfile = rhs

                # Before actually doing the include, make sure we've
                # not exceeded the limit.  This is here mostly to make
                # sure we stop recursive/circular includes.

                NUMINCLUDES += 1
                if NUMINCLUDES > MAXINCLUDES:
                    ErrorMsg(eTOOMANYINC, EXIT=True)

                # Read the included file, stripping out comments

                try:
                    n = []
                    f = open(inclfile)
                    for line in f.readlines():
                        line = line.split(COMMENT)[0]
                        n += line.split()
                    f.close()
    
                    # Keep track of the filenames being included
        
                    IncludedFiles.append(os.path.abspath(inclfile))

                    # Insert content of included file at current
                    # command line position

                    # A non-null left hand side means that there were
                    # options before the include we need to preserve

                    if lhs:
                        n = [lhs] + n

                    OPTIONS = OPTIONS[:i] + n + OPTIONS[i+1:]
            
                except IOError as e:
                    ErrorMsg(eFILEOPEN % (inclfile, e.args[1]), EXIT=True)
        
            i += 1

    return OPTIONS

# End of 'ProcessIncludes()'


#####
# Print Usage Information
#####

def Usage():
    for line in uTable:
        PrintStdout(line)

# End of 'Usage()'


#----------------------------------------------------------#
#                    Program Entry Point                   #
#----------------------------------------------------------#

#####
# Command Line Preprocessing
# 
# Some things have to be done *before* the command line
# options can actually be processed.  This includes:
#
#  1) Prepending any options specified in the environment variable.
#
#  2) Resolving any include file references
#
#  3) Separating the command line into [options ... filenames ..]
#     groupings so that user can interweave multiple options
#     and names on the command line.
#
#  4) Building the data structures that depend on the file/dir names
#     specified for renaming.  We have to do this first, because
#     -r renaming operations specified on the command line will
#     need this information if they make use of renaming tokens.
#
#####

# Process any options set in the environment first, and then those
# given on the command line


OPTIONS = sys.argv[1:]

envopt = os.getenv(PROGENV)
if envopt:
    OPTIONS = envopt.split() + OPTIONS

# Deal with include files

OPTIONS = ProcessIncludes(OPTIONS)

# And parse the command line

try:
    opts, args = getopt.getopt(OPTIONS, 'CcdEfGghP:qR:r:S:tvw:Xx]')
except getopt.GetoptError as e:
    ErrorMsg(eBADARG % e.args[0], EXIT=True)

# Create and populate an object with rename targets.  This must be
# done here because this object also stores the -r renaming requests
# we may find in the options processing below.  Also, this object must
# be fully populated before any actual renaming can take place since
# many of the renaming tokens derive information about the file.

targs = RenameTargets(args)

# Now process the options

for opt, val in opts:

    if opt == "-C":
        ProgramOptions[CASESENSITIVE] = True

    if opt == "-c":
        ProgramOptions[CASESENSITIVE] = False

    if opt == "-d":
        ProgramOptions[DEBUG] = True
        DumpState()

    if opt == "-E":
        ProgramOptions[ERRORCONTINUE] = True

    if opt == "-f":
        ProgramOptions[FORCERENAME] = True

    if opt == "-G":
        ProgramOptions[GLOBAL] = False

    if opt == "-g":
        ProgramOptions[GLOBAL] = True

    if opt == "-h":
        Usage()
        sys.exit(0)

    if opt == "-P":
        if len(val) == 1:
            ProgramOptions[ESCAPE] = val
        else:
            ErrorMsg(eARGLENGTH % (NULLESC, 1), EXIT=True)

    if opt == "-q":
        ProgramOptions[QUIET] = True

    if opt == '-R':
        if len(val) == 1:
            ProgramOptions[RENSEP] = val
        else:
            ErrorMsg(eARGLENGTH % (NULLRENSEP, 1), EXIT=True)

    if opt == "-r":
        req = {}
        req[OLD], req[NEW] = GetOldNew(val)
        for opt in ProgramOptions:
            req[opt] = ProgramOptions[opt]
        targs.RenRequests.append(req)

    if opt == "-S":
        if val:
            ProgramOptions[EXISTSUFFIX] = val
        else:
            ErrorMsg(eNULLARG % NULLSUFFIX, EXIT=True)

    if opt == "-t":
        ProgramOptions[TESTMODE] = True

    if opt == "-v":
        PrintStdout(RCSID)

    if opt == "-w":
        try:
            l = int(val)
        except:
            ErrorMsg(eBADLEN % val, EXIT=True)
        if l < MINLEN:
            ErrorMsg(eLINELEN, EXIT=True)
        ProgramOptions[MAXLINELEN] = l

    if opt == "-X":
        ProgramOptions[REGEX] = False

    if opt == "-x":
        ProgramOptions[REGEX] = True


# At this point, the command line has been fully processed and the
# container fully populated.  Provide debug info about both if
# requested.

if ProgramOptions[DEBUG]:

    # Dump what we know about the command line

    DumpList(DebugMsg, dCMDLINE, "", sys.argv)
    DumpList(DebugMsg, dPROGENV, "", envopt)
    DumpList(DebugMsg, dRESOLVEDOPTS, "", OPTIONS)

    # Dump what we know about included files

    DumpList(DebugMsg, dINCLFILES, "", IncludedFiles)

    # Dump what we know about the container

    targs.DumpObj()


# Perform reqested renamings

targs.ProcessRenameRequests()


# Release the target container if we created one

del targs