0109373551405a6e6f47dbb0b9fa110b5e49dd47
[occt.git] / src / OSD / OSD_Path.cdl
1 -- Created on: 1992-02-18
2 -- Created by: Stephan GARNAUD (ARM)
3 -- Copyright (c) 1992-1999 Matra Datavision
4 -- Copyright (c) 1999-2014 OPEN CASCADE SAS
5 --
6 -- This file is part of Open CASCADE Technology software library.
7 --
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
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.
13 --
14 -- Alternatively, this file may be used under the terms of Open CASCADE
15 -- commercial license or contractual agreement.
16
17 -- Modified by LD on Dec 15 1995
18 -- Methode SetSystemName added
19
20
21
22 class 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
32 raises 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
131   IsValid (me ; aDependentName : AsciiString; aSysType : SysType=OSD_Default) 
132     returns Boolean is static;
133     ---Purpose: Returns TRUE if <aDependentName> is valid for this SysType.
134     ---Level: Public
135
136
137   UpTrek (me : in out) is static;
138    ---Purpose: This removes the last directory name in <aTrek>
139    --          and returns result.
140    --          ex:  me = "|usr|bin|todo.sh" 
141    --               me.UpTrek() gives me = "|usr|todo.sh"
142    --          if <me> contains "|", me.UpTrek() will give again "|"
143    --          without any error.
144    ---Level: Public
145
146   DownTrek(me : in out; aName : AsciiString) is static;
147    ---Purpose: This appends a directory name into the Trek.
148    --          ex: me = "|usr|todo.sh"
149    --              me.DownTrek("bin") gives me = "|usr|bin|todo.sh".
150    ---Level: Public
151
152   TrekLength(me) returns Integer is static;
153    ---Purpose: Returns number of components in Trek of <me>.
154    --          ex: me = "|usr|sys|etc|bin"
155    --              me.TrekLength() returns 4.
156    ---Level: Public
157
158   RemoveATrek(me : in out; where : Integer)
159    ---Purpose: This removes a component of Trek in <me> at position <where>.
160    --          The first component of Trek is numbered 1.
161    --          ex:   me = "|usr|bin|"
162    --                me.RemoveATrek(1) gives me = "|bin|"
163    --          To avoid a 'NumericError' because of a bad <where>, use
164    --          TrekLength() to know number of components of Trek in <me>.
165    ---Level: Public
166    raises NumericError is static;
167
168   RemoveATrek(me : in out; aName : AsciiString) is static;
169    ---Purpose: This removes <aName> from <me> in Trek.
170    --          No error is raised if <aName> is not in <me>.
171    --          ex:  me = "|usr|sys|etc|doc"
172    --               me.RemoveATrek("sys") gives me = "|usr|etc|doc".
173    ---Level: Public
174
175   TrekValue(me ; where : Integer) returns AsciiString
176    ---Purpose: Returns component of Trek in <me> at position <where>.
177    --          ex:  me = "|usr|bin|sys|"
178    --               me.TrekValue(2) returns "bin"
179    raises NumericError is static;
180    ---Level: Public
181
182   InsertATrek(me : in out; aName : AsciiString; where : Integer)
183    ---Purpose: This inserts <aName> at position <where> into Trek of <me>.
184    --          ex:  me = "|usr|etc|"
185    --               me.InsertATrek("sys",2) gives me = "|usr|sys|etc" 
186    raises NumericError is static;
187    ---Level: Public
188
189   Node (me) returns AsciiString is static;
190    ---Purpose: Returns Node of <me>.
191    ---Level: Public
192
193   UserName (me) returns AsciiString is static;
194    ---Purpose: Returns UserName of <me>.
195    ---Level: Public
196
197   Password (me) returns AsciiString is static;
198    ---Purpose: Returns Password of <me>.
199    ---Level: Public
200
201   Disk(me) returns AsciiString is static;
202    ---Purpose: Returns Disk of <me>.
203    ---Level: Public
204
205   Trek(me) returns AsciiString is static;
206    ---Purpose: Returns Trek of <me>.
207    ---Level: Public
208
209   Name (me) returns AsciiString is static;
210    ---Purpose: Returns file name of <me>.
211      --          If <me> hasn't been initialized, it returns an empty AsciiString.
212    ---Level: Public
213                                              
214   Extension (me) returns AsciiString is static;
215    ---Purpose: Returns my extension name.
216      --          This returns an empty string if path contains no file name.
217    ---Level: Public
218
219   SetNode (me : in out; aName : AsciiString) is static;
220    ---Purpose: Sets Node of <me>.
221    ---Level: Public
222
223   SetUserName (me : in out; aName : AsciiString) is static;
224    ---Purpose: Sets UserName of <me>.
225    ---Level: Public
226
227   SetPassword (me : in out; aName : AsciiString) is static;
228    ---Purpose: Sets Password of <me>.
229    ---Level: Public
230
231   SetDisk(me : in out; aName : AsciiString) is static;
232    ---Purpose: Sets Disk of <me>.
233    ---Level: Public
234
235   SetTrek(me : in out; aName : AsciiString) is static;
236    ---Purpose: Sets Trek of <me>.
237    ---Level: Public
238
239   SetName (me : in out; aName : AsciiString) is static;
240    ---Purpose: Sets file name of <me>.
241    --          If <me> hasn't been initialized, it returns an empty AsciiString.
242    ---Level: Public
243                                              
244   SetExtension (me : in out; aName : AsciiString) is static;
245    ---Purpose: Sets my extension name.
246    ---Level: Public
247
248   LocateExecFile(me : in out; aPath: out Path from OSD )
249   returns Boolean from Standard ;
250    ---Purpose: Finds the full path of an executable file, like the
251    --          "which" Unix utility. Uses the path environment variable.
252    --          Returns False if executable file not found.
253    ---Level: Public    
254         
255   RelativePath(myclass; DirPath, AbsFilePath : AsciiString from TCollection)
256   returns AsciiString from TCollection ;
257    ---Purpose: Returns the relative file path between the absolute directory 
258    ---         path <DirPath>  and the absolute file path <AbsFilePath>.
259    ---         If <DirPath> starts with "/", pathes are handled as
260    ---         on Unix, if it starts with a letter followed by ":", as on
261    ---         WNT. In particular on WNT directory names are not key sensitive.
262    ---         If handling fails, an empty string is returned.
263    ---Level: Public
264
265
266   AbsolutePath(myclass; DirPath, RelFilePath : AsciiString from TCollection) 
267   returns AsciiString from TCollection ;
268    ---Purpose: Returns the absolute file path from the absolute directory path
269    ---         <DirPath> and the relative file path returned by RelativePath().
270    ---         If the RelFilePath is an absolute path, it is returned and the
271    ---         directory path is ignored.
272    ---         If handling fails, an empty string is returned.
273
274
275  fields
276   myNode      : AsciiString;
277   myUserName  : AsciiString;
278   myPassword  : AsciiString;
279   myDisk      : AsciiString;
280   myTrek      : AsciiString;
281   myName      : AsciiString;
282   myExtension : AsciiString;
283   myUNCFlag   : Boolean ;
284   SysDep      : SysType;  -- To allow system specific use
285 end Path from OSD;