vala/valatypesymbol.vala

   1 /* valatypesymbol.vala
   2  *
   3  * Copyright (C) 2006-2008  Jürg Billeter, Raffaele Sandrini
   4  *
   5  * This library is free software; you can redistribute it and/or
   6  * modify it under the terms of the GNU Lesser General Public
   7  * License as published by the Free Software Foundation; either
   8  * version 2.1 of the License, or (at your option) any later version.
   9
  10  * This library is distributed in the hope that it will be useful,
  11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13  * Lesser General Public License for more details.
  14
  15  * You should have received a copy of the GNU Lesser General Public
  16  * License along with this library; if not, write to the Free Software
  17  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301  USA
  18  *
  19  * Author:
  20  *      Jürg Billeter <j@bitron.ch>
  21  *      Raffaele Sandrini <raffaele@sandrini.ch>
  22  */
  23
  24 using GLib;
  25
  26 /**
  27  * Represents a runtime data type. This data type may be defined in Vala source
  28  * code or imported from an external library with a Vala API file.
  29  */
  30 public abstract class Vala.TypeSymbol : Symbol {
  31         public Comment? comment { get; set; }
  32
  33         private List<string> cheader_filenames = new ArrayList<string> ();
  34
  35         public TypeSymbol (string? name, SourceReference? source_reference = null, Comment? comment = null) {
  36                 base (name, source_reference);
  37                 this.comment = comment;
  38         }
  39
  40         /**
  41          * Returns the name of this data type as it is used in C code.
  42          *
  43          * @return the name to be used in C code
  44          */
  45         public abstract string get_cname (bool const_type = false);
  46
  47         /**
  48          * Checks whether this data type has value or reference type semantics.
  49          *
  50          * @return true if this data type has reference type semantics
  51          */
  52         public virtual bool is_reference_type () {
  53                 return false;
  54         }
  55
  56         /**
  57          * Returns the C function name that duplicates instances of this data
  58          * type. The specified C function must accept one argument referencing
  59          * the instance of this data type and return a reference to the
  60          * duplicate.
  61          *
  62          * @return the name of the C function if supported or null otherwise
  63          */
  64         public virtual string? get_dup_function () {
  65                 return null;
  66         }
  67
  68         /**
  69          * Returns the C function name that frees instances of this data type.
  70          * The specified C function must accept one argument pointing to the
  71          * instance to be freed.
  72          *
  73          * @return the name of the C function if supported or null otherwise
  74          */
  75         public virtual string? get_free_function () {
  76                 return null;
  77         }
  78
  79         /**
  80          * Returns the C function name that copies contents of instances of
  81          * this data type. This is only applicable to structs. The specified
  82          * C function must accept two arguments, the first is the source value
  83          * and the second is the destination value.
  84          *
  85          * @return the name of the C function if supported or null otherwise
  86          */
  87         public virtual string? get_copy_function () {
  88                 return null;
  89         }
  90
  91         /**
  92          * Returns the C function name that destroys the contents of instances
  93          * of this data type. This is only applicable to structs. The specified
  94          * C function must accept one argument pointing to the instance to be
  95          * destroyed.
  96          *
  97          * @return the name of the C function if supported or null otherwise
  98          */
  99         public virtual string? get_destroy_function () {
 100                 return null;
 101         }
 102
 103         /**
 104          * Checks whether this data type supports reference counting. This is
 105          * only valid for reference types.
 106          *
 107          * @return true if this data type supports reference counting
 108          */
 109         public virtual bool is_reference_counting () {
 110                 return false;
 111         }
 112
 113         /**
 114          * Returns the C function name that increments the reference count of
 115          * instances of this data type. This is only valid for data types
 116          * supporting reference counting. The specified C function must accept
 117          * one argument referencing the instance of this data type and return
 118          * the reference.
 119          *
 120          * @return the name of the C function or null if this data type does not
 121          *         support reference counting
 122          */
 123         public virtual string? get_ref_function () {
 124                 return null;
 125         }
 126
 127         /**
 128          * Returns the C function name that decrements the reference count of
 129          * instances of this data type. This is only valid for data types
 130          * supporting reference counting. The specified C function must accept
 131          * one argument referencing the instance of this data type.
 132          *
 133          * @return the name of the C function or null if this data type does not
 134          *         support reference counting
 135          */
 136         public virtual string? get_unref_function () {
 137                 return null;
 138         }
 139
 140         /**
 141          * Returns the C function name that sinks the reference count of
 142          * "floating" instances of this data type. This is only valid for data
 143          * types supporting floating references. The specified C function must
 144          * accept one argument referencing the instance of this data type and
 145          * return a non-floating reference.
 146          *
 147          * The ref_sink function is called for any constructor of the class and
 148          * for other methods that have the class as a return value and are
 149          * marked with the 'floating' attribute.
 150          *
 151          * @return the name of the C function or null if this data type does not
 152          *         support floating reference counts
 153          */
 154         public virtual string? get_ref_sink_function () {
 155                 return null;
 156         }
 157
 158         /**
 159          * Returns the C symbol representing the runtime type id for this data
 160          * type. The specified symbol must express a registered GType.
 161          *
 162          * @return the name of the GType name in C code or null if this data
 163          *         type is not registered with GType
 164          */
 165         public virtual string? get_type_id () {
 166                 return null;
 167         }
 168
 169         /**
 170          * Returns the name of this data type as used in C code marshallers
 171          *
 172          * @return type name for marshallers
 173          */
 174         public virtual string? get_marshaller_type_name () {
 175                 return null;
 176         }
 177
 178         /**
 179          * Returns the cname of the GValue parameter spec function.
 180          */
 181         public virtual string? get_param_spec_function () {
 182                 return null;
 183         }
 184
 185         /**
 186          * Returns the cname of the GValue getter function.
 187          */
 188         public virtual string? get_get_value_function () {
 189                 return null;
 190         }
 191
 192         /**
 193          * Returns the cname of the GValue setter function.
 194          */
 195         public virtual string? get_set_value_function () {
 196                 return null;
 197         }
 198
 199         /**
 200          * Returns the C name of this data type in upper case. Words are
 201          * separated by underscores. The upper case C name of the namespace is
 202          * prefix of the result.
 203          *
 204          * @param infix a string to be placed between namespace and data type
 205          *              name or null
 206          * @return      the upper case name to be used in C code
 207          */
 208         public virtual string? get_upper_case_cname (string? infix = null) {
 209                 return null;
 210         }
 211
 212         /**
 213          * Returns the default value for the given type. Returning null means
 214          * there is no default value (i.e. not that the default name is NULL).
 215          *
 216          * @return the name of the default value
 217          */
 218         public virtual string? get_default_value () {
 219                 return null;
 220         }
 221
 222         public override List<string> get_cheader_filenames () {
 223                 // parent_symbol can be null on incremental parsing
 224                 if (cheader_filenames.size == 0 && parent_symbol != null) {
 225                         /* default to header filenames of the namespace */
 226                         foreach (string filename in parent_symbol.get_cheader_filenames ()) {
 227                                 add_cheader_filename (filename);
 228                         }
 229
 230                         if (cheader_filenames.size == 0 && source_reference != null && !external_package) {
 231                                 // don't add default include directives for VAPI files
 232                                 cheader_filenames.add (source_reference.file.get_cinclude_filename ());
 233                         }
 234                 }
 235                 return new ReadOnlyList<string> (cheader_filenames);
 236         }
 237
 238         /**
 239          * Adds a filename to the list of C header filenames users of this data
 240          * type must include.
 241          *
 242          * @param filename a C header filename
 243          */
 244         public void add_cheader_filename (string filename) {
 245                 cheader_filenames.add (filename);
 246         }
 247
 248         /**
 249          * Checks whether this data type is equal to or a subtype of the
 250          * specified data type.
 251          *
 252          * @param t a data type
 253          * @return  true if t is a supertype of this data type, false otherwise
 254          */
 255         public virtual bool is_subtype_of (TypeSymbol t) {
 256                 return (this == t);
 257         }
 258
 259         /**
 260          * Return the index of the specified type parameter name.
 261          */
 262         public virtual int get_type_parameter_index (string name) {
 263                 return -1;
 264         }
 265
 266         /**
 267          * Returns type signature as used for GVariant and D-Bus
 268          */
 269         public virtual string? get_type_signature () {
 270                 return null;
 271         }
 272 }