vala/valasymbol.vala

   1 /* valasymbol.vala
   2  *
   3  * Copyright (C) 2006-2010  Jürg Billeter
   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  */
  22
  23 using GLib;
  24
  25 /**
  26  * Represents a node in the symbol tree.
  27  */
  28 public abstract class Vala.Symbol : CodeNode {
  29         /**
  30          * The parent of this symbol.
  31          */
  32         public weak Symbol? parent_symbol {
  33                 get {
  34                         if (owner == null) {
  35                                 return null;
  36                         } else {
  37                                 return owner.owner;
  38                         }
  39                 }
  40         }
  41
  42         /**
  43          * The scope this symbol opens.
  44          */
  45         public weak Scope owner {
  46                 get {
  47                         return _owner;
  48                 }
  49                 set {
  50                         _owner = value;
  51                         _scope.parent_scope = value;
  52                 }
  53         }
  54
  55         /**
  56          * The GIR name.
  57          */
  58         public string? gir_name {
  59                 get {
  60                         return _gir_name == null ? name : _gir_name;
  61                 }
  62                 set {
  63                         _gir_name = value;
  64                 }
  65         }
  66
  67         /**
  68          * The symbol name.
  69          */
  70         public string? name { get; set; }
  71
  72         /**
  73          * Specifies whether this symbol is active.
  74          *
  75          * Symbols may become inactive when they only apply to a part of a
  76          * scope. This is used for local variables not declared at the beginning
  77          * of the block to determine which variables need to be freed before
  78          * jump statements.
  79          */
  80         public bool active { get; set; default = true; }
  81
  82         /**
  83          * Specifies whether this symbol has been deprecated.
  84          */
  85         public bool deprecated { get; set; default = false; }
  86
  87         /**
  88          * Specifies what version this symbol has been deprecated since.
  89          */
  90         public string? deprecated_since { get; set; default = null; }
  91
  92         /**
  93          * Specifies the replacement if this symbol has been deprecated.
  94          */
  95         public string? replacement { get; set; default = null; }
  96
  97         /**
  98          * Specifies whether this symbol has been accessed.
  99          */
 100         public bool used { get; set; }
 101
 102         /**
 103          * Specifies the accessibility of this symbol. Public accessibility
 104          * doesn't limit access. Default accessibility limits access to this
 105          * program or library. Private accessibility limits access to instances
 106          * of the contained type.
 107          */
 108         public SymbolAccessibility access { get; set; }
 109
 110         public Comment? comment { get; set; }
 111
 112         private List<string> cheader_filenames;
 113
 114         /**
 115          * Specifies whether this method explicitly hides a member of a base
 116          * type.
 117          */
 118         public bool hides { get; set; }
 119
 120         /**
 121          * Check if this symbol is just internal API (and therefore doesn't need
 122          * to be listed in header files for instance) by traversing parent symbols
 123          * and checking their accessibility.
 124          */
 125         public bool is_internal_symbol () {
 126                 if (!external && external_package) {
 127                         // non-external symbols in VAPI files are internal symbols
 128                         return true;
 129                 }
 130
 131                 for (Symbol sym = this; null != sym; sym = sym.parent_symbol) {
 132                         if (sym.access == SymbolAccessibility.PRIVATE
 133                             || sym.access == SymbolAccessibility.INTERNAL) {
 134                                 return true;
 135                         }
 136                 }
 137
 138                 return false;
 139         }
 140
 141         public bool is_private_symbol () {
 142                 if (!external && external_package) {
 143                         // non-external symbols in VAPI files are private symbols
 144                         return true;
 145                 }
 146
 147                 for (Symbol sym = this; null != sym; sym = sym.parent_symbol) {
 148                         if (sym.access == SymbolAccessibility.PRIVATE) {
 149                                 return true;
 150                         }
 151                 }
 152
 153                 return false;
 154         }
 155
 156         public Scope scope {
 157                 get { return _scope; }
 158         }
 159
 160         /**
 161          * Specifies whether the implementation is external, for example in
 162          * a separate C source file or in an external library.
 163          */
 164         public bool external { get; set; }
 165
 166         /**
 167          * Specifies whether the implementation is in an external library.
 168          */
 169         public bool external_package {
 170                 get {
 171                         return source_type == SourceFileType.PACKAGE;
 172                 }
 173         }
 174
 175         /**
 176          * Gets the SourceFileType of the source file that this symbol
 177          * came from, or SourceFileType.NONE.
 178          */
 179         public SourceFileType source_type {
 180                 get {
 181                         if (source_reference != null) {
 182                                 return source_reference.file.file_type;
 183                         } else {
 184                                 return SourceFileType.NONE;
 185                         }
 186                 }
 187         }
 188
 189         private weak Scope _owner;
 190         private Scope _scope;
 191         private string? _gir_name = null;
 192
 193         public Symbol (string? name, SourceReference? source_reference, Comment? comment = null) {
 194                 this.name = name;
 195                 this.source_reference = source_reference;
 196                 this.comment = comment;
 197                 _scope = new Scope (this);
 198         }
 199
 200         /**
 201          * Returns the fully expanded GIR name of this symbol
 202          *
 203          * @return full GIR name
 204          */
 205         public string get_full_gir_name () {
 206                 if (parent_symbol == null) {
 207                         return gir_name;
 208                 }
 209
 210                 if (name == null) {
 211                         return parent_symbol.get_full_gir_name ();
 212                 }
 213
 214                 if (parent_symbol.get_full_gir_name () == null) {
 215                         return gir_name;
 216                 }
 217
 218                 if (name.has_prefix (".")) {
 219                         return "%s%s".printf (parent_symbol.get_full_gir_name (), gir_name);
 220                 } else {
 221                         return "%s.%s".printf (parent_symbol.get_full_gir_name (), gir_name);
 222                 }
 223         }
 224
 225         /**
 226          * Returns the fully expanded name of this symbol for use in
 227          * human-readable messages.
 228          *
 229          * @return full name
 230          */
 231         public string get_full_name () {
 232                 if (parent_symbol == null) {
 233                         return name;
 234                 }
 235
 236                 if (name == null) {
 237                         return parent_symbol.get_full_name ();
 238                 }
 239
 240                 if (parent_symbol.get_full_name () == null) {
 241                         return name;
 242                 }
 243
 244                 if (name.has_prefix (".")) {
 245                         return "%s%s".printf (parent_symbol.get_full_name (), name);
 246                 } else {
 247                         return "%s.%s".printf (parent_symbol.get_full_name (), name);
 248                 }
 249         }
 250
 251         /**
 252          * Returns the camel case string to be prepended to the name of members
 253          * of this symbol when used in C code.
 254          *
 255          * @return the camel case prefix to be used in C code
 256          */
 257         public virtual string get_cprefix () {
 258                 if (name == null) {
 259                         return "";
 260                 } else {
 261                         return name;
 262                 }
 263         }
 264
 265         /**
 266          * Returns the C name of this symbol in lower case. Words are
 267          * separated by underscores. The lower case C name of the parent symbol
 268          * is prefix of the result, if there is one.
 269          *
 270          * @param infix a string to be placed between namespace and data type
 271          *              name or null
 272          * @return      the lower case name to be used in C code
 273          */
 274         public virtual string? get_lower_case_cname (string? infix = null) {
 275                 return null;
 276         }
 277
 278         /**
 279          * Returns the string to be prefixed to members of this symbol in
 280          * lower case when used in C code.
 281          *
 282          * @return      the lower case prefix to be used in C code
 283          */
 284         public virtual string get_lower_case_cprefix () {
 285                 return "";
 286         }
 287
 288         static List<string> _empty_string_list;
 289
 290         /**
 291          * Returns a list of C header filenames users of this symbol must
 292          * include.
 293          *
 294          * @return list of C header filenames for this symbol
 295          */
 296         public virtual List<string> get_cheader_filenames () {
 297                 if (cheader_filenames == null || cheader_filenames.size == 0) {
 298                         // parent_symbol can be null on incremental parsing
 299                         if (parent_symbol != null) {
 300                                 /* default to header filenames of the namespace */
 301                                 var parent_header_filenames = parent_symbol.get_cheader_filenames ();
 302                                 if (parent_header_filenames.size > 0) {
 303                                         return parent_header_filenames;
 304                                 }
 305                         }
 306
 307                         if (source_reference != null && !external_package) {
 308                                 // don't add default include directives for VAPI files
 309                                 add_cheader_filename (source_reference.file.get_cinclude_filename ());
 310                         } else {
 311                                 if (_empty_string_list == null) {
 312                                         _empty_string_list = new ArrayList<string> ();
 313                                 }
 314                                 return _empty_string_list;
 315                         }
 316                 }
 317                 return cheader_filenames;
 318         }
 319
 320         /**
 321          * Converts a string from CamelCase to lower_case.
 322          *
 323          * @param camel_case a string in camel case
 324          * @return           the specified string converted to lower case
 325          */
 326         public static string camel_case_to_lower_case (string camel_case) {
 327                 if ("_" in camel_case) {
 328                         // do not insert additional underscores if input is not real camel case
 329                         return camel_case.down ();
 330                 }
 331
 332                 var result_builder = new StringBuilder ("");
 333
 334                 weak string i = camel_case;
 335
 336                 bool first = true;
 337                 while (i.length > 0) {
 338                         unichar c = i.get_char ();
 339                         if (c.isupper () && !first) {
 340                                 /* current character is upper case and
 341                                  * we're not at the beginning */
 342                                 weak string t = i.prev_char ();
 343                                 bool prev_upper = t.get_char ().isupper ();
 344                                 t = i.next_char ();
 345                                 bool next_upper = t.get_char ().isupper ();
 346                                 if (!prev_upper || (i.length >= 2 && !next_upper)) {
 347                                         /* previous character wasn't upper case or
 348                                          * next character isn't upper case*/
 349                                         long len = result_builder.str.length;
 350                                         if (len != 1 && result_builder.str.offset (len - 2).get_char () != '_') {
 351                                                 /* we're not creating 1 character words */
 352                                                 result_builder.append_c ('_');
 353                                         }
 354                                 }
 355                         }
 356
 357                         result_builder.append_unichar (c.tolower ());
 358
 359                         first = false;
 360                         i = i.next_char ();
 361                 }
 362
 363                 return result_builder.str;
 364         }
 365
 366         /**
 367          * Converts a string from lower_case to CamelCase.
 368          *
 369          * @param lower_case a string in lower case
 370          * @return           the specified string converted to camel case
 371          */
 372         public static string lower_case_to_camel_case (string lower_case) {
 373                 var result_builder = new StringBuilder ("");
 374
 375                 weak string i = lower_case;
 376
 377                 bool last_underscore = true;
 378                 while (i.length > 0) {
 379                         unichar c = i.get_char ();
 380                         if (c == '_') {
 381                                 last_underscore = true;
 382                         } else if (c.isupper ()) {
 383                                 // original string is not lower_case, don't apply transformation
 384                                 return lower_case;
 385                         } else if (last_underscore) {
 386                                 result_builder.append_unichar (c.toupper ());
 387                                 last_underscore = false;
 388                         } else {
 389                                 result_builder.append_unichar (c);
 390                         }
 391
 392                         i = i.next_char ();
 393                 }
 394
 395                 return result_builder.str;
 396         }
 397
 398         // get the top scope from where this symbol is still accessible
 399         public Scope? get_top_accessible_scope (bool is_internal = false) {
 400                 if (access == SymbolAccessibility.PRIVATE) {
 401                         // private symbols are accessible within the scope where the symbol has been declared
 402                         return owner;
 403                 }
 404
 405                 if (access == SymbolAccessibility.INTERNAL) {
 406                         is_internal = true;
 407                 }
 408
 409                 if (parent_symbol == null) {
 410                         // this is the root symbol
 411                         if (is_internal) {
 412                                 // only accessible within the same library
 413                                 // return root scope
 414                                 return scope;
 415                         } else {
 416                                 // unlimited access
 417                                 return null;
 418                         }
 419                 }
 420
 421                 // if this is a public symbol, it's equally accessible as the parent symbol
 422                 return parent_symbol.get_top_accessible_scope (is_internal);
 423         }
 424
 425         public virtual bool is_instance_member () {
 426                 bool instance = true;
 427                 if (this is Field) {
 428                         var f = (Field) this;
 429                         instance = (f.binding == MemberBinding.INSTANCE);
 430                 } else if (this is Method) {
 431                         var m = (Method) this;
 432                         if (!(m is CreationMethod)) {
 433                                 instance = (m.binding == MemberBinding.INSTANCE);
 434                         }
 435                 } else if (this is Property) {
 436                         var prop = (Property) this;
 437                         instance = (prop.binding == MemberBinding.INSTANCE);
 438                 } else if (this is EnumValue) {
 439                         instance = false;
 440                 } else if (this is ErrorCode) {
 441                         instance = false;
 442                 }
 443
 444                 return instance;
 445         }
 446
 447         public virtual bool is_class_member () {
 448                 bool isclass = true;
 449                 if (this is Field) {
 450                         var f = (Field) this;
 451                         isclass = (f.binding == MemberBinding.CLASS);
 452                 } else if (this is Method) {
 453                         var m = (Method) this;
 454                         if (!(m is CreationMethod)) {
 455                                 isclass = (m.binding == MemberBinding.CLASS);
 456                         }
 457                 } else if (this is Property) {
 458                         var prop = (Property) this;
 459                         isclass = (prop.binding == MemberBinding.CLASS);
 460                 } else if (this is EnumValue) {
 461                         isclass = false;
 462                 } else if (this is ErrorCode) {
 463                         isclass = false;
 464                 }
 465
 466                 return isclass;
 467         }
 468
 469         /**
 470          * Process a [Deprecated] attribute
 471          */
 472         public virtual void process_deprecated_attribute (Attribute attr) {
 473                 if (attr.name != "Deprecated") {
 474                         return;
 475                 }
 476
 477                 deprecated = true;
 478
 479                 if (attr.has_argument ("since")) {
 480                         deprecated_since = attr.get_string ("since");
 481                 }
 482                 if (attr.has_argument ("replacement")) {
 483                         replacement = attr.get_string ("replacement");
 484                 }
 485         }
 486
 487         /**
 488          * Check to see if the symbol has been deprecated, and emit a warning
 489          * if it has.
 490          */
 491         public bool check_deprecated (SourceReference? source_ref = null) {
 492                 if (deprecated) {
 493                         if (!CodeContext.get ().deprecated) {
 494                                 Report.warning (source_ref, "%s %s%s".printf (get_full_name (), (deprecated_since == null) ? "is deprecated" : "has been deprecated since %s".printf (deprecated_since), (replacement == null) ? "" : ". Use %s".printf (replacement)));
 495                         }
 496                         return true;
 497                 } else {
 498                         return false;
 499                 }
 500         }
 501
 502         /**
 503          * Sets the C header filename of this namespace to the specified
 504          * filename.
 505          *
 506          * @param cheader_filename header filename
 507          */
 508         public void set_cheader_filename (string cheader_filename) {
 509                 cheader_filenames = new ArrayList<string> ();
 510                 cheader_filenames.add (cheader_filename);
 511         }
 512
 513         /**
 514          * Adds a filename to the list of C header filenames users of this data
 515          * type must include.
 516          *
 517          * @param filename a C header filename
 518          */
 519         public void add_cheader_filename (string filename) {
 520                 if (cheader_filenames == null) {
 521                         cheader_filenames = new ArrayList<string> ();
 522                 }
 523                 cheader_filenames.add (filename);
 524         }
 525
 526         public Symbol? get_hidden_member () {
 527                 Symbol sym = null;
 528
 529                 if (parent_symbol is Class) {
 530                         var cl = ((Class) parent_symbol).base_class;
 531                         while (cl != null) {
 532                                 sym = cl.scope.lookup (name);
 533                                 if (sym != null && sym.access != SymbolAccessibility.PRIVATE) {
 534                                         return sym;
 535                                 }
 536                                 cl = cl.base_class;
 537                         }
 538                 } else if (parent_symbol is Struct) {
 539                         var st = ((Struct) parent_symbol).base_struct;
 540                         while (st != null) {
 541                                 sym = st.scope.lookup (name);
 542                                 if (sym != null && sym.access != SymbolAccessibility.PRIVATE) {
 543                                         return sym;
 544                                 }
 545                                 st = st.base_struct;
 546                         }
 547                 }
 548
 549                 return null;
 550         }
 551
 552         // check whether this symbol is at least as accessible as the specified symbol
 553         public  bool is_accessible (Symbol sym) {
 554                 Scope sym_scope = sym.get_top_accessible_scope ();
 555                 Scope this_scope = this.get_top_accessible_scope ();
 556                 if ((sym_scope == null && this_scope != null)
 557                     || (sym_scope != null && !sym_scope.is_subscope_of (this_scope))) {
 558                         return false;
 559                 }
 560
 561                 return true;
 562         }
 563
 564         public virtual void add_namespace (Namespace ns) {
 565                 Report.error (ns.source_reference, "unexpected declaration");
 566         }
 567
 568         public virtual void add_class (Class cl) {
 569                 Report.error (cl.source_reference, "unexpected declaration");
 570         }
 571
 572         public virtual void add_interface (Interface iface) {
 573                 Report.error (iface.source_reference, "unexpected declaration");
 574         }
 575
 576         public virtual void add_struct (Struct st) {
 577                 Report.error (st.source_reference, "unexpected declaration");
 578         }
 579
 580         public virtual void add_enum (Enum en) {
 581                 Report.error (en.source_reference, "unexpected declaration");
 582         }
 583
 584         public virtual void add_error_domain (ErrorDomain edomain) {
 585                 Report.error (edomain.source_reference, "unexpected declaration");
 586         }
 587
 588         public virtual void add_delegate (Delegate d) {
 589                 Report.error (d.source_reference, "unexpected declaration");
 590         }
 591
 592         public virtual void add_constant (Constant constant) {
 593                 Report.error (constant.source_reference, "unexpected declaration");
 594         }
 595
 596         public virtual void add_field (Field f) {
 597                 Report.error (f.source_reference, "unexpected declaration");
 598         }
 599
 600         public virtual void add_method (Method m) {
 601                 Report.error (m.source_reference, "unexpected declaration");
 602         }
 603
 604         public virtual void add_property (Property prop) {
 605                 Report.error (prop.source_reference, "unexpected declaration");
 606         }
 607
 608         public virtual void add_signal (Signal sig) {
 609                 Report.error (sig.source_reference, "unexpected declaration");
 610         }
 611
 612         public virtual void add_constructor (Constructor c) {
 613                 Report.error (c.source_reference, "unexpected declaration");
 614         }
 615
 616         public virtual void add_destructor (Destructor d) {
 617                 Report.error (d.source_reference, "unexpected declaration");
 618         }
 619 }
 620
 621 public enum Vala.SymbolAccessibility {
 622         PRIVATE,
 623         INTERNAL,
 624         PROTECTED,
 625         PUBLIC
 626 }
 627
 628 public enum Vala.MemberBinding {
 629         INSTANCE,
 630         CLASS,
 631         STATIC
 632 }