Many changes
[perl-ctypes:shlomifs-perl-ctypes.git] / lib / Ctypes / Type.pm
1 package Ctypes::Type;
2 # always loaded and all c types are exported.
3 use strict;
4 use warnings;
5 use Carp;
6 require Exporter;
7 our @ISA = qw|Exporter|;
8 our @EXPORT_OK = qw|&_types &allow_overflow_all|;
9 our $VERSION = 0.002;
10 use constant USE_PERLTYPES => 1; # so far use only perl pack-style types, 
11                                  # not the full python ctypes types
12 use Ctypes;
13 use Ctypes::Type::Simple;
14 use Ctypes::Type::Array;
15 use Ctypes::Type::Pointer;
16 use Ctypes::Type::Struct;
17 use Ctypes::Type::Union;
18 my $Debug = 0;
19
20 =head1 NAME
21
22 Ctypes::Type - Abstract base class for Ctypes Data Type objects
23
24 =cut
25
26 our $_perltypes = 
27
28   v =>  "c_void",
29   c =>  "c_byte",
30   C =>  "c_char",
31   s =>  "c_short",
32   S =>  "c_ushort",
33   i =>  "c_int",
34   I =>  "c_uint",
35   l =>  "c_long",
36   L =>  "c_ulong",
37   f =>  "c_float",
38   d =>  "c_double",
39   D =>  "c_longdouble",
40   p =>  "c_void_p",
41 };
42
43 our $_pytypes = 
44
45   s =>  "c_char_p",
46   c =>  "c_char",
47   b =>  "c_byte",
48   B =>  "c_ubyte",
49   C =>  "c_uchar",
50   h =>  "c_short",
51   H =>  "c_ushort",
52   i =>  "c_int",
53   I =>  "c_uint",
54   l =>  "c_long",
55   L =>  "c_ulong",
56   f =>  "c_float",
57   d =>  "c_double",
58   g =>  "c_longdouble",
59   q =>  "c_longlong",
60   Q =>  "c_ulonglong",
61   P =>  "c_void_p",
62   u =>  "c_wchar_p",
63   U =>  "c_char_p",
64   Z =>  "c_wchar_p",
65   X =>  "c_bstr",
66   v =>  "c_bool",
67   O =>  "c_void_p",
68 };
69 our $_types = USE_PERLTYPES ? $_perltypes : $_pytypes;
70 sub _types () { return $_types; }
71 sub allow_overflow_all;
72
73 =head1 SYNOPSIS
74
75 use Ctypes;
76
77 my $int = c_int(10);
78
79 $$int = 15;                          # Note the double sigil
80 $$int += 3;
81 print $int->size;                    # sizeof(int) in C
82 print $int->name;                    # 'c_int'
83
84 my $array = Array( 7, 6, 5, 4, 3 );  #Create array (of c_ushort)
85 my $dblarray = Array( c_double, [ 2, 1, 0, -1, -2 ] );
86 $$dblarray[2] = $$int;               # Again, note sigils
87 print $dblarray->size;               # sizeof(type) * #members
88
89 # Create int-type pointer to double-type array
90 my $intp = Pointer( c_int, $dblarray );
91 print $$intp[2];                     # 1073741824 on my system
92
93 =head1 ABSTRACT
94
95 Ctypes::Type is the base class for classes representing the
96 simple C types, as well as L<Arrays|Ctypes::Type::Array>,
97 L<Pointers|Ctypes::Type::Pointer>, L<Structs|Ctypes::Type::Struct>
98 and L<Unions|Ctypes::Type::Union> (although there are functions for
99 all of them in the main L<Ctypes> namespace, so you can normally
100 just C<use Ctypes>).
101
102 Common methods are documented here. See the relevant documentation
103 for the above packages for more detailed information.
104
105 =cut
106
107 # Ctypes::Type::_new: Abstract base class for all Ctypes objects
108 sub _new {
109   return bless my $self = {
110     _data       =>  0,             # raw (binary) memory block
111     _needsfree  =>  0,             # does object own its data?
112     _owner      =>  undef,         # ref to object that owns this one
113     _size       =>  0,             # size of memory block in bytes
114     _length     =>  1,             # ? number of fields of this object ???
115     _index      =>  undef,         # index of this object into the base
116                                    # object's _object list
117     _objects    =>  undef,         # objects this object holds
118     _value      =>  undef,         # 'a small default buffer'
119     _address    =>  undef,
120     _datasafe   =>  1,             # Can object trust & return its _value
121                                    # or must it update its _data?
122     _name       => undef,
123     _typecode  => undef,
124      } => ref($_[0]) || $_[0];
125 }
126
127 # Pod for these functions is on down below
128
129 # can't be relied upon to be lvalue as compound types will override
130 sub _datasafe {
131   $_[0]->{_datasafe} = $_[1] if defined $_[1]; return $_[0]->{_datasafe};
132 }
133
134 sub _needsfree : lvalue {
135   $_[0]->{_needsfree} = $_[1] if defined $_[1]; $_[0]->{_needsfree};
136 }
137
138 #
139 # Create global c_<type> functions...
140 #
141 my %_defined;
142 for my $k (keys %$_types) {
143   my $name = $_types->{$k};
144   my $func;
145   unless ($_defined{$name}) {
146     no strict 'refs';
147     $func = sub { Ctypes::Type::Simple->new($k, @_); };
148     *{"Ctypes::$name"} = $func;
149     $_defined{$name} = 1;
150   }
151 }
152 our @_allnames = keys %_defined;
153
154 =head1 METHODS
155
156 Apart from its value or values, each Ctypes::Type object holds various
157 pieces of information about itself, which you can access via the methods
158 below. Some are only 'getters', but some could be misused to greatly
159 confuse the object internals, so you shouldn't assign to them lightly.
160
161 =over
162
163 =item data
164
165 Returning a I<reference> to the object's data field, where its value is
166 held in L<pack|perlfunc/"pack">ed form. This was originally designed
167 for internal use, so the semantics are likely to change in future, as
168 handing out direct access to the data field isn't a good default for
169 such an innocuously named method.
170
171 =cut
172
173 #
174 # Hello! Currently classes implement their own data() methods.
175 # Looking into commonalities and whether they can be abstracted
176 # in some way is still TODO.
177 #
178
179 =item index
180
181 Returns the offset of the object into its 'owner' object, if it
182 has one (i.e. an Array, Struct or Union).
183
184 =cut
185
186 sub index : lvalue {
187   $_[0]->{_index} = $_[1] if defined $_[1]; $_[0]->{_index};
188 }
189
190 =item name
191
192 Accessor returning the 'name' of the Type instance ('c_int', 'c_double',
193 etc.).
194
195 B<Note> The use of the C<name> attribute is currently quite
196 inconsistent. It's used in places it shouldn't be. There should be some
197 kind of C<Ctypes::are_like()> function to do a deep equivalence check
198 for data types. At that time C<name> will become simpler. Until then
199 though, the following rules apply:
200
201 Since all basic types are currently Ctypes::Type::Simple objects,
202 the C<name> attribute is how you find out what kind of type you
203 actually have.
204
205 For compound data types, the name will tell you something about the
206 object's contents.
207
208 For Arrays, C<name> is the lowercased C<name> of the type of object
209 contained in the array, minus any leading 'c_', plus the suffix '_Array',
210 e.g. 'int_Array'.
211
212 For Pointers, C<name> is the lowercased C<name> of the type of object
213 being pointed to, minus any leading 'c_', plus the suffix '_Pointer',
214 e.g. 'int_array_Pointer'.
215
216 In the case of Structs, the preceeding convention could get out of hand
217 (even quicker than it does with the others), so C<name> consists of the
218 typecodes of the Struct's constituent types, in order, concatenated
219 together, plus the suffix '_Struct'. So a Struct of three unsigned ints
220 and two signed doubles would have the name 'iiiDD_Struct' (of course,
221 this can't be relied upon for checking equivalence, as all compound
222 Types have the typecode 'p').
223
224 =cut
225
226 sub name   { return $_[0]->{_name}  }
227 sub _set_name { return $_[0]->{_name} = $_[1] }
228
229 =item owner
230
231 Return the object's 'owner' object, i.e. the Array, Struct or Union
232 of which it is currently part. Returns undef if the object isn't
233 inside any others.
234
235 =cut
236
237 sub owner : lvalue {
238   $_[0]->{_owner} = $_[1] if defined $_[1]; $_[0]->{_owner};
239 }
240
241 =item size
242
243 Accessor returning the size in bytes on your system of the C type
244 represented by the Type object. For example, a c_int object might
245 have size 4, and an Array of five of them would have size 20.
246
247 =cut
248
249 sub size   { return $_[0]->{_size}  }
250 sub _set_size { return $_[0]->{_size} = $_[1] }
251
252 =item typecode
253
254 Accessor returning the 'typecode' of the Type instance. A typecode
255 is a 1-character string used internally for representing different
256 C types, which might be useful for various things.
257
258 =cut
259
260 sub typecode { return $_[0]->{_typecode} }
261
262 =back
263
264 =head1 CLASS FUNCTIONS
265
266 =over
267
268 =item allow_overflow_all
269
270 This class method can put a stop to all overflowing for all Type
271 objects. Sets/returns 1 or 0. See L</"allow_overflow"> above.
272
273 =back
274
275 =cut
276
277 {
278   my $allow_overflow_all = 1;
279   sub allow_overflow_all {
280 # ??? This could be improved; could still be called as a class method
281 # with an object instead of a 1 or 0 and user would not be notified
282     my $arg = shift;
283     if( @_ or ( defined($arg) and $arg != 1 and $arg != 0 ) ) {
284       croak("Usage: allow_overflow_all(x) (1 or 0)");
285     }
286     $allow_overflow_all = $arg if defined $arg;
287     return $allow_overflow_all;
288   }
289 }
290
291 1;
292 __END__