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                 string parent_gir_name = parent_symbol.get_full_gir_name ();
 219                 string self_gir_name = gir_name.has_prefix (".") ? gir_name.offset (1) : gir_name;
 220                 if (parent_gir_name.str (".") != null) {
 221                         return "%s%s".printf (parent_gir_name, self_gir_name);
 222                 } else {
 223                         return "%s.%s".printf (parent_gir_name, self_gir_name);
 224                 }
 225         }
 226
 227         /**
 228          * Returns the fully expanded name of this symbol for use in
 229          * human-readable messages.
 230          *
 231          * @return full name
 232          */
 233         public string get_full_name () {
 234                 if (parent_symbol == null) {
 235                         return name;
 236                 }
 237
 238                 if (name == null) {
 239                         return parent_symbol.get_full_name ();
 240                 }
 241
 242                 if (parent_symbol.get_full_name () == null) {
 243                         return name;
 244                 }
 245
 246                 if (name.has_prefix (".")) {
 247                         return "%s%s".printf (parent_symbol.get_full_name (), name);
 248                 } else {
 249                         return "%s.%s".printf (parent_symbol.get_full_name (), name);
 250                 }
 251         }
 252
 253         /**
 254          * Returns the camel case string to be prepended to the name of members
 255          * of this symbol when used in C code.
 256          *
 257          * @return the camel case prefix to be used in C code
 258          */
 259         public virtual string get_cprefix () {
 260                 if (name == null) {
 261                         return "";
 262                 } else {
 263                         return name;
 264                 }
 265         }
 266
 267         /**
 268          * Returns the C name of this symbol in lower case. Words are
 269          * separated by underscores. The lower case C name of the parent symbol
 270          * is prefix of the result, if there is one.
 271          *
 272          * @param infix a string to be placed between namespace and data type
 273          *              name or null
 274          * @return      the lower case name to be used in C code
 275          */
 276         public virtual string? get_lower_case_cname (string? infix = null) {
 277                 return null;
 278         }
 279
 280         /**
 281          * Returns the string to be prefixed to members of this symbol in
 282          * lower case when used in C code.
 283          *
 284          * @return      the lower case prefix to be used in C code
 285          */
 286         public virtual string get_lower_case_cprefix () {
 287                 return "";
 288         }
 289
 290         static List<string> _empty_string_list;
 291
 292         /**
 293          * Returns a list of C header filenames users of this symbol must
 294          * include.
 295          *
 296          * @return list of C header filenames for this symbol
 297          */
 298         public virtual List<string> get_cheader_filenames () {
 299                 if (cheader_filenames == null || cheader_filenames.size == 0) {
 300                         // parent_symbol can be null on incremental parsing
 301                         if (parent_symbol != null) {
 302                                 /* default to header filenames of the namespace */
 303                                 var parent_header_filenames = parent_symbol.get_cheader_filenames ();
 304                                 if (parent_header_filenames.size > 0) {
 305                                         return parent_header_filenames;
 306                                 }
 307                         }
 308
 309                         if (source_reference != null && !external_package) {
 310                                 // don't add default include directives for VAPI files
 311                                 add_cheader_filename (source_reference.file.get_cinclude_filename ());
 312                         } else {
 313                                 if (_empty_string_list == null) {
 314                                         _empty_string_list = new ArrayList<string> ();
 315                                 }
 316                                 return _empty_string_list;
 317                         }
 318                 }
 319                 return cheader_filenames;
 320         }
 321
 322         /**
 323          * Converts a string from CamelCase to lower_case.
 324          *
 325          * @param camel_case a string in camel case
 326          * @return           the specified string converted to lower case
 327          */
 328         public static string camel_case_to_lower_case (string camel_case) {
 329                 if ("_" in camel_case) {
 330                         // do not insert additional underscores if input is not real camel case
 331                         return camel_case.down ();
 332                 }
 333
 334                 var result_builder = new StringBuilder ("");
 335
 336                 weak string i = camel_case;
 337
 338                 bool first = true;
 339                 while (i.length > 0) {
 340                         unichar c = i.get_char ();
 341                         if (c.isupper () && !first) {
 342                                 /* current character is upper case and
 343                                  * we're not at the beginning */
 344                                 weak string t = i.prev_char ();
 345                                 bool prev_upper = t.get_char ().isupper ();
 346                                 t = i.next_char ();
 347                                 bool next_upper = t.get_char ().isupper ();
 348                                 if (!prev_upper || (i.length >= 2 && !next_upper)) {
 349                                         /* previous character wasn't upper case or
 350                                          * next character isn't upper case*/
 351                                         long len = result_builder.str.length;
 352                                         if (len != 1 && result_builder.str.offset (len - 2).get_char () != '_') {
 353                                                 /* we're not creating 1 character words */
 354                                                 result_builder.append_c ('_');
 355                                         }
 356                                 }
 357                         }
 358
 359                         result_builder.append_unichar (c.tolower ());
 360
 361                         first = false;
 362                         i = i.next_char ();
 363                 }
 364
 365                 return result_builder.str;
 366         }
 367
 368         /**
 369          * Converts a string from lower_case to CamelCase.
 370          *
 371          * @param lower_case a string in lower case
 372          * @return           the specified string converted to camel case
 373          */
 374         public static string lower_case_to_camel_case (string lower_case) {
 375                 var result_builder = new StringBuilder ("");
 376
 377                 weak string i = lower_case;
 378
 379                 bool last_underscore = true;
 380                 while (i.length > 0) {
 381                         unichar c = i.get_char ();
 382                         if (c == '_') {
 383                                 last_underscore = true;
 384                         } else if (c.isupper ()) {
 385                                 // original string is not lower_case, don't apply transformation
 386                                 return lower_case;
 387                         } else if (last_underscore) {
 388                                 result_builder.append_unichar (c.toupper ());
 389                                 last_underscore = false;
 390                         } else {
 391                                 result_builder.append_unichar (c);
 392                         }
 393
 394                         i = i.next_char ();
 395                 }
 396
 397                 return result_builder.str;
 398         }
 399
 400         // get the top scope from where this symbol is still accessible
 401         public Scope? get_top_accessible_scope (bool is_internal = false) {
 402                 if (access == SymbolAccessibility.PRIVATE) {
 403                         // private symbols are accessible within the scope where the symbol has been declared
 404                         return owner;
 405                 }
 406
 407                 if (access == SymbolAccessibility.INTERNAL) {
 408                         is_internal = true;
 409                 }
 410
 411                 if (parent_symbol == null) {
 412                         // this is the root symbol
 413                         if (is_internal) {
 414                                 // only accessible within the same library
 415                                 // return root scope
 416                                 return scope;
 417                         } else {
 418                                 // unlimited access
 419                                 return null;
 420                         }
 421                 }
 422
 423                 // if this is a public symbol, it's equally accessible as the parent symbol
 424                 return parent_symbol.get_top_accessible_scope (is_internal);
 425         }
 426
 427         public virtual bool is_instance_member () {
 428                 bool instance = true;
 429                 if (this is Field) {
 430                         var f = (Field) this;
 431                         instance = (f.binding == MemberBinding.INSTANCE);
 432                 } else if (this is Method) {
 433                         var m = (Method) this;
 434                         if (!(m is CreationMethod)) {
 435                                 instance = (m.binding == MemberBinding.INSTANCE);
 436                         }
 437                 } else if (this is Property) {
 438                         var prop = (Property) this;
 439                         instance = (prop.binding == MemberBinding.INSTANCE);
 440                 } else if (this is EnumValue) {
 441                         instance = false;
 442                 } else if (this is ErrorCode) {
 443                         instance = false;
 444                 }
 445
 446                 return instance;
 447         }
 448
 449         public virtual bool is_class_member () {
 450                 bool isclass = true;
 451                 if (this is Field) {
 452                         var f = (Field) this;
 453                         isclass = (f.binding == MemberBinding.CLASS);
 454                 } else if (this is Method) {
 455                         var m = (Method) this;
 456                         if (!(m is CreationMethod)) {
 457                                 isclass = (m.binding == MemberBinding.CLASS);
 458                         }
 459                 } else if (this is Property) {
 460                         var prop = (Property) this;
 461                         isclass = (prop.binding == MemberBinding.CLASS);
 462                 } else if (this is EnumValue) {
 463                         isclass = false;
 464                 } else if (this is ErrorCode) {
 465                         isclass = false;
 466                 }
 467
 468                 return isclass;
 469         }
 470
 471         /**
 472          * Process a [Deprecated] attribute
 473          */
 474         public virtual void process_deprecated_attribute (Attribute attr) {
 475                 if (attr.name != "Deprecated") {
 476                         return;
 477                 }
 478
 479                 deprecated = true;
 480
 481                 if (attr.has_argument ("since")) {
 482                         deprecated_since = attr.get_string ("since");
 483                 }
 484                 if (attr.has_argument ("replacement")) {
 485                         replacement = attr.get_string ("replacement");
 486                 }
 487         }
 488
 489         /**
 490          * Check to see if the symbol has been deprecated, and emit a warning
 491          * if it has.
 492          */
 493         public bool check_deprecated (SourceReference? source_ref = null) {
 494                 if (deprecated) {
 495                         if (!CodeContext.get ().deprecated) {
 496                                 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)));
 497                         }
 498                         return true;
 499                 } else {
 500                         return false;
 501                 }
 502         }
 503
 504         /**
 505          * Sets the C header filename of this namespace to the specified
 506          * filename.
 507          *
 508          * @param cheader_filename header filename
 509          */
 510         public void set_cheader_filename (string cheader_filename) {
 511                 cheader_filenames = new ArrayList<string> ();
 512                 cheader_filenames.add (cheader_filename);
 513         }
 514
 515         /**
 516          * Adds a filename to the list of C header filenames users of this data
 517          * type must include.
 518          *
 519          * @param filename a C header filename
 520          */
 521         public void add_cheader_filename (string filename) {
 522                 if (cheader_filenames == null) {
 523                         cheader_filenames = new ArrayList<string> ();
 524                 }
 525                 cheader_filenames.add (filename);
 526         }
 527
 528         public Symbol? get_hidden_member () {
 529                 Symbol sym = null;
 530
 531                 if (parent_symbol is Class) {
 532                         var cl = ((Class) parent_symbol).base_class;
 533                         while (cl != null) {
 534                                 sym = cl.scope.lookup (name);
 535                                 if (sym != null && sym.access != SymbolAccessibility.PRIVATE) {
 536                                         return sym;
 537                                 }
 538                                 cl = cl.base_class;
 539                         }
 540                 } else if (parent_symbol is Struct) {
 541                         var st = ((Struct) parent_symbol).base_struct;
 542                         while (st != null) {
 543                                 sym = st.scope.lookup (name);
 544                                 if (sym != null && sym.access != SymbolAccessibility.PRIVATE) {
 545                                         return sym;
 546                                 }
 547                                 st = st.base_struct;
 548                         }
 549                 }
 550
 551                 return null;
 552         }
 553
 554         // check whether this symbol is at least as accessible as the specified symbol
 555         public  bool is_accessible (Symbol sym) {
 556                 Scope sym_scope = sym.get_top_accessible_scope ();
 557                 Scope this_scope = this.get_top_accessible_scope ();
 558                 if ((sym_scope == null && this_scope != null)
 559                     || (sym_scope != null && !sym_scope.is_subscope_of (this_scope))) {
 560                         return false;
 561                 }
 562
 563                 return true;
 564         }
 565
 566         public virtual void add_namespace (Namespace ns) {
 567                 Report.error (ns.source_reference, "unexpected declaration");
 568         }
 569
 570         public virtual void add_class (Class cl) {
 571                 Report.error (cl.source_reference, "unexpected declaration");
 572         }
 573
 574         public virtual void add_interface (Interface iface) {
 575                 Report.error (iface.source_reference, "unexpected declaration");
 576         }
 577
 578         public virtual void add_struct (Struct st) {
 579                 Report.error (st.source_reference, "unexpected declaration");
 580         }
 581
 582         public virtual void add_enum (Enum en) {
 583                 Report.error (en.source_reference, "unexpected declaration");
 584         }
 585
 586         public virtual void add_error_domain (ErrorDomain edomain) {
 587                 Report.error (edomain.source_reference, "unexpected declaration");
 588         }
 589
 590         public virtual void add_delegate (Delegate d) {
 591                 Report.error (d.source_reference, "unexpected declaration");
 592         }
 593
 594         public virtual void add_constant (Constant constant) {
 595                 Report.error (constant.source_reference, "unexpected declaration");
 596         }
 597
 598         public virtual void add_field (Field f) {
 599                 Report.error (f.source_reference, "unexpected declaration");
 600         }
 601
 602         public virtual void add_method (Method m) {
 603                 Report.error (m.source_reference, "unexpected declaration");
 604         }
 605
 606         public virtual void add_property (Property prop) {
 607                 Report.error (prop.source_reference, "unexpected declaration");
 608         }
 609
 610         public virtual void add_signal (Signal sig) {
 611                 Report.error (sig.source_reference, "unexpected declaration");
 612         }
 613
 614         public virtual void add_constructor (Constructor c) {
 615                 Report.error (c.source_reference, "unexpected declaration");
 616         }
 617
 618         public virtual void add_destructor (Destructor d) {
 619                 Report.error (d.source_reference, "unexpected declaration");
 620         }
 621 }
 622
 623 public enum Vala.SymbolAccessibility {
 624         PRIVATE,
 625         INTERNAL,
 626         PROTECTED,
 627         PUBLIC
 628 }
 629
 630 public enum Vala.MemberBinding {
 631         INSTANCE,
 632         CLASS,
 633         STATIC
 634 }