vala/valasymbol.vala

   1 /* valasymbol.vala
   2  *
   3  * Copyright (C) 2006-2009  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 using Gee;
  25
  26 /**
  27  * Represents a node in the symbol tree.
  28  */
  29 public abstract class Vala.Symbol : CodeNode {
  30         /**
  31          * The parent of this symbol.
  32          */
  33         public weak Symbol? parent_symbol {
  34                 get {
  35                         if (owner == null) {
  36                                 return null;
  37                         } else {
  38                                 return owner.owner;
  39                         }
  40                 }
  41         }
  42
  43         /**
  44          * The scope this symbol opens.
  45          */
  46         public weak Scope owner {
  47                 get {
  48                         return _owner;
  49                 }
  50                 set {
  51                         _owner = value;
  52                         _scope.parent_scope = value;
  53                 }
  54         }
  55
  56         /**
  57          * The symbol name.
  58          */
  59         public string? name { get; set; }
  60
  61         /**
  62          * Specifies whether this symbol is active.
  63          *
  64          * Symbols may become inactive when they only apply to a part of a
  65          * scope. This is used for local variables not declared at the beginning
  66          * of the block to determine which variables need to be freed before
  67          * jump statements.
  68          */
  69         public bool active { get; set; default = true; }
  70
  71         /**
  72          * Specifies whether this symbol has been accessed.
  73          */
  74         public bool used { get; set; }
  75
  76         /**
  77          * Specifies the accessibility of this symbol. Public accessibility
  78          * doesn't limit access. Default accessibility limits access to this
  79          * program or library. Private accessibility limits access to instances
  80          * of the contained type.
  81          */
  82         public SymbolAccessibility access { get; set; }
  83
  84         /**
  85          * Check if this symbol is just internal API (and therefore doesn't need
  86          * to be listed in header files for instance) by traversing parent symbols
  87          * and checking their accessibility.
  88          */
  89         public bool is_internal_symbol () {
  90                 if (!external && external_package) {
  91                         // non-external symbols in VAPI files are internal symbols
  92                         return true;
  93                 }
  94
  95                 for (Symbol sym = this; null != sym; sym = sym.parent_symbol) {
  96                         if (SymbolAccessibility.PRIVATE == sym.access) {
  97                                 return true;
  98                         }
  99                 }
 100
 101                 return false;
 102         }
 103
 104         public Scope scope {
 105                 get { return _scope; }
 106         }
 107
 108         /**
 109          * Specifies whether the implementation is external, for example in
 110          * a separate C source file or in an external library.
 111          */
 112         public bool external { get; set; }
 113
 114         /**
 115          * Specifies whether the implementation is in an external library.
 116          */
 117         public bool external_package {
 118                 get {
 119                         return (source_reference != null && source_reference.file.external_package);
 120                 }
 121         }
 122
 123         private weak Scope _owner;
 124         private Scope _scope;
 125
 126         public Symbol (string? name, SourceReference? source_reference) {
 127                 this.name = name;
 128                 this.source_reference = source_reference;
 129                 _scope = new Scope (this);
 130         }
 131
 132         /**
 133          * Returns the fully expanded name of this symbol for use in
 134          * human-readable messages.
 135          *
 136          * @return full name
 137          */
 138         public string get_full_name () {
 139                 if (parent_symbol == null) {
 140                         return name;
 141                 }
 142
 143                 if (name == null) {
 144                         return parent_symbol.get_full_name ();
 145                 }
 146
 147                 if (parent_symbol.get_full_name () == null) {
 148                         return name;
 149                 }
 150
 151                 return "%s.%s".printf (parent_symbol.get_full_name (), name);
 152         }
 153
 154         /**
 155          * Returns the camel case string to be prepended to the name of members
 156          * of this symbol when used in C code.
 157          *
 158          * @return the camel case prefix to be used in C code
 159          */
 160         public virtual string get_cprefix () {
 161                 if (name == null) {
 162                         return "";
 163                 } else {
 164                         return name;
 165                 }
 166         }
 167
 168         /**
 169          * Returns the C name of this symbol in lower case. Words are
 170          * separated by underscores. The lower case C name of the parent symbol
 171          * is prefix of the result, if there is one.
 172          *
 173          * @param infix a string to be placed between namespace and data type
 174          *              name or null
 175          * @return      the lower case name to be used in C code
 176          */
 177         public virtual string? get_lower_case_cname (string? infix = null) {
 178                 return null;
 179         }
 180
 181         /**
 182          * Returns the string to be prefixed to members of this symbol in
 183          * lower case when used in C code.
 184          *
 185          * @return      the lower case prefix to be used in C code
 186          */
 187         public virtual string get_lower_case_cprefix () {
 188                 return "";
 189         }
 190
 191         /**
 192          * Returns a list of C header filenames users of this symbol must
 193          * include.
 194          *
 195          * @return list of C header filenames for this symbol
 196          */
 197         public virtual Gee.List<string> get_cheader_filenames () {
 198                 return new ArrayList<string> ();
 199         }
 200
 201         /**
 202          * Converts a string from CamelCase to lower_case.
 203          *
 204          * @param camel_case a string in camel case
 205          * @return           the specified string converted to lower case
 206          */
 207         public static string camel_case_to_lower_case (string camel_case) {
 208                 var result_builder = new StringBuilder ("");
 209
 210                 weak string i = camel_case;
 211
 212                 bool first = true;
 213                 while (i.len () > 0) {
 214                         unichar c = i.get_char ();
 215                         if (c.isupper () && !first) {
 216                                 /* current character is upper case and
 217                                  * we're not at the beginning */
 218                                 weak string t = i.prev_char ();
 219                                 bool prev_upper = t.get_char ().isupper ();
 220                                 t = i.next_char ();
 221                                 bool next_upper = t.get_char ().isupper ();
 222                                 if (!prev_upper || (i.len () >= 2 && !next_upper)) {
 223                                         /* previous character wasn't upper case or
 224                                          * next character isn't upper case*/
 225                                         long len = result_builder.str.len ();
 226                                         if (len != 1 && result_builder.str.offset (len - 2).get_char () != '_') {
 227                                                 /* we're not creating 1 character words */
 228                                                 result_builder.append_c ('_');
 229                                         }
 230                                 }
 231                         }
 232
 233                         result_builder.append_unichar (c.tolower ());
 234
 235                         first = false;
 236                         i = i.next_char ();
 237                 }
 238
 239                 return result_builder.str;
 240         }
 241
 242         /**
 243          * Converts a string from lower_case to CamelCase.
 244          *
 245          * @param lower_case a string in lower case
 246          * @return           the specified string converted to camel case
 247          */
 248         public static string lower_case_to_camel_case (string lower_case) {
 249                 var result_builder = new StringBuilder ("");
 250
 251                 weak string i = lower_case;
 252
 253                 bool last_underscore = true;
 254                 while (i.len () > 0) {
 255                         unichar c = i.get_char ();
 256                         if (c == '_') {
 257                                 last_underscore = true;
 258                         } else if (c.isupper ()) {
 259                                 // original string is not lower_case, don't apply transformation
 260                                 return lower_case;
 261                         } else if (last_underscore) {
 262                                 result_builder.append_unichar (c.toupper ());
 263                                 last_underscore = false;
 264                         } else {
 265                                 result_builder.append_unichar (c);
 266                         }
 267
 268                         i = i.next_char ();
 269                 }
 270
 271                 return result_builder.str;
 272         }
 273
 274         // get the top scope from where this symbol is still accessible
 275         public Scope? get_top_accessible_scope () {
 276                 if (access != SymbolAccessibility.PUBLIC) {
 277                         // private symbols are accessible within the scope where the symbol has been declared
 278                         Scope scope = owner;
 279
 280                         // skip scopes of normal namespaces, they don't influence accessibility
 281                         while (scope != null && scope.owner is Namespace && scope.owner.name != null) {
 282                                 scope = scope.parent_scope;
 283                         }
 284
 285                         return scope;
 286                 }
 287
 288                 if (parent_symbol == null) {
 289                         return null;
 290                 }
 291
 292                 // if this is a public symbol, it's equally accessible as the parent symbol
 293                 return parent_symbol.get_top_accessible_scope ();
 294         }
 295 }
 296
 297 public enum Vala.SymbolAccessibility {
 298         PRIVATE,
 299         INTERNAL,
 300         PROTECTED,
 301         PUBLIC
 302 }
 303