1 /*
2 
3 Boost Software License - Version 1.0 - August 17th, 2003
4 
5 Permission is hereby granted, free of charge, to any person or organization
6 obtaining a copy of the software and accompanying documentation covered by
7 this license (the "Software") to use, reproduce, display, distribute,
8 execute, and transmit the Software, and to prepare derivative works of the
9 Software, and to permit third-parties to whom the Software is furnished to
10 do so, all subject to the following:
11 
12 The copyright notices in the Software and this entire statement, including
13 the above license grant, this restriction and the following disclaimer,
14 must be included in all copies of the Software, in whole or in part, and
15 all derivative works of the Software, unless such copies or derivative
16 works are solely in the form of machine-executable object code generated by
17 a source language processor.
18 
19 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
20 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
21 FITNESS FOR A PARTICULAR PURPOSE, TITLE AND NON-INFRINGEMENT. IN NO EVENT
22 SHALL THE COPYRIGHT HOLDERS OR ANYONE DISTRIBUTING THE SOFTWARE BE LIABLE
23 FOR ANY DAMAGES OR OTHER LIABILITY, WHETHER IN CONTRACT, TORT OR OTHERWISE,
24 ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
25 DEALINGS IN THE SOFTWARE.
26 
27 */
28 module derelict.util.exception;
29 
30 /++
31  Base class for all exceptions thrown by Derelict packages.
32 +/
33 class DerelictException : Exception {
34     public this(string msg, size_t line = __LINE__, string file = __FILE__) {
35         super(msg, file, line, null);
36     }
37 }
38 
39 /++
40  Helper struct to facilitate throwing a single SharedLibException after failing
41  to load a library using multiple names.
42 +/
43 private struct FailedSharedLib {
44     string name;
45     string reason;
46 }
47 
48 /++
49  This exception is thrown when a shared library cannot be loaded
50  because it is either missing or not on the system path.
51 +/
52 class SharedLibLoadException : DerelictException
53 {
54     private string _sharedLibName;
55 
56     public {
57         static void throwNew(string[] libNames, string[] reasons, size_t line = __LINE__, string file = __FILE__) {
58             string msg = "Failed to load one or more shared libraries:";
59             foreach(i, n; libNames) {
60                 msg ~= "\n\t" ~ n ~ " - ";
61                 if(i < reasons.length)
62                     msg ~= reasons[i];
63                 else
64                     msg ~= "Unknown";
65             }
66             throw new SharedLibLoadException(msg, line, file);
67         }
68 
69         this(string msg, size_t line = __LINE__, string file = __FILE__) {
70             super(msg, line, file);
71             _sharedLibName = "";
72         }
73 
74         this(string msg, string sharedLibName, size_t line = __LINE__, string file = __FILE__) {
75             super(msg, line, file);
76             _sharedLibName = sharedLibName;
77         }
78 
79         string sharedLibName() {
80             return _sharedLibName;
81         }
82     }
83 }
84 
85 /++
86  This exception is thrown when a symbol cannot be loaded from a shared library,
87  either because it does not exist in the library or because the library is corrupt.
88 +/
89 class SymbolLoadException : DerelictException
90 {
91     private string _symbolName;
92 
93     public {
94         this(string msg, size_t line = __LINE__, string file = __FILE__) {
95             super(msg, line, file);
96         }
97 
98         this(string sharedLibName, string symbolName, size_t line = __LINE__, string file = __FILE__) {
99             super("Failed to load symbol " ~ symbolName ~ " from shared library " ~ sharedLibName, line, file);
100             _symbolName = symbolName;
101         }
102 
103         string symbolName() {
104             return _symbolName;
105         }
106     }
107 }
108 
109 /++
110  The return type of the MissingSymbolCallbackFunc/Dg.
111 +/
112 enum ShouldThrow {
113     No,
114     Yes
115 }
116 
117 /++
118  The MissingSymbolCallback allows the user to prevent the throwing of SymbolLoadExceptions.
119 
120  By default, a SymbolLoadException is thrown when a symbol cannot be found in a shared
121  library. Assigning a MissingSymbolCallback to a loader allows the application to override
122  this behavior. If the missing symbol in question can be ignored, the callback should
123  return ShouldThrow.No to prevent the exception from being thrown. Otherwise, the
124  return value should be ShouldThrow.Yes. This is useful to allow a binding implemented
125  for version N.N of a library to load older or newer versions that may be missing
126  functions the loader expects to find, provided of course that the app does not need
127  to use those functions.
128 +/
129 alias MissingSymbolCallbackFunc = ShouldThrow function(string symbolName);
130 /// Ditto
131 alias MissingSymbolCallbackDg = ShouldThrow delegate(string symbolName);
132 
133 /// Convenient alias to use as a return value.
134 alias MissingSymbolCallback = MissingSymbolCallbackDg;