reserved.txt 4.32 KB
Newer Older
1
;;
Dave Cooper's avatar
Dave Cooper committed
2
;; Copyright 2002, 2009 Genworks International
3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164
;;
;; This source file is part of the General-purpose Declarative
;; Language project (GDL).
;;
;; This source file contains free software: you can redistribute it
;; and/or modify it under the terms of the GNU Affero General Public
;; License as published by the Free Software Foundation, either
;; version 3 of the License, or (at your option) any later version.
;; 
;; This source file is distributed in the hope that it will be useful,
;; but WITHOUT ANY WARRANTY; without even the implied warranty of
;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
;; Affero General Public License for more details.
;; 
;; You should have received a copy of the GNU Affero General Public
;; License along with this source file.  If not, see
;; <http://www.gnu.org/licenses/>.
;; 



               Reserved Symbols in GDL/GWL
               ===========================

When defining your own objects in GDL, there are a few message names
you should avoid using (i.e. overriding). This only applies to message
and input names within a define-object form, since the :GDL and :GWL
packages have definition locks set. The package definition locks avoid
accidental redefinition of symbols naming GDL/GWL functions, macros,
parameters, constants, and classes. 

In a future GDL release, automatic protection against redefining these
pre-defined messages will probably be added. But currently it is up to
the application developer to avoid using these names.


1. Symbols to Avoid Using as Messages Within a Define-Object Form
   ==============================================================

This includes :input-slots, :computed-slots, :objects,
:hidden-objects, and :functions.

  o From Vanilla-Mixin (which means these apply to any define-object
    form). Please see the GDL Reference Section on Vanilla-Mixin for
    more details:

     aggregate 
     children 
     documentation 
     first 
     first? 
     follow-root-path 
     hidden-children 
     index 
     last 
     last? 
     leaf? 
     message-list 
     mixins 
     next 
     parent
     parent-tree 
     previous 
     restore-slot-default! 
     root 
     root-path 
     root? 
     set-slot! 
     set-slots! 
     slot-documentation 
     type 
     update!


  o From Base-Object (which means these apply to any define-object
    which mixes in base-object or any of its subclasses). Please see
    the GDL Reference Section on Base-Object for more details (note
    that color and line-thickness can be specified in the
    display-controls, and should not be specified as their own
    messages):

    axis-vector    
    color-decimal
    edge-center
    face-center
    face-normal-vector
    line-thickness 
    local-center
    obliqueness
    vertex
    
    
       
2. Symbols to Avoid Using as Input Specifications to an Object or Hidden-Object
===============================================================================

 The following have special meaning within an :objects or
 :hidden-objects specification and should not be used except for the
 intended purpose:

    :parameters

        Used to pass a plist of input specifications into a child
        object, e.g:

          :parameters (list :length 10 :width 20 :height 30)

        is functionally equivalent to:

          :length 10
          :width 20
          :height 30

    :pass-down
  
        Used as shorthand for passing messages down to the child part,
        e.g:

          :pass-down (data labels colors)

        is equivalent to:

          :data (the data)
          :labels (the labels)
          :colors (the colors)


    :sequence

        Used for making a sequence of parts, as with
           
           ...
           :sequence (:size (length (the data)))
           ...
            
          for a standard sequence, or

           ...
           :sequence (:indices (list 1 2 3))
           ...

          for a variable sequence.


    :type 

        Used to specify the type or types of the child object(s).



3. Internal naming convention with the percent sign ("%")
=========================================================

 Finally, in addition to the above specific messages, you should avoid
 naming any messages starting and ending with a percent character
 ("%"), e.g. %my-message% -- this is a convention used to name
 internal, private GDL messages.