;;; -*-lisp-*-
;;;
;;; Class finalization implementation
;;;
;;; (c) 2009 Straylight/Edgeware
;;;

;;;----- Licensing notice ---------------------------------------------------
;;;
;;; This file is part of the Sensible Object Design, an object system for C.
;;;
;;; SOD is free software; you can redistribute it and/or modify
;;; it under the terms of the GNU General Public License as published by
;;; the Free Software Foundation; either version 2 of the License, or
;;; (at your option) any later version.
;;;
;;; SOD 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 General Public License for more details.
;;;
;;; You should have received a copy of the GNU General Public License
;;; along with SOD; if not, write to the Free Software Foundation,
;;; Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

(cl:in-package #:sod)

;;;--------------------------------------------------------------------------
;;; Class precedence lists.

;; Just for fun, we implement a wide selection of precedence list algorithms.
;; C3 seems to be clearly the best, with fewer sharp edges for the unwary.
;;
;; The extended precedence graph (EPG) is constructed by adding edges to the
;; superclass graph.  If A and B are classes, then write A < B if A is a
;; (maybe indirect) subclass of B.  For every two classes A and B, and for
;; every /maximal/ subclass of both A and B (i.e., every C for which C < A
;; and C < B, but there does not exist D such that D < A, D < B and C < D):
;; if A precedes B in C's direct superclass list, then draw an edge A -> B,
;; otherwise draw the edge B -> A.
;;
;; A linearization respects the EPG if, whenever A precedes B in the
;; linearization, there is a path from A to B.  The EPG can be cyclic; in
;; that case, we don't care which order the classes in the cycle are
;; linearized.
;;
;; See Barrett, Cassels, Haahr, Moon, Playford, Withington, `A Monotonic
;; Superclass Linearization for Dylan' for more detail.
;; http://www.webcom.com/haahr/dylan/linearization-oopsla96.html

;;; Utilities.

(export 'report-class-list-merge-error)
(defun report-class-list-merge-error (class lists error)
  "Report a failure to merge superclasseses.

   Here, CLASS is the class whose class precedence list we're trying to
   compute; the LISTS are the individual superclass orderings being merged;
   and ERROR is an `inconsistent-merge-error' describing the problem that was
   encountered.

   Each of the LISTS is assumed to begin with the class from which the
   corresponding constraint originates; see `merge-class-lists'."

  (let* ((state (make-inheritance-path-reporter-state class))
	 (candidates (merge-error-candidates error))
	 (focus (remove-duplicates
		 (remove nil
			 (mapcar (lambda (list)
				   (cons (car list)
					 (remove-if-not
					  (lambda (item)
					    (member item candidates))
					  list)))
				 lists)
			 :key #'cddr)
		 :test #'equal :key #'cdr)))

    (cerror*-with-location class "Ill-formed superclass graph: ~
				  can't construct class precedence list ~
				  for `~A'"
			   class)
    (dolist (offenders focus)
      (let ((super (car offenders)))
	(info-with-location super
			    "~{Class `~A' orders `~A' before ~
			       ~#[<BUG>~;`~A'~;`~A' and `~A'~:;~
				  ~@{`~A', ~#[~;and `~A'~]~}~]~}"
			    offenders)
	(report-inheritance-path state super)))))

(export 'merge-class-lists)
(defun merge-class-lists (class lists pick)
  "Merge the LISTS of superclasses of CLASS, using PICK to break ties.

   This is a convenience wrapper around the main `merge-lists' function.
   Given that class linearizations (almost?) always specify a custom
   tiebreaker function, this isn't a keyword argument.

   If a merge error occurs, this function translates it into a rather more
   useful form, and tries to provide helpful notes.

   For error reporting purposes, it's assumed that each of the LISTS begins
   with the class from which the corresponding constraint originates.  This
   initial class does double-duty: it is also considered to be part of the
   list for the purpose of the merge."

  (handler-case (merge-lists lists :pick pick)
    (inconsistent-merge-error (error)
      (report-class-list-merge-error class lists error)
      (continue error))))

;;; Tiebreaker functions.

(defun clos-tiebreaker (candidates so-far)
  "The CLOS linearization tiebreaker function.

   Intended for use with `merge-lists'.  Returns the member of CANDIDATES
   which has a direct subclass furthest to the right in the list SO-FAR.

   This must disambiguate.  The SO-FAR list cannot be empty, since the class
   under construction precedes all of the others.  If two classes share a
   direct subclass then that subclass's direct superclasses list must order
   them relative to each other."

  (dolist (class (reverse so-far))
    (dolist (candidate candidates)
      (when (member candidate (sod-class-direct-superclasses class))
	(return-from clos-tiebreaker candidate))))
  (error "SOD INTERNAL ERROR: Failed to break tie in CLOS"))

(defun c3-tiebreaker (candidates cpls)
  "The C3 linearization tiebreaker function.

   Intended for use with `merge-lists'.  Returns the member of CANDIDATES
   which appears in the earliest element of CPLS, which should be the list of
   the class precedence lists of the direct superclasses of the class in
   question, in the order specified in the class declaration.

   The only class in the class precedence list which does not appear in one
   of these lists is the new class itself, which must precede all of the
   others.

   This must disambiguate, since if two classes are in the same class
   precedence list, then one must appear in it before the other, which
   provides an ordering between them.  (In this situation we return the one
   that matches earliest anyway, which would still give the right answer.)

   Note that this will merge the CPLs of superclasses /as they are/, not
   necessarily as C3 would have computed them.  This ensures monotonicity
   assuming that the superclass CPLs are already monotonic.  If they aren't,
   you're going to lose anyway."

  (dolist (cpl cpls)
    (dolist (candidate candidates)
      (when (member candidate cpl)
	(return-from c3-tiebreaker candidate))))
  (error "SOD INTERNAL ERROR: Failed to break tie in C3"))

;;; Linearization functions.

(export 'clos-cpl)
(defun clos-cpl (class)
  "Compute the class precedence list of CLASS using CLOS linearization rules.

   We merge the direct-superclass lists of all of CLASS's superclasses,
   disambiguating using `clos-tiebreaker'.

   The CLOS linearization preserves local class ordering, but is not
   monotonic, and does not respect the extended precedence graph.  CLOS
   linearization will succeed whenever Dylan or C3 linearization succeeds;
   the converse is not true."

  (labels ((superclasses (class)
	     (let ((direct-supers (sod-class-direct-superclasses class)))
	       (remove-duplicates (cons class
					(mappend #'superclasses
						 direct-supers))))))
    (merge-class-lists class
		       (mapcar (lambda (c)
				 (cons c (sod-class-direct-superclasses c)))
			       (superclasses class))
		       #'clos-tiebreaker)))

(export 'dylan-cpl)
(defun dylan-cpl (class)
  "Compute the class precedence list of CLASS using Dylan linearization
   rules.

   We merge the direct-superclass list of CLASS with the full class
   precedence lists of its direct superclasses, disambiguating using
   `clos-tiebreaker'.  (Inductively, these lists will be consistent with the
   CPLs of indirect superclasses, since those CPLs' orderings are reflected
   in the CPLs of the direct superclasses.)

   The Dylan linearization preserves local class ordering and is monotonic,
   but does not respect the extended precedence graph.

   Note that this will merge the CPLs of superclasses /as they are/, not
   necessarily as Dylan would have computed them.  This ensures monotonicity
   assuming that the superclass CPLs are already monotonic.  If they aren't,
   you're going to lose anyway."

  (let* ((direct-supers (sod-class-direct-superclasses class))
	 (cpls (mapcar #'sod-class-precedence-list direct-supers)))
    (merge-class-lists class
		       (cons (cons class direct-supers) cpls)
		       #'clos-tiebreaker)))

(export 'c3-cpl)
(defun c3-cpl (class)
  "Compute the class precedence list of CLASS using C3 linearization rules.

   We merge the direct-superclass list of CLASS with the full class
   precedence lists of its direct superclasses, disambiguating using
   `c3-tiebreaker'.

   The C3 linearization preserves local class ordering, is monotonic, and
   respects the extended precedence graph.  It is the linearization used in
   Python, Perl 6 and other languages.  It is the recommended linearization
   for SOD."

  (let* ((direct-supers (sod-class-direct-superclasses class))
	 (cpls (mapcar #'sod-class-precedence-list direct-supers)))
    (merge-class-lists class
		       (cons (cons class direct-supers) cpls)
		       (lambda (candidates so-far)
			 (declare (ignore so-far))
			 (c3-tiebreaker candidates cpls)))))

(export 'flavors-cpl)
(defun flavors-cpl (class)
  "Compute the class precedence list of CLASS using Flavors linearization
   rules.

   We do a depth-first traversal of the superclass graph, ignoring duplicates
   of classes we've already visited.  Interestingly, this has the property of
   being able to tolerate cyclic superclass graphs, though defining cyclic
   graphs is syntactically impossible in SOD.

   This linearization has few other redeeming features, however.  In
   particular, the top class tends not to be at the end of the CPL, despite
   it being unequivocally less specific than any other class."

  (let ((done nil))
    (labels ((walk (class)
	       (unless (member class done)
		 (push class done)
		 (dolist (super (sod-class-direct-superclasses class))
		   (walk super)))))
      (walk class)
      (nreverse done))))

(export 'python-cpl)
(defun python-cpl (class)
  "Compute the class precedence list of CLASS using the documented Python 2.2
   linearization rules.

   We do a depth-first traversal of the superclass graph, retaining only the
   last occurrence of each class visited.

   This linearization has few redeeming features.  It was never actually
   implemented; the true Python 2.2 linearization seems closer to (but
   different from) L*LOOPS."

  (let ((done nil))
    (labels ((walk (class)
	       (push class done)
	       (dolist (super (sod-class-direct-superclasses class))
		 (walk super))))
      (walk class)
      (delete-duplicates (nreverse done)))))

(export 'l*loops-cpl)
(defun l*loops-cpl (class)
  "Compute the class precedence list of CLASS using L*LOOPS linearization
   rules.

   We merge the class precedence lists of the direct superclasses of CLASS,
   disambiguating by choosing the earliest candidate which appears in a
   depth-first walk of the superclass graph.

   The L*LOOPS rules are monotonic and respect the extended precedence
   graph.  However (unlike Dylan and CLOS) they don't respect local
   precedence order i.e., the direct-superclasses list orderings."

  (let ((dfs (flavors-cpl class)))
    (cons class
	  (merge-class-lists class
			     (mapcar #'sod-class-precedence-list
				     (sod-class-direct-superclasses class))
			     (lambda (candidates so-far)
			       (declare (ignore so-far))
			       (dolist (class dfs)
				 (when (member class candidates)
				   (return class))))))))

;;; Default function.

(defmethod compute-cpl ((class sod-class))
  (c3-cpl class))

;;;--------------------------------------------------------------------------
;;; Chains.

(defmethod compute-chains ((class sod-class))
  (with-default-error-location (class)
    (with-slots (chain-link class-precedence-list) class
      (let* ((head (if chain-link
		       (sod-class-chain-head chain-link)
		       class))
	     (chain (cons class (and chain-link
				     (sod-class-chain chain-link))))
	     (state (make-inheritance-path-reporter-state class))
	     (table (make-hash-table)))

	;; Check the chains.  We work through each superclass, maintaining a
	;; hash table keyed by class.  If we encounter a class C which links
	;; to L, then we store C as L's value; if L already has a value then
	;; we've found an error.  By the end of all of this, the classes
	;; which don't have an entry are the chain tails.
	(dolist (super class-precedence-list)
	  (let* ((link (sod-class-chain-link super))
		 (found (and link (gethash link table))))
	    (cond ((not found) (setf (gethash link table) super))
		  (t
		   (cerror* "Conflicting chains in class `~A': ~
			     (`~A' and `~A' both link to `~A')"
			    class super found link)
		   (report-inheritance-path state super)
		   (report-inheritance-path state found)))))

	;; Done.
	(values head chain
		(cons chain
		      (mapcar #'sod-class-chain
			      (remove-if (lambda (super)
					   (gethash super table))
					 (cdr class-precedence-list)))))))))

;;;--------------------------------------------------------------------------
;;; Sanity checking.

(defmethod check-class-initializer ((slot effective-slot) (class sod-class))
  (finalization-error (:missing-class-initializer)
    (unless (find-class-initializer slot class)
      (let ((dslot (effective-slot-direct-slot slot)))
	(cerror* "Missing initializer for class slot `~A', ~
		  defined by meta-superclass `~A' of `~A'"
		 dslot (sod-slot-class dslot) class)))))

(defmethod check-class-initializer
    ((slot sod-class-effective-slot) (class sod-class))
  ;; The programmer shouldn't set an explicit initializer here.
  (finalization-error (:invalid-class-initializer)
    (let ((init (find-class-initializer slot class))
	  (dslot (effective-slot-direct-slot slot)))
      (when init
	(cerror* "Initializers not permitted for class slot `~A', ~
		  defined by meta-superclass `~A' of `~A'"
		 dslot (sod-slot-class dslot) class)
	(info-with-location init "Offending initializer defined here")))))

(defmethod check-sod-class ((class sod-class))

  ;; Check the names of things are valid.
  (flet ((check-list (list what namefunc)
	   (dolist (item list)
	     (let ((name (funcall namefunc item)))
	       (unless (valid-name-p name)
		 (cerror*-with-location item
					"Invalid ~A name `~A' in class `~A'"
					what name class))))))
    (unless (valid-name-p (sod-class-name class))
      (cerror* "Invalid class name `~A'" class))
    (unless (valid-name-p (sod-class-nickname class))
      (cerror* "Invalid class nickname `~A' for class `~A'"
	       (sod-class-nickname class) class))
    (check-list (sod-class-messages class) "message" #'sod-message-name)
    (check-list (sod-class-slots class) "slot" #'sod-slot-name))

  ;; Check that the class doesn't define conflicting things.
  (labels ((simple-previous (previous)
	     (info-with-location previous "Previous definition was here"))
	   (simple-complain (what namefunc)
	     (lambda (item previous)
	       (cerror*-with-location item
				      "Duplicate ~A `~A' in class `~A'"
				      what (funcall namefunc item) class)
	       (simple-previous previous))))

    ;; Make sure direct slots have distinct names.
    (find-duplicates (simple-complain "slot name" #'sod-slot-name)
		     (sod-class-slots class) :key #'sod-slot-name)

    ;; Make sure there's at most one initializer for each slot.
    (flet ((check-initializer-list (list kind)
	     (find-duplicates (lambda (initializer previous)
				(let ((slot
				       (sod-initializer-slot initializer)))
				  (cerror*-with-location initializer
							 "Duplicate ~
							  initializer ~
							  for ~A slot `~A' ~
							  in class `~A'"
							 kind slot class)
				  (simple-previous previous)))
			      list :key #'sod-initializer-slot)))
      (check-initializer-list (sod-class-instance-initializers class)
			      "instance")
      (check-initializer-list (sod-class-class-initializers class)
			      "class"))

    ;; Make sure messages have distinct names.
    (find-duplicates (simple-complain "message name" #'sod-message-name)
		     (sod-class-messages class) :key #'sod-message-name)

    ;; Make sure methods are sufficiently distinct.
    (find-duplicates (lambda (method previous)
		       (cerror*-with-location method
					      "Duplicate ~A direct method ~
					       for message `~A' ~
					       in classs `~A'"
					      (sod-method-description method)
					      (sod-method-message method)
					      class)
		       (simple-previous previous))
		     (sod-class-methods class)
		     :key #'sod-method-function-name :test #'equal)

    ;; Make sure superclasses have distinct nicknames.
    (let ((state (make-inheritance-path-reporter-state class)))
      (find-duplicates (lambda (super previous)
			 (cerror*-with-location class
						"Duplicate nickname `~A' ~
						 in superclasses of `~A': ~
						 used by `~A' and `~A'"
						(sod-class-nickname super)
						class super previous)
			 (report-inheritance-path state super)
			 (report-inheritance-path state previous))
		       (sod-class-precedence-list class)
		       :key #'sod-class-nickname :test #'equal)))

  ;; Check that the CHAIN-TO class is actually a proper superclass.  (This
  ;; eliminates hairy things like a class being its own link.)
  (let ((link (sod-class-chain-link class)))
    (unless (or (not link)
		(member link (cdr (sod-class-precedence-list class))))
      (cerror* "In `~A~, chain-to class `~A' is not a proper superclass"
	       class link)))

  ;; Check that the initargs declare compatible types.  Duplicate entries,
  ;; even within a class, are harmless, but at most one initarg in any
  ;; class should declare a default value.
  (let ((seen (make-hash-table :test #'equal))
	(state (make-inheritance-path-reporter-state class)))
    (dolist (super (sod-class-precedence-list class))
      (dolist (initarg (reverse (sod-class-initargs super)))
	(let* ((initarg-name (sod-initarg-name initarg))
	       (initarg-type (sod-initarg-type initarg))
	       (initarg-default (sod-initarg-default initarg))
	       (found (gethash initarg-name seen))
	       (found-type (and found (sod-initarg-type found)))
	       (found-default (and found (sod-initarg-default found)))
	       (found-class (and found (sod-initarg-class found)))
	       (found-location (and found (file-location found))))
	  (with-default-error-location (initarg)
	    (cond ((not found)
		   (setf (gethash initarg-name seen) initarg))
		  ((not (c-type-equal-p initarg-type found-type))
		   (cerror* "Inititalization argument `~A' defined ~
			     with incompatible types: ~
			     ~A in class `~A', but ~A in class `~A'"
			    initarg-name initarg-type super
			    found-type found-class found-location)
		   (report-inheritance-path state super))
		  ((and initarg-default found-default
			(eql super found-class))
		   (cerror* "Initialization argument `~A' redefined ~
			     with default value"
			    initarg-name)
		   (info-with-location found-location
				       "Previous definition is here"))
		  (initarg-default
		   (setf (gethash initarg-name seen) initarg))))))))

  ;; Check for circularity in the superclass graph.  Since the superclasses
  ;; should already be acyclic, it suffices to check that our class is not
  ;; a superclass of any of its own direct superclasses.
  (let ((circle (find-if (lambda (super)
			   (sod-subclass-p super class))
			 (sod-class-direct-superclasses class))))
    (when circle
      (cerror* "`~A' is already a superclass of `~A'" class circle)
      (report-inheritance-path (make-inheritance-path-reporter-state class)
			       circle)))

  ;; Check that the class has a unique root superclass.
  (find-root-superclass class)

  ;; Check that the metaclass is a subclass of each direct superclass's
  ;; metaclass.
  (finalization-error (:bad-metaclass)
    (let ((meta (sod-class-metaclass class)))
      (dolist (super (sod-class-direct-superclasses class))
	(let ((supermeta (sod-class-metaclass super)))
	  (unless (sod-subclass-p meta supermeta)
	    (cerror* "Metaclass `~A' of `~A' isn't a subclass of `~A'"
		     meta class supermeta)
	    (info-with-location super
				"Direct superclass `~A' defined here ~
				 has metaclass `~A'"
				super supermeta))))))

  ;; Check that all of the messages we can be sent have coherent collections
  ;; of applicable methods.  This can go wrong, for example, if we inherit
  ;; methods with differently typed keyword arguments.
  (finalization-error (:mismatched-applicable-methods)
    (dolist (super (sod-class-precedence-list class))
      (dolist (message (sod-class-messages super))
	(let ((methods (sod-message-applicable-methods message class)))
	  (sod-message-check-methods message class methods)))))

  ;; Check that an initializer is available for every slot in the class's
  ;; metaclass.  Skip this and trust the caller if the metaclass isn't
  ;; finalized yet: in that case, we must be bootstrapping, and we must hope
  ;; that the caller knows what they're doing.
  (let* ((meta (sod-class-metaclass class))
	 (ilayout (and (eq (sod-class-state meta) :finalized)
		       (sod-class-ilayout meta))))
    (dolist (ichain (and ilayout (ilayout-ichains ilayout)))
      (dolist (item (cdr (ichain-body ichain)))
	(when (typep item 'islots)
	  (dolist (slot (islots-slots item))
	    (check-class-initializer slot class)))))))

;;;--------------------------------------------------------------------------
;;; Finalization.

(defmethod finalize-sod-class :around ((class sod-class))
  "Common functionality for `finalize-sod-class'.

     * If an attempt to finalize the CLASS has been made before, then we
       don't try again.  Similarly, attempts to finalize a class recursively
       will fail.

     * A condition handler is established to keep track of whether any errors
       are signalled during finalization.  The CLASS is only marked as
       successfully finalized if no (unhandled) errors are encountered."
  (with-default-error-location (class)
    (ecase (sod-class-state class)
      ((nil)

       ;; If this fails, leave the class marked as a loss.
       (setf (slot-value class 'state) :broken)

       ;; Invoke the finalization method proper.  If it signals any
       ;; continuable errors, take note of them so that we can report failure
       ;; properly.
       ;;
       ;; Catch: we get called recursively to clean up superclasses and
       ;; metaclasses, but there should only be one such handler, so don't
       ;; add another.  (In turn, this means that other methods mustn't
       ;; actually trap their significant errors.)
       (let ((have-handler-p (boundp '*finalization-errors*))
	     (*finalization-errors* nil)
	     (*finalization-error-token* nil))
	 (catch '%finalization-failed
	   (if have-handler-p (call-next-method)
	       (handler-bind ((error (lambda (cond)
				       (declare (ignore cond))
				       (pushnew *finalization-error-token*
						*finalization-errors*
						:test #'equal)
				       :decline)))
		 (call-next-method)))
	   (when *finalization-errors* (finalization-failed))
	   (setf (slot-value class 'state) :finalized)
	   t)))

      ;; If the class is broken, we're not going to be able to fix it now.
      (:broken
       nil)

      ;; If we already finalized it, there's no point doing it again.
      (:finalized
       t))))

(defmethod finalize-sod-class ((class sod-class))

  ;; CLONE-AND-HACK WARNING: Note that `bootstrap-classes' has a (very brief)
  ;; clone of the CPL and chain establishment code.  If the interface changes
  ;; then `bootstrap-classes' will need to be changed too.

  ;; Finalize all of the superclasses.  There's some special pleading here to
  ;; make bootstrapping work: we don't try to finalize the metaclass if we're
  ;; a root class (no direct superclasses -- because in that case the
  ;; metaclass will have to be a subclass of us!), or if it's equal to us.
  ;; This is enough to tie the knot at the top of the class graph.  If we
  ;; can't manage this then we're doomed.
  (flet ((try-finalizing (what other-class)
	   (unless (finalize-sod-class other-class)
	     (cerror* "Class `~A' has broken ~A `~A'" class what other-class)
	     (info-with-location other-class
				 "Class `~A' defined here" other-class)
	     (finalization-failed))))
    (let ((supers (sod-class-direct-superclasses class))
	  (meta (sod-class-metaclass class)))
      (dolist (super supers)
	(try-finalizing "direct superclass" super))
      (unless (or (null supers) (eq class meta))
	(try-finalizing "metaclass" meta))))

  ;; Stash the class's type.
  (setf (slot-value class '%type)
	(make-class-type (sod-class-name class)))

  ;; Clobber the lists of items if they've not been set.
  (dolist (slot '(slots instance-initializers class-initializers
		  messages methods))
    (unless (slot-boundp class slot)
      (setf (slot-value class slot) nil)))

  ;; If the CPL hasn't been done yet, compute it.  If we can't manage this
  ;; then there's no hope at all.
  (unless (slot-boundp class 'class-precedence-list)
    (restart-case
	(setf (slot-value class 'class-precedence-list) (compute-cpl class))
      (continue () :report "Continue"
	(finalization-failed))))

  ;; Check that the class is fairly sane.
  (check-sod-class class)

  ;; Determine the class's layout.
  (setf (values (slot-value class 'chain-head)
		(slot-value class 'chain)
		(slot-value class 'chains))
	(compute-chains class)))

;;;----- That's all, folks --------------------------------------------------