1# Module 'riscospath' -- common operations on RISC OS pathnames.
2
3# contributed by Andrew Clover  ( andrew@oaktree.co.uk )
4
5# The "os.path" name is an alias for this module on RISC OS systems;
6# on other systems (e.g. Mac, Windows), os.path provides the same
7# operations in a manner specific to that platform, and is an alias
8# to another module (e.g. macpath, ntpath).
9
10"""
11Instead of importing this module directly, import os and refer to this module
12as os.path.
13"""
14
15# strings representing various path-related bits and pieces
16curdir = '@'
17pardir = '^'
18extsep = '/'
19sep = '.'
20pathsep = ','
21defpath = '<Run$Dir>'
22altsep = None
23
24# Imports - make an error-generating swi object if the swi module is not
25# available (ie. we are not running on RISC OS Python)
26
27import os, stat, string
28
29try:
30    import swi
31except ImportError:
32    class _swi:
33        def swi(*a):
34            raise AttributeError, 'This function only available under RISC OS'
35        block= swi
36    swi= _swi()
37
38[_false, _true]= range(2)
39
40_roots= ['$', '&', '%', '@', '\\']
41
42
43# _allowMOSFSNames
44# After importing riscospath, set _allowMOSFSNames true if you want the module
45# to understand the "-SomeFS-" notation left over from the old BBC Master MOS,
46# as well as the standard "SomeFS:" notation. Set this to be fully backwards
47# compatible but remember that "-SomeFS-" can also be a perfectly valid file
48# name so care must be taken when splitting and joining paths.
49
50_allowMOSFSNames= _false
51
52
53## Path manipulation, RISC OS stylee.
54
55def _split(p):
56    """
57  split filing system name (including special field) and drive specifier from rest
58  of path. This is needed by many riscospath functions.
59  """
60    dash= _allowMOSFSNames and p[:1]=='-'
61    if dash:
62        q= string.find(p, '-', 1)+1
63    else:
64        if p[:1]==':':
65            q= 0
66        else:
67            q= string.find(p, ':')+1 # q= index of start of non-FS portion of path
68    s= string.find(p, '#')
69    if s==-1 or s>q:
70        s= q # find end of main FS name, not including special field
71    else:
72        for c in p[dash:s]:
73            if c not in string.ascii_letters:
74                q= 0
75                break # disallow invalid non-special-field characters in FS name
76    r= q
77    if p[q:q+1]==':':
78        r= string.find(p, '.', q+1)+1
79        if r==0:
80            r= len(p) # find end of drive name (if any) following FS name (if any)
81    return (p[:q], p[q:r], p[r:])
82
83
84def normcase(p):
85    """
86  Normalize the case of a pathname. This converts to lowercase as the native RISC
87  OS filesystems are case-insensitive. However, not all filesystems have to be,
88  and there's no simple way to find out what type an FS is argh.
89  """
90    return string.lower(p)
91
92
93def isabs(p):
94    """
95  Return whether a path is absolute. Under RISC OS, a file system specifier does
96  not make a path absolute, but a drive name or number does, and so does using the
97  symbol for root, URD, library, CSD or PSD. This means it is perfectly possible
98  to have an "absolute" URL dependent on the current working directory, and
99  equally you can have a "relative" URL that's on a completely different device to
100  the current one argh.
101  """
102    (fs, drive, path)= _split(p)
103    return drive!='' or path[:1] in _roots
104
105
106def join(a, *p):
107    """
108  Join path elements with the directory separator, replacing the entire path when
109  an absolute or FS-changing path part is found.
110  """
111    j= a
112    for b in p:
113        (fs, drive, path)= _split(b)
114        if j=='' or fs!='' or drive!='' or path[:1] in _roots:
115            j= b
116        elif j[-1]==':':
117            j= j+b
118        else:
119            j= j+'.'+b
120    return j
121
122
123def split(p):
124    """
125  Split a path in head (everything up to the last '.') and tail (the rest). FS
126  name must still be dealt with separately since special field may contain '.'.
127  """
128    (fs, drive, path)= _split(p)
129    q= string.rfind(path, '.')
130    if q!=-1:
131        return (fs+drive+path[:q], path[q+1:])
132    return ('', p)
133
134
135def splitext(p):
136    """
137  Split a path in root and extension. This assumes the 'using slash for dot and
138  dot for slash with foreign files' convention common in RISC OS is in force.
139  """
140    (tail, head)= split(p)
141    if '/' in head:
142        q= len(head)-string.rfind(head, '/')
143        return (p[:-q], p[-q:])
144    return (p, '')
145
146
147def splitdrive(p):
148    """
149  Split a pathname into a drive specification (including FS name) and the rest of
150  the path. The terminating dot of the drive name is included in the drive
151  specification.
152  """
153    (fs, drive, path)= _split(p)
154    return (fs+drive, p)
155
156
157def basename(p):
158    """
159  Return the tail (basename) part of a path.
160  """
161    return split(p)[1]
162
163
164def dirname(p):
165    """
166  Return the head (dirname) part of a path.
167  """
168    return split(p)[0]
169
170
171def commonprefix(m):
172    "Given a list of pathnames, returns the longest common leading component"
173    if not m: return ''
174    s1 = min(m)
175    s2 = max(m)
176    n = min(len(s1), len(s2))
177    for i in xrange(n):
178        if s1[i] != s2[i]:
179            return s1[:i]
180    return s1[:n]
181
182
183## File access functions. Why are we in os.path?
184
185def getsize(p):
186    """
187  Return the size of a file, reported by os.stat().
188  """
189    st= os.stat(p)
190    return st[stat.ST_SIZE]
191
192
193def getmtime(p):
194    """
195  Return the last modification time of a file, reported by os.stat().
196  """
197    st = os.stat(p)
198    return st[stat.ST_MTIME]
199
200getatime= getmtime
201
202
203# RISC OS-specific file access functions
204
205def exists(p):
206    """
207  Test whether a path exists.
208  """
209    try:
210        return swi.swi('OS_File', '5s;i', p)!=0
211    except swi.error:
212        return 0
213
214lexists = exists
215
216
217def isdir(p):
218    """
219  Is a path a directory? Includes image files.
220  """
221    try:
222        return swi.swi('OS_File', '5s;i', p) in [2, 3]
223    except swi.error:
224        return 0
225
226
227def isfile(p):
228    """
229  Test whether a path is a file, including image files.
230  """
231    try:
232        return swi.swi('OS_File', '5s;i', p) in [1, 3]
233    except swi.error:
234        return 0
235
236
237def islink(p):
238    """
239  RISC OS has no links or mounts.
240  """
241    return _false
242
243ismount= islink
244
245
246# Same-file testing.
247
248# samefile works on filename comparison since there is no ST_DEV and ST_INO is
249# not reliably unique (esp. directories). First it has to normalise the
250# pathnames, which it can do 'properly' using OS_FSControl since samefile can
251# assume it's running on RISC OS (unlike normpath).
252
253def samefile(fa, fb):
254    """
255  Test whether two pathnames reference the same actual file.
256  """
257    l= 512
258    b= swi.block(l)
259    swi.swi('OS_FSControl', 'isb..i', 37, fa, b, l)
260    fa= b.ctrlstring()
261    swi.swi('OS_FSControl', 'isb..i', 37, fb, b, l)
262    fb= b.ctrlstring()
263    return fa==fb
264
265
266def sameopenfile(a, b):
267    """
268  Test whether two open file objects reference the same file.
269  """
270    return os.fstat(a)[stat.ST_INO]==os.fstat(b)[stat.ST_INO]
271
272
273## Path canonicalisation
274
275# 'user directory' is taken as meaning the User Root Directory, which is in
276# practice never used, for anything.
277
278def expanduser(p):
279    (fs, drive, path)= _split(p)
280    l= 512
281    b= swi.block(l)
282
283    if path[:1]!='@':
284        return p
285    if fs=='':
286        fsno= swi.swi('OS_Args', '00;i')
287        swi.swi('OS_FSControl', 'iibi', 33, fsno, b, l)
288        fsname= b.ctrlstring()
289    else:
290        if fs[:1]=='-':
291            fsname= fs[1:-1]
292        else:
293            fsname= fs[:-1]
294        fsname= string.split(fsname, '#', 1)[0] # remove special field from fs
295    x= swi.swi('OS_FSControl', 'ib2s.i;.....i', 54, b, fsname, l)
296    if x<l:
297        urd= b.tostring(0, l-x-1)
298    else: # no URD! try CSD
299        x= swi.swi('OS_FSControl', 'ib0s.i;.....i', 54, b, fsname, l)
300        if x<l:
301            urd= b.tostring(0, l-x-1)
302        else: # no CSD! use root
303            urd= '$'
304    return fsname+':'+urd+path[1:]
305
306# Environment variables are in angle brackets.
307
308def expandvars(p):
309    """
310  Expand environment variables using OS_GSTrans.
311  """
312    l= 512
313    b= swi.block(l)
314    return b.tostring(0, swi.swi('OS_GSTrans', 'sbi;..i', p, b, l))
315
316
317# Return an absolute path. RISC OS' osfscontrol_canonicalise_path does this among others
318abspath = os.expand
319
320
321# realpath is a no-op on systems without islink support
322realpath = abspath
323
324
325# Normalize a path. Only special path element under RISC OS is "^" for "..".
326
327def normpath(p):
328    """
329  Normalize path, eliminating up-directory ^s.
330  """
331    (fs, drive, path)= _split(p)
332    rhs= ''
333    ups= 0
334    while path!='':
335        (path, el)= split(path)
336        if el=='^':
337            ups= ups+1
338        else:
339            if ups>0:
340                ups= ups-1
341            else:
342                if rhs=='':
343                    rhs= el
344                else:
345                    rhs= el+'.'+rhs
346    while ups>0:
347        ups= ups-1
348        rhs= '^.'+rhs
349    return fs+drive+rhs
350
351
352# Directory tree walk.
353# Independent of host system. Why am I in os.path?
354
355def walk(top, func, arg):
356    """Directory tree walk with callback function.
357
358    For each directory in the directory tree rooted at top (including top
359    itself, but excluding '.' and '..'), call func(arg, dirname, fnames).
360    dirname is the name of the directory, and fnames a list of the names of
361    the files and subdirectories in dirname (excluding '.' and '..').  func
362    may modify the fnames list in-place (e.g. via del or slice assignment),
363    and walk will only recurse into the subdirectories whose names remain in
364    fnames; this can be used to implement a filter, or to impose a specific
365    order of visiting.  No semantics are defined for, or required of, arg,
366    beyond that arg is always passed to func.  It can be used, e.g., to pass
367    a filename pattern, or a mutable object designed to accumulate
368    statistics.  Passing None for arg is common."""
369
370    try:
371        names= os.listdir(top)
372    except os.error:
373        return
374    func(arg, top, names)
375    for name in names:
376        name= join(top, name)
377        if isdir(name) and not islink(name):
378            walk(name, func, arg)
379