0024716: OSD_Path - remove excessive validity checks and allow non-ascii strings
[occt.git] / src / OSD / OSD_Path.cdl
CommitLineData
b311480e 1-- Created on: 1992-02-18
2-- Created by: Stephan GARNAUD (ARM)
3-- Copyright (c) 1992-1999 Matra Datavision
973c2be1 4-- Copyright (c) 1999-2014 OPEN CASCADE SAS
b311480e 5--
973c2be1 6-- This file is part of Open CASCADE Technology software library.
b311480e 7--
d5f74e42 8-- This library is free software; you can redistribute it and/or modify it under
9-- the terms of the GNU Lesser General Public License version 2.1 as published
973c2be1 10-- by the Free Software Foundation, with special exception defined in the file
11-- OCCT_LGPL_EXCEPTION.txt. Consult the file LICENSE_LGPL_21.txt included in OCCT
12-- distribution for complete text of the license and disclaimer of any warranty.
b311480e 13--
973c2be1 14-- Alternatively, this file may be used under the terms of Open CASCADE
15-- commercial license or contractual agreement.
7fd59977 16
7fd59977 17-- Modified by LD on Dec 15 1995
18-- Methode SetSystemName added
19
20
21
22class Path from OSD
23
24 --Purpose: Manage a system independent path.
25 -- It is possible to give this object a complete
26 -- path including VMS possibilities such as
27 -- Node"Username Password"::Disk:[path1.path2]
28 -- This system dependent syntax is avoided with the
29 -- SetValues method.
30
31 uses Environment, SysType, Error, AsciiString from TCollection
32raises ConstructionError, NullObject, OSDError, NumericError, ProgramError
33
34 is
35 Create returns Path;
36 ---Purpose: Creates a Path object initialized to an empty string.
37 -- i.e. current directory.
38 ---Level: Public
39
40 Create (aDependentName : AsciiString; aSysType : SysType=OSD_Default) returns Path
41 ---Purpose: Creates a Path object initialized by dependant path.
42 -- ex: OSD_Path me ("/usr/bin/myprog.sh",OSD_UnixBSD);
43 --
44 -- OSD_Path me ("sys$common:[syslib]cc.exe",OSD_OSF) will
45 -- raise a ProgramError due to invalid name for this
46 -- type of system.
47 -- In order to avoid a 'ProgramError' , use IsValid(...)
48 -- to ensure you the validity of <aDependentName>.
49 -- Raises ConstructionError when the path is either null
50 -- or contains characters not in range of ' '...'~'.
51 ---Level: Public
52 raises ConstructionError;
53
54 Create (aNode,aUsername,aPassword,aDisk,aTrek,aName,anExtension: in AsciiString) returns Path;
55 ---Purpose: Initializes a system independent path.
56 -- By default , the Path conversion will be assumed using
57 -- currently used system.
58 -- A special syntax is used to specify a "aTrek" in an
59 -- independent manner :
60 -- a "|" represents directory separator
61 -- a "^" means directory above (father)
62 -- examples:
63 -- "|usr|bin" - On UNIX -> "/usr/bin"
64 -- - On VMS -> "[usr.bin]"
65 -- - On MSDOS-> "\usr\bin"
66 -- - On MacOs-> ": usr : bin"
67 --
68 -- "^|rep" - On UNIX -> "../rep"
69 -- - On VMS -> "[-.rep]"
70 -- - On MSDOS -> "..\rep"
71 -- - On MacOS-> ":: rep"
72 --
73 -- "subdir|" - On UNIX -> "subdir/"
74 -- - On VMS -> "[.subdir.]"
75
76 ---Example: Create("amelix", "sga", "toto", "dk$22", "|bin|usr",myFile,"")
77 -- will give internaly
78 -- On MS-DOS/OS2 \DK22\BIN\USR\MYFILE
79 -- On UNIX sga"toto"@amelix:/dk22/bin/usr/myFile
80 -- On VMS AMELIX"SGA TOTO"::DK$22:[BIN.USR]MYFILE
81 -- On MacOs dk$22 : bin : usr : myFile
82 --
83 -- As you can see, "aDisk" is used under UNIX.
84 -- This is possible when one 'mounts' a directory from another system.
85 -- However, the syntax of <aDisk> can slightly change on several systems.
86 -- So "DK$22" on VMS becomes "dk22" on UNIX and Windows NT.
87 -- for instance when you mount a VMS directory under UNIX this gives:
88 --
89 -- lucide:/dk22/mydirectory mounted on /vms/mydirectory
90 ---Level: Public
91
92
93 Values (me ; aNode,aUsername,aPassword,aDisk,aTrek,aName,anExtension :
94 out AsciiString) is static;
95 ---Purpose: Gets each component of a path.
96 ---Level: Public
97
98 SetValues (me : in out;
99 aNode,aUsername,aPassword,aDisk,aTrek,aName,anExtension : in AsciiString)
100 ---Purpose: Sets each component of a path.
101 ---Level: Public
102 raises ConstructionError is static;
103
104 SystemName(me ; FullName : out AsciiString ; aType : SysType=OSD_Default)
105 is static;
106 ---Purpose: Returns system dependent path
107 -- <aType> is one among Unix,VMS ...
108 -- This function is not private because you may need to
109 -- display system dependent path on a front-end.
110 -- It can be useful when communicating with another system.
111 -- For instance when you want to communicate between VMS and Unix
112 -- to transfer files, or to do a remote procedure call
113 -- using files.
114 -- example :
115 -- OSD_Path myPath ("sparc4", "sga", "secret_passwd",
116 -- "$5$dkb100","|users|examples");
117 -- Internal ( Dependent_name );
118 -- On UNIX sga"secret_passwd"@sparc4:/users/examples
119 -- On VMS sparc4"sga secret_passwd"::$5$dkb100:[users.examples]
120 ---Level: Public
121
122-- SetSystemName(me : in out ; aDependentName : AsciiString; aSysType : SysType=OSD_Default)
123 ---Purpose: Sets each component of a Path giving its system dependent name.
124 ---Level: Public
125-- raises ConstructionError is static;
126
127 ExpandedName(me : in out; aName : out AsciiString)
128 is static;
129 ---Purpose: Returns system dependent path resolving logical symbols.
130
30d33e71 131 IsValid (myclass ; theDependentName : AsciiString; theSysType : SysType = OSD_Default)
132 returns Boolean;
133 ---Purpose: Returns TRUE if <theDependentName> is valid for this SysType.
7fd59977 134 ---Level: Public
135
7fd59977 136 UpTrek (me : in out) is static;
137 ---Purpose: This removes the last directory name in <aTrek>
138 -- and returns result.
139 -- ex: me = "|usr|bin|todo.sh"
140 -- me.UpTrek() gives me = "|usr|todo.sh"
141 -- if <me> contains "|", me.UpTrek() will give again "|"
142 -- without any error.
143 ---Level: Public
144
145 DownTrek(me : in out; aName : AsciiString) is static;
146 ---Purpose: This appends a directory name into the Trek.
147 -- ex: me = "|usr|todo.sh"
148 -- me.DownTrek("bin") gives me = "|usr|bin|todo.sh".
149 ---Level: Public
150
151 TrekLength(me) returns Integer is static;
152 ---Purpose: Returns number of components in Trek of <me>.
153 -- ex: me = "|usr|sys|etc|bin"
154 -- me.TrekLength() returns 4.
155 ---Level: Public
156
157 RemoveATrek(me : in out; where : Integer)
158 ---Purpose: This removes a component of Trek in <me> at position <where>.
159 -- The first component of Trek is numbered 1.
160 -- ex: me = "|usr|bin|"
161 -- me.RemoveATrek(1) gives me = "|bin|"
162 -- To avoid a 'NumericError' because of a bad <where>, use
163 -- TrekLength() to know number of components of Trek in <me>.
164 ---Level: Public
165 raises NumericError is static;
166
167 RemoveATrek(me : in out; aName : AsciiString) is static;
168 ---Purpose: This removes <aName> from <me> in Trek.
169 -- No error is raised if <aName> is not in <me>.
170 -- ex: me = "|usr|sys|etc|doc"
171 -- me.RemoveATrek("sys") gives me = "|usr|etc|doc".
172 ---Level: Public
173
174 TrekValue(me ; where : Integer) returns AsciiString
175 ---Purpose: Returns component of Trek in <me> at position <where>.
176 -- ex: me = "|usr|bin|sys|"
177 -- me.TrekValue(2) returns "bin"
178 raises NumericError is static;
179 ---Level: Public
180
181 InsertATrek(me : in out; aName : AsciiString; where : Integer)
182 ---Purpose: This inserts <aName> at position <where> into Trek of <me>.
183 -- ex: me = "|usr|etc|"
184 -- me.InsertATrek("sys",2) gives me = "|usr|sys|etc"
185 raises NumericError is static;
186 ---Level: Public
187
188 Node (me) returns AsciiString is static;
189 ---Purpose: Returns Node of <me>.
190 ---Level: Public
191
192 UserName (me) returns AsciiString is static;
193 ---Purpose: Returns UserName of <me>.
194 ---Level: Public
195
196 Password (me) returns AsciiString is static;
197 ---Purpose: Returns Password of <me>.
198 ---Level: Public
199
200 Disk(me) returns AsciiString is static;
201 ---Purpose: Returns Disk of <me>.
202 ---Level: Public
203
204 Trek(me) returns AsciiString is static;
205 ---Purpose: Returns Trek of <me>.
206 ---Level: Public
207
208 Name (me) returns AsciiString is static;
209 ---Purpose: Returns file name of <me>.
210 -- If <me> hasn't been initialized, it returns an empty AsciiString.
211 ---Level: Public
212
213 Extension (me) returns AsciiString is static;
214 ---Purpose: Returns my extension name.
215 -- This returns an empty string if path contains no file name.
216 ---Level: Public
217
218 SetNode (me : in out; aName : AsciiString) is static;
219 ---Purpose: Sets Node of <me>.
220 ---Level: Public
221
222 SetUserName (me : in out; aName : AsciiString) is static;
223 ---Purpose: Sets UserName of <me>.
224 ---Level: Public
225
226 SetPassword (me : in out; aName : AsciiString) is static;
227 ---Purpose: Sets Password of <me>.
228 ---Level: Public
229
230 SetDisk(me : in out; aName : AsciiString) is static;
231 ---Purpose: Sets Disk of <me>.
232 ---Level: Public
233
234 SetTrek(me : in out; aName : AsciiString) is static;
235 ---Purpose: Sets Trek of <me>.
236 ---Level: Public
237
238 SetName (me : in out; aName : AsciiString) is static;
239 ---Purpose: Sets file name of <me>.
240 -- If <me> hasn't been initialized, it returns an empty AsciiString.
241 ---Level: Public
242
243 SetExtension (me : in out; aName : AsciiString) is static;
244 ---Purpose: Sets my extension name.
245 ---Level: Public
246
247 LocateExecFile(me : in out; aPath: out Path from OSD )
248 returns Boolean from Standard ;
249 ---Purpose: Finds the full path of an executable file, like the
250 -- "which" Unix utility. Uses the path environment variable.
251 -- Returns False if executable file not found.
252 ---Level: Public
253
254 RelativePath(myclass; DirPath, AbsFilePath : AsciiString from TCollection)
255 returns AsciiString from TCollection ;
256 ---Purpose: Returns the relative file path between the absolute directory
257 --- path <DirPath> and the absolute file path <AbsFilePath>.
258 --- If <DirPath> starts with "/", pathes are handled as
259 --- on Unix, if it starts with a letter followed by ":", as on
260 --- WNT. In particular on WNT directory names are not key sensitive.
261 --- If handling fails, an empty string is returned.
262 ---Level: Public
263
264
265 AbsolutePath(myclass; DirPath, RelFilePath : AsciiString from TCollection)
266 returns AsciiString from TCollection ;
267 ---Purpose: Returns the absolute file path from the absolute directory path
268 --- <DirPath> and the relative file path returned by RelativePath().
269 --- If the RelFilePath is an absolute path, it is returned and the
270 --- directory path is ignored.
271 --- If handling fails, an empty string is returned.
272
273
274 fields
275 myNode : AsciiString;
276 myUserName : AsciiString;
277 myPassword : AsciiString;
278 myDisk : AsciiString;
279 myTrek : AsciiString;
280 myName : AsciiString;
281 myExtension : AsciiString;
282 myUNCFlag : Boolean ;
30d33e71 283 mySysDep : SysType; -- To allow system specific use
7fd59977 284end Path from OSD;