Conversion Tools for Code in Legacy Formats =========================================== GDL provides a limited set of tools for converting legacy code into the GDL native syntax. Currently the tools provide some capability for converting code in the icad-style defpart format. While these tools can help in migrating legacy code, it is recommended that you consider doing new development in the GDL native syntax (described in the file "usage.txt" and in the reference documentation), because this syntax will be better supported by Genworks into the future and is intended as a more general-purpose syntax for all types of applications, not necessarily just CAD-centric ones. This document provides a rough description of the mapping done by the conversion tools; it is by no means exhaustive, and you should still inspect the converted results (using the "convert-defparts" function for example), to ensure that the generated GDL-native code is in fact doing what you intended. Please understand that there are many subtle differences in going from icad, a very large and complex Flavors-based object system, to GDL, a relatively new and simple, small, CLOS-based system. Legacy icad-style code will require testing and vetting, and may require some rewriting, to ensure that it is functioning properly with the GDL compiler and runtime system. 1 Loading the conversion tools ============================== Load the conversion tools using the "require" facility as follows: (require :defpart) If you are licensed for the conversion tools, this will load without errors (currently, all licensed GDL seats are licensed for the conversion tools). 2 Converting code as a one-time process ======================================= You can convert files from the legacy icad-style syntax to GDL-native syntax with the "convert-defparts" function. This function takes either a filename or a directory containing source files, and will convert all defparts, defwriters, and defcompanions to the closest available GDL analogs. Each defpart, defwriter, and defcompanion will be placed in its own output file in the system temporary directory, in a subdirectory named for the package, as follows: /tmp//.lisp For companions, the filename will be constructed from both the "writer" name and the "object" name making up the companion. 3 Converting code on the fly ============================ You can also keep your legacy code in the legacy format, and the conversion tools will convert it on the fly as part of the compilation process. This is not recommended as a long-term strategy, however, unless you have a requirement to continue using your code both in the legacy icad environment as well as in the GDL environment. Appendix A: GDL Object Hierarchy ================================ For a normal GDL object, the class hierarchy is as follows: T ..Standard-Class ...Vanilla-Mixin .... T and Standard-Class are built-in CLOS classes. Vanilla-Mixin is a base GDL type which provides many of the foundational messages for a GDL object. See the reference documentation on vanilla-mixin for details. (note: the name for the GDL "vanilla-mixin" is inspired by the old Steve's Ice Cream in Ann Arbor, MI, and is not connected with "vanilla-mixin" from the Flavors object system). Base-object is mixed into most of the geometric primitives, and you can mix it into your own parts. It provides the basic messages for the reference box sizes, position, and orientation, as well as other standard spatial messages. See the reference documentation for base-object for details. Appendix B: Mapping from defpart to define-object ================================================= Object Definition Sections ========================== defpart -> define-object Note that in all the examples below, message names can be normal symbols, they need not be keyword symbols (although there is no harm in using keywords). The symbol must be literally present at compile time; if you want to evaluate a message name at runtime, you can use the "evaluate" special symbol as in icad. In this case you should stick with keyword symbols: (setq key :length) (the (evaluate key)) == (the length) :inputs -> :input-slots (without default values): ... :input-slots (length width height) ... :optional-inputs -> :input-slots (with default values): Note that each input-slot is within its own set of parentheses, unlike icad optional-inputs which are expressed in plist format: ... :input-slots ((length 10) (width 20) (height (+ (the length) (the width)))) ... :modifiable-inputs, :modifiable-optional-inputs -> In GDL, these are the same as :input-slots described above, with the addition of the :settable modifier for :modifiable-optional-inputs. Required inputs are by defaultt "settable" (i.e. modifiable) and the :settable modifier is not required or added by the translator. :attributes -> :computed-slots Note that each computed-slot is within its own set of parentheses, unlike icad attributes which are expressed in plist format: :computed-slots ((length 10) (width (twice (the length)))) Note also that message names can be normal symbols, they need not be keyword symbols (although there is no harm in using keywords). :modifiable-attributes -> :computed-slots with the :settable modifier keyword: :computed-slots ((length 10 :settable) (width (twice (the length)) :settable)) :parts -> :objects :pseudo-parts -> :hidden-objects The :type of an object or hidden-object _must_ evaluate to a symbol. This means you have to quote it even if it is a literal symbol: :objects ((mybox :type 'box ...)) Special keywords Within a Part Specification: ============================================= :type (:series ) -> :type (:size ) ... :quantify (:series ) -> :sequence (:size ) ... :quantify (:variable ) -> :sequence (:indices ) ... :with-attributes -> :pass-down Positioning and Orienting ========================= There are _no_ special positioning or orienting keywords such as :on-top, :in-front, :postion-about, etc. In GDL you position and orient using :center and :orientation as inputs to the object or as messages defined within the object. See the reference documentation on base-object for more information on this. UPDATE: Based on a customer request, the translator has been supplemented to to handle some of the symbolic :position and :orientation semantics from icad. Currently this feature is not documented and handles only a subset of the keywords. Please contact us if you would like more information on this feature. :methods -> :functions Messages which take arguments are called "functions" in GDL, since they are more similar to Common Lisp functions than CLOS methods in that the arguments to a GDL function cannot be specialized as one would expect with a normal CLOS defmethod. Note however that since GDL is CLOS-based, you are free to define normal CLOS defmethods using GDL object types as argument discriminators, as well as mix in standard CLOS classes with your GDL objects and vice-versa (this ability to mix CLOS classes with GDL objects is true in theory, at the time of this writing however it may need some testing and vetting in real use). As with other message names, the names for :functions can be normal literal unquoted symbols or keyword symbols. The need not be keyword symbols. NOTE: GDL's define-object also supports a :methods section, which contains true CLOS-style methods which can have their arguments specialized in the same manner as normal CLOS methods. This feature is not yet documented so please contact us if you would like more information on it. :spec-attributes, :layout -> Not supported. Consider using the GWL web-based application server system as an alternative to legacy PUI code. Contact us if you require conversion support. :trials -> Not supported. If you are a supported customer, please do not hesitate to contact Genworks for information on several alternative approaches to searching and optimizing. Appendix C: defcompanion, defwriter =================================== In GDL the macros define-view and define-format provide some roughly comparable functionality. Please see the reference documentation for each of these macros for details.