DEFINITION MODULE FileNameStrs;
(*******************************************************************
Module FileNameStrs (Version 1.0)
Copyright (c) 1990-2006 by Andreas Fischlin and ETH Zurich.
Purpose String manipulation routines needed to work with
directory and file names.
Remarks Used definitions (EBNF):
VolName = String. # Mac length <=27
DirName = String. # Mac length <=31
FileName = String [extSeparator String]. # Mac length <=31
Path = VolName volSeparator {DirName pathSeparator}.
FullPath = Path FileName | DirName.
RelPath = pathSeparator {DirName pathSeparator}.
Programming
o Design
Andreas Fischlin 21/09/1990
o Implementation
Andreas Fischlin 21/09/1990
ETH Zurich
Systems Ecology
CHN E 35.1
Universitaetstrasse 16
8092 Zurich
SWITZERLAND
URLs:
<mailto:RAMSES@env.ethz.ch>
<http://www.sysecol.ethz.ch>
<http://www.sysecol.ethz.ch/SimSoftware/RAMSES>
Last revision of definition: 02/06/1991 AF
*******************************************************************)
VAR
extSeparator, pathSeparator, volSeparator: CHAR;
(*
Following defaults used:
extSeparator = '.'
pathSeparator = ':' or '/' or '\' depending on the platform
(must NOT be changed!)
volSeparator = ':' or '/' (must NOT be changed!)
*)
(* ===============================================================
Note, most examples given in this definition are for the
Macintosh platform. However, the routines work in a platform
independent fashion and can be used on all three supported
platforms (see DMSystem for details on supported platforms).
Note: Most of the following routines are fault tolerant and
accept input parameters in various formats. For instance:
- VolName may carry a volSeparator at the end or not, e.g.
"HD:" or "HD" are both accepted and interpreted correctly
by CompletePathFileName
- A fullPath may have a pathSeparator at the end or not
e.g. "HD:M2:Work:" or "HD:M2:Work" (ExtractRelPath)
- A basePath may have a pathSeparator at the end or not
e.g. "HD:M2:" or "HD:M2" (ExtractRelPath)
- A relative path may start or end with or without a pathSeparator
e.g. ":Dir:" or ":Dir" or "Dir:" or "Dir" are all accepted by
CompletePath and CompletePathFileName
=============================================================== *)
PROCEDURE ExtractVolName ( fullPathName : ARRAY OF CHAR;
VAR volName : ARRAY OF CHAR );
(*
E.g. ExtractVolName("HD:M2:Dir:Work:", volName) returns volName
= "HD". Note however, a volSeparator must always be present in
fullPathName to extract a volName. E.g. ExtractVolName("HD",
volName) returns an empty volName since the file name has a
higher priority and fullPathName will be interpreted to contain
just the file name "HD".
*)
PROCEDURE ExtractRelPath ( fullPath, basePath : ARRAY OF CHAR;
VAR relOrAbsPath : ARRAY OF CHAR );
(*
Returns in relOrAbsPath the relative path relative to the
folder denoted by the absolute path basePath. E.g. a call to
ExtractRelPath("HD:M2:Dir:Work:", "HD:M2:",relOrAbsPath)
returns in relOrAbsPath ":Dir:Work:". Note that the match is
case sensitive and that fullPath as well as basePath must be
absolute pathes hence e.g.
ExtractRelPath("HD:M2:Dir:Work:", "HD:M2:dir:",relOrAbsPath)
returns in relOrAbsPath "::Dir:Work:", i.e. it is treated
analogously to the following example
ExtractRelPath("HD:M2:Dir:Work::Project:", "HD:M2:Work:",relOrAbsPath)
where relOrAbsPath contains after the call "::Dir:Work::Project:".
IMPORTANT NOTICE: Despite the name of the routine, in case
that fullPathName points to a directory which is even on a
different volume, i.e. there exists no true relative path, that
relOrAbsPath will actually contain an absolute path. E.g.
ExtractRelPath("HD:M2:Dir:Work:", "HDExtra:M2:",relOrAbsPath)
returns in relOrAbsPath "HD:M2:Dir:Work:", i.e. a copy of fullPath.
Also a copy of fullPath results if either of the two paths is
a relative path specification. E.g. both examples
ExtractRelPath(":relative:", "HD:M2:dir:",relOrAbsPath)
ExtractRelPath("HD:M2:dir:", ":relative:",relOrAbsPath)
return in relOrAbsPath ":relative:" resp. "HD:M2:dir:".
Note also, that in the case where fullPath points to the same
folder as basePath, the relOrAbsPath becomes empty.
*)
PROCEDURE ExtractPath ( pathAndFileName : ARRAY OF CHAR;
VAR path : ARRAY OF CHAR );
(*
E.g. ExtractPath("HD:M2:Dir:Work:FileName.EXT", path) returns
absolute path = "HD:M2:Dir:Work:"
*)
PROCEDURE ExtractFileName ( pathAndFileName : ARRAY OF CHAR;
VAR fName : ARRAY OF CHAR );
(*
E.g. ExtractFileName("HD:M2:Dir:Work:FileName.EXT", path) returns
fName = "FileName.EXT"
*)
PROCEDURE ExtractFolderName ( pathAndFileName : ARRAY OF CHAR;
VAR folderName : ARRAY OF CHAR );
(*
Returns name of last folder in the path. E.g.
ExtractFolderName("HD:M2:Dir:Work:FileName.EXT", folderName)
returns folderName = "Work". To extract folders from the
beginning of a path, use routine ExtractSubString from
module DMStrings and use as delimiter the read only
variable pathSeparator. IMPLEMENTATION RESTRICTION:
The routines of this module deal only with strings and know
nothing about the actual properties of the designated items
in your operating system. In case of procedure
ExtractFolderName this means, if the last item in
pathAndFileName is actually a folder and you wish to extract
it, make sure, you have a path separator at the end.
Otherwise the routine can not tell a folder name apart from
a file name. E.g. ExtractFolderName("HD:M2:Dir:Work:",
folderName) returns folderName = "Work", but
ExtractFolderName("HD:M2:Dir:Work", folderName) returns
folderName = "Dir", since it understands Work to be simply
a file name. It knows nothing about the fact that 'Work' is
actually the name of a folder.
*)
PROCEDURE ExtractExt ( pathAndFileName : ARRAY OF CHAR;
VAR extension : ARRAY OF CHAR );
(*
E.g. ExtractExt("HD:M2:Dir:Work:FileName.EXT", path) returns
extension = "EXT"
*)
PROCEDURE StripExt ( fromName : ARRAY OF CHAR;
VAR toName : ARRAY OF CHAR);
(* e.g. strip '.MOD' from 'MyModule.MOD' to obtain 'MyModule' *)
PROCEDURE SetNewExt ( fromName, newExt : ARRAY OF CHAR;
VAR toName: ARRAY OF CHAR);
(*
Strip eventually present old extension from file name
fromName and add new extension newExt in toName. E.g.
SetNewExt('ThisGrandModule.DEF','MOD',toName)
returns toName = 'ThisGrandModule.MOD. In case that fromName
has no extension append newExt by inserting first extSeparator.
*)
PROCEDURE SplitPathFileName ( pathAndFileName : ARRAY OF CHAR;
VAR path,fName : ARRAY OF CHAR );
(*
E.g. SplitPathFileName("HD:M2:Dir:Work:FileName.EXT",path,fName)
returns path = "HD:M2:Dir:Work:" and fName = "FileName.EXT".
*)
PROCEDURE SplitVolPathFileName( fullPath : ARRAY OF CHAR;
VAR volN,relPath,fileN : ARRAY OF CHAR );
(*
E.g.
SplitVolPathFileName("HD:M2:Dir:Work:FileName.EXT",volN,relPath,fileN)
returns volN = "HD", relPath = ":M2:Dir:Work:", and fileN =
"FileName.EXT".
*)
PROCEDURE CompletePath ( basePath, relPath : ARRAY OF CHAR;
VAR fullPath : ARRAY OF CHAR );
(*
E.g. CompletePath("HD:M2:",":Dir:Work:", fullPath) returns
fullPath = "HD:M2:Dir:Work:". Or on a Unix or OS X platform
CompletePath("/home/user/", "myProject/subdir/") returns fullPath
= "/home/user/myProject/subdir/". There is no need for basePath
to have a pathSeparator at the end. This routine will add it as
needed. IMPORTANT: Note, if relPath is actually an absolute path,
basePath is ignored. Hint: Use CompletePathFileName(basePath,"",
relPath,fullPath) to force the correct concatenation of a relPath
string to a basePath, if relPath may have no pathSeparator at the
begin (as needed under MacOS Classic).
*)
PROCEDURE CompletePathFileName( volN, relPath, fileN : ARRAY OF CHAR;
VAR fullPathAndFileName: ARRAY OF CHAR );
(*
E.g. CompletePathFileName("HD",":M2:Dir:Work:","FileName.EXT",
fullPathAndFileName) returns fullPathAndFileName =
"HD:M2:Dir:Work:FileName.EXT". Or on a Unix or OS X platform
CompletePathFileName("/Users/user/", "myProject/subdir/",
"MyFile", fullPathAndFileName) returns in fullPathAndFileName =
"/Users/user/myProject/subdir/MyFile". There is no need for volN
to have a volSeparator nor pathSeparator at the end. This routine
will add it as needed. volN may also be an absolute or relative
path. In case volN is already the full path leading to the file
fileN, relPath is best passed as the empty string. fileN may also
contain a partial path. IMPORTANT: Note, if relPath is actually
an absolute path, argument volN is ignored. A fileN consisting only
of the pathSeparator will be ignored.
*)
END FileNameStrs.
RAMSES
Modules:
A-Z
Function
Layer
QuickRefs:
DM
AuxLib
AuxLibE
SciLib
EasyMW
MW
ISIS
RMSLib