translate macro argument list

[reiniervandijk]

The translate macro argument list is ambiguous. And as a result, I see a lot of users make the same mistakes time after time.

instead of:

(origin &rest offsets)

I suggest using something like:

(origin direction offset &rest rest)

Now, a lot of students don't understand what they are supposed to give in and often end up saying something like:

(translate (the center) :front)

In such cases they get an error message:

`nil' is not of the expected type `number'
   [Condition of type type-error]

And are lost. Arguably, they should have read the manual a bit closer. However, I believe it is the duty of the software developer to be as unambiguous as possible when setting up a utilities library.

It should also be possible to check for proper input, viz. whether 3, 5 or 7 inputs are given. An even better would probably be to define this as a method for automatic safe-typing.

(defmethod safe-translate ((origin vector) (direction symbol) (offset number))
        (translate origin direction offset))

[reiniervandijk]

Proposed fix:

(in-package :geom-base)

(defmacro translate (origin direction offset &rest more-translations)
  "[Macro] 3D Point. Within the context of a GDL object definition (i.e. a <tt>define-object</tt>),
translate <b>origin</b> by <b>offset</b> over <b>direction</b>. More direction-offset combinations
can be specified in <b>more-translations</b>.
:arguments (origin \"3D Point\"
            direction \"keyword. A direction keyword can be one of:
            <ul><li><tt>:top</tt> (or <tt>:up</tt>)</li>
            <li><tt>:bottom</tt> (or <tt>:down</tt>)</li>
            <li><tt>:left</tt></li>
            <li><tt>:right</tt></li>
            <li><tt>:front</tt></li>
            <li><tt>:rear</tt> (or <tt>:back</tt>)</li></ul>.\"
            offset \"number. Distance to translate along offset.\")
:&rest (offsets \"Plist consisting of direction keywords and numbers.\")"

  (if more-translations
      ;; recurse
      `(translate (translate-along-vector ,origin 
                      (the (:face-normal-vector (ecase ,direction
                                      ((:up :top) :top)
                                      ((:down :bottom) :bottom)
                                      (:left :left)
                                      (:right :right)
                                      (:front :front)
                                      ((:rear :back) :rear))))
                      ,offset)
          ,@more-translations)
      ;; don't recurse
      `(translate-along-vector ,origin 
                   (the (:face-normal-vector (ecase ,direction
                               ((:up :top) :top)
                               ((:down :bottom) :bottom)
                               (:left :left)
                               (:right :right)
                               (:front :front)
                               ((:rear :back) :rear))))
                   ,offset)))

[reiniervandijk]

Unfortunately I can not test the YADD documentation string, because I keep on getting this error:

[aserve] 13-aserve-worker: 02/01/15 - 11:40:59 - while processing command "GET /assy/geom-base/function-docs/translate.html HTTP/1.1"
got the error Nothing appears after . in list. [file position = 63]

Should I register this as new bug?

[reiniervandijk]

Some form of testing below. I couldn't easily find a way to hook this test into any already existing test module. I noted the regression framework, but it seems to mainly test if something runs, instead of testing for equality or something (correct me if I'm wrong). Here some sort of test.

(in-package :gdl-user)

(define-object translate-sample (base-object)

  :computed-slots
  ((bar (translate (the center) :right 1))
   (baz (translate (the bar) :rear 2 :top 3))
   ;; the following correctly casts a compiler warning, how to test?
   ;; (qux (translate (the center)))
   ))

(defun translate-test ()
  (let ((obj (make-object 'translate-test)))
    (assert (equalp (the-object obj bar) (make-point 1 0 0)))
    (assert (equalp (the-object obj baz) (make-point 1 2 3)))
    t))

[reiniervandijk]

Final note. If anywhere in legacy code something like

(translate a-point)

occurs, a compiler error is thrown. I don't know if you believe this would be troublesome. IMO, it is unlikely, and moreover, it's not desired to write code like that and the compiler error is very welcome. After all, what's the use of translating a point without direction or offset...