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