/src/wrappers/common/library/wrapper_factory.e

 1note
 2   copyright:
 3      "[
 4               Copyright (C) 2008-2017: Paolo Redaelli
 5
 6               This library is free software; you can redistribute it and/or
 7               modify it under the terms of the GNU Lesser General Public License
 8               as published by the Free Software Foundation; either version 2.1 of
 9               the License, or (at your option) any later version.
10
11               This library is distributed in the hope that it will be useful, but
12               WITHOUT ANY WARRANTY; without even the implied warranty of
13               MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
14               Lesser General Public License for more details.
15
16               You should have received a copy of the GNU Lesser General Public
17               License along with this library; if not, write to the Free Software
18               Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
19               02110-1301 USA
20         ]"
21deferred class WRAPPER_FACTORY[ITEM_ -> WRAPPER]
22   -- A wrapper factory returns the "fittest" wrapper object given a
23   -- pointer to a wrapped "thing".
24   -- A wrapper factory would implement the typing policy described in the
25   -- wrapper library documentation.  In fact some libraries implement their
26   -- own type system like GObject, while other having smaller scopes will
27   -- describe the types of each returned pointer, sometime being polymorphic.
28   -- If the developer needs to create wrappers of several different types and
29   -- those types are pre-defined, known during the development of the
30   -- wrapper, for example when the actual returned type is explained in the
31   -- documentation of the library it is sometimes better to use (as a client)
32   -- one of its expanded variant, i.e.  G_OBJECT_EXPANDED_FACTORY.
33
34inherit
35   WRAPPER_HANDLER
36
37feature {WRAPPER, WRAPPER_HANDLER} -- Implementation
38   wrapper (a_pointer: POINTER): ITEM_
39         -- The wrapper for `a_pointer'. It could be newly created or
40         -- retrieved from a cache, a dictionary, from the underlying
41         -- object, depending on the implementation.
42         -- See also wrapper_or_void: when `a_pointer' is the
43         -- default pointer (known as NULL in C) Result will be Void.
44      require
45         pointer_not_null: a_pointer.is_not_null
46      deferred
47      ensure
48         non_void: Result /= Void
49         correct: Result.handle = a_pointer
50      end
51
52   wrapper_or_void (a_pointer: POINTER): ITEM_
53         -- A wrapper for `a_pointer' or Void if `a_pointer'
54         -- default_pointer (NULL in C). A commodity feature to
55         -- replace the following code snippet:
56         -- my_gobject: A_WRAPPER
57         -- local p: POINTER
58         -- do
59         --   p := get_foo(handle)
60         --   if p.is_not_null then
61         --     Result := factory.wrapper(p)
62         --   end
63         -- end
64         -- with
65         -- my_gobject: A_G_OBJECT_HEIR
66         --   do
67         --     Result := factory.wrapper_or_void(get_foo(handle))
68         --   end
69      do
70         if a_pointer.is_not_null then
71            Result := wrapper(a_pointer)
72         end
73      ensure
74         null_pointer_returns_void: a_pointer.is_null implies Result = Void
75         correct: a_pointer.is_not_null implies Result /= Void and then Result.handle = a_pointer
76      end
77
78end -- class WRAPPER_FACTORY