[business-core] refactor & document gnc:owner-from-split

This function helps to establish UI link from register split to an
owner's split. It should not be used anywhere else. Its use in reports
will be removed.

It is also unnecessarily complex -- it is called from an AP/AR account
register split, it should have all necessary information via split
metadata. e.g. this function *can* return a split owner if originating
from an Asset/Liability account which settles an invoice, but this
functionality is not used because there is no asset/liability register
hook to call it.

libgnucash/engine/business-core.scm

@@ -19,6 +19,7 @@
 
 (define-module (gnucash business-core))
 (use-modules (gnucash gnc-module))
+(use-modules (srfi srfi-1))
 (gnc:module-load "gnucash/engine" 0)
 
 (define (gnc:owner-get-address owner)
@@ -99,39 +100,29 @@
   (let ((type type-val))
     (equal? type GNC-AMT-TYPE-PERCENT)))
 
+;; this function aims to find a split's owner. various splits are
+;; supported: (1) any splits in the invoice posted transaction, in
+;; APAR or income/expense accounts (2) any splits from invoice's
+;; payments, in APAR or asset/liability accounts. it returns either
+;; the owner or '() if not found. in addition, if owner was found, the
+;; result-owner argument is mutated to it.
 (define (gnc:owner-from-split split result-owner)
+  (define (notnull x) (and (not (null? x)) x))
   (let* ((trans (xaccSplitGetParent split))
-	 (invoice (gncInvoiceGetInvoiceFromTxn trans))
-	 (temp-owner (gncOwnerNew))
-	 (owner '()))
-
-    (if (not (null? invoice))
-	(set! owner (gncInvoiceGetOwner invoice))
-	(let ((split-list (xaccTransGetSplitList trans)))
-	  (define (check-splits splits)
-	    (if (and splits (not (null? splits)))
-		(let* ((split (car splits))
-		       (lot (xaccSplitGetLot split)))
-		  (if (not (null? lot))
-		      (let* ((invoice (gncInvoiceGetInvoiceFromLot lot))
-			     (owner? (gncOwnerGetOwnerFromLot
-				      lot temp-owner)))
-			(if (not (null? invoice))
-			    (set! owner (gncInvoiceGetOwner invoice))
-			    (if owner?
-				(set! owner temp-owner)
-				(check-splits (cdr splits)))))
-		      (check-splits (cdr splits))))))
-	  (check-splits split-list)))
-
-    (if (not (null? owner))
-	(begin
-	  (gncOwnerCopy (gncOwnerGetEndOwner owner) result-owner)
-	  (gncOwnerFree temp-owner)
-	  result-owner)
-	(begin
-	  (gncOwnerFree temp-owner)
-	  '()))))
+	 (invoice (notnull (gncInvoiceGetInvoiceFromTxn trans)))
+	 (temp (gncOwnerNew))
+	 (owner (or (and invoice (gncInvoiceGetOwner invoice))
+                    (any
+                     (lambda (split)
+                       (let* ((lot (xaccSplitGetLot split))
+                              (invoice (notnull (gncInvoiceGetInvoiceFromLot lot))))
+                         (or (and invoice (gncInvoiceGetOwner invoice))
+                             (and (gncOwnerGetOwnerFromLot lot temp) temp))))
+                     (xaccTransGetSplitList trans)))))
+    (gncOwnerFree temp)
+    (cond (owner (gncOwnerCopy (gncOwnerGetEndOwner owner) result-owner)
+                 result-owner)
+          (else  '()))))
 
 
 (export gnc:owner-get-address)