[QWK] Proposal: paths notation

Wed May 7 11:29:00 BST 2003

Proposal: More generic paths notation and handling for non-unix qt and kde

Updated versions of this document will be published at: 
http://www.iidea.pl/~js/qkw/code/paths-proposal.txt

Jaroslaw Staniek, js at iidea.pl
2003-05-07

I. Initial remarks:
Proposed solutions do not affect existing kde/unix and qt/unix source code
or behaviour. No changes are required to sources except for porting
requirements.
Binary and source compatibility shouldn't be broken for non-win32 targets.

II. Problems:
On win32 there is important differences from "normal" operating systems: 

1. We have drive letters explicity noted as <letter>:\ prefix for absolute 
paths. These paths do not starts wiht "/", while in many situations existing 
unix code depends on that.

2. Directories like "D:\" are in fact not real subdirectories of "/" root 
directory or something like that, because here we even do not have such root 
directory. Hence, we can't traverse through dirs like this:

D:\ > cd ..\C:\mydir

Although, for sure, some dir search algorithms depends on that it works and
unix programmers shouldn't never think about this issue. So we must deliver
solution for this too.

3. Most elementary issue is that we have "\" instead of "/" on win32. It is
not a big problem since Qt/win32 automatically converts "/" to "\". But it
_is_ a problem when we want to:
- store paths names inside config files or documents created by KDE apps, 
reuse these configs, exchange paths inside networks, integration

4. Qt has QFile::setEncodingFunction() method. But surprisingly:
- it is only for controling non-latin characters encoding, while it isn't
used 
for paths notation unification
- it is not used inside places like in 

QPixmap::QPixmap( const QString & fileName, ...)
QImage::QImage( const QString & fileName, ...)

and most notable:
QFileInfo::QFileInfo(  const QString & file )
QDir::QDir( const QString & path, ...)

while it is expected that these functions can properly encode paths names 
and will load files.

III. Solution for notation:

My proposal is to map win32-specific paths to unix-friendly format. The
method would be this:

a) convert all paths names to lowercase
b) map "\" to "/"
c) map <drive-letter>: to <drive-letter>| , (drive letter always written in 
lowercase)

This allows us to fix all the problems described in II.
Example mappings:

"C:\Program Files" -> "/c/program files"
"D:\kde\lib" -> "/d/kde/lib"

Note : I also thought about "/c|/program files" (use of "|") but above
notation 
is convenient, because do not require allocating more space dirung string 
conversions, so "in place" convertions can be performed easily. Paths with
"|" are also inconvenient to write since we must to write path with
quotation marks or "|" with escape "\" character. 
Note: use of "|" is at least known from netscape behaviour on win32, when we
e.g. enter C:\ in a location text box.

IV. Implementation

1. First solution is to introduce encode and decode functions:
QFile::EncoderFn and QFile::DecoderFn that will not only handle non-latin 
characters but also convert paths notation. 

Then we use QFile::setEncodingFunction( EncoderFn f ) and 
QFile::setDecodingFunction( DecoderFn f ) somewhere in KDE program 
initialization step. But it is not enough because of issue II.4.

I use this approach in current kdelibs win32 port and I am not happy with
this.
I am required to put additional encoding call in places like that:

QFileInfo info( QFile::encodeName(fname) );
                 ^^^^^^^^^^^^^^^

There are many places there I had to put it. More, QFile::encodeName is just 
empty call on non-win32, at least today, so it seems to be redundant in the
code 
for many free software programmers.

2. How to cleanly solve this inconvenience?

Second solution:
Only method I know is to patch qt for win32. If it would be 
possible I would like to have there another pair of functions similar to 
QFile::set{Encoding|Decoding}Function():

static QFile::setMapToGenericPathFunction( MapToGenericPathFn f );
static QFile::setMapFromGenericPathFunction( MapFromGenericPathFn f );
while MapToGenericPathFn has signature: 
 QString ( const QCString & ) -- like DecoderFn
and MapFromGenericPathFn has signature: 
 QCString ( const QString & ) -- like EncoderFn

These function should be called in every such places like constructors
mentioned 
in II.4.

Notes:

By default, these functions should be empty to ensure compatibility for 
existing Qt code. Once QFile::setMap{To|From}GenericPathFunction() will be 
called in program initialization, new expected semantic of paths notation
will 
be used.

The cost of introducing this solution inside Qt is simply one check for 
existence given Map{To|From}GenericPathFn functions. If any ot the two
exists, 
it'll be called _once_ before accessing to a file.

Mapped paths can be also cached inside e.g. QDir instance for efficency.

Note that there can also be in Qt possibility for having
QDir::entryInfoList(..)
function that will not use paths mapping for better afficency. Other issue
is 
that KDElibs has some outside-qt implementations for file searching, etc. so
it 
is not an efficency problem for KDE.

Benefits are that we won't need to again-and-again fix existing code with 
encode() and decode() wrapper functions and of course, code can remains
clear 
what is also IMO one of the reasons for using Qt for our software
development.

V. Changes to KDE libs

0. I haven't done any commits to kde cvs, related to this proposal yet.

1. KPath class introduced for kdelibs/kdecore. It takes some functionality
from 
KStandardDirs and KLocale to more generic and usable level. See 
http://www.iidea.pl/~js/qkw/code/ for sources.
Use of KPath for unix kde apps will require users to do kde upgrade. So for
this 
target, use of KPath IMO should be temporary limited to win32 target, 
maybe waiting for KDE4 ;) Probably #ifdefs and #defines will be introduced
to 
avoid linking against libkpath in unix. 
Temporary, I use libkpath on my unix KDE, but is it a good solution?

VI. References
Older disscussion on paths:

http://www.iidea.pl/~js/qkw/NOTES.paths

-- 
regards,
  Jaroslaw Staniek / OpenOffice Poland
  QT-KDE-Wrapper project: http://iidea.pl/~js/qkw