Function: kcell:ref-to-id

kcell:ref-to-id is an autoloaded and byte-compiled function defined in kcell.el.

Signature

(kcell:ref-to-id CELL-REF &optional KVIEWSPEC-FLAG)

Documentation

Return a CELL-REF string converted to a cell idstamp (integer).

If CELL-REF contains both a relative and a permanent id, the permanent id is returned. If CELL-REF is invalid or does not exist, nil is returned.

If optional KVIEWSPEC-FLAG is non-nil and CELL-REF includes a viewspec, return the the idstamp concatenated with the viewspec
(begins with a | character) as a string.

CELL-REF may be a whole number:

  12 - permanent idstamp

or may be composed from these string forms:
  1 or 1b - relative id, augment style
  1.2 - relative id, legal style
  012 - permanent idstamp
  1a=012 - both relative and permanent ids (in that order) separated by =
  |viewspec - a koutliner viewspec setting, rather than a cell reference
  :viewspec - an augment viewspec, ignored for now.

Optionally, any of these id forms (or the relative form) may be followed by zero or more whitespace characters and optionally a comma, followed by the '|' character and some view specification characters.

Augment capabilities not yet implemented and ignored for now:
  1. Augment viewspec characters preceded by a colon
  2. Any of the above id forms followed by a period and some
     alpha characters indicating a location relative to the id.

Source Code

;; Defined in ~/.emacs.d/elpa/hyperbole-20260414.325/kotl/kcell.el
;;;###autoload
(defun kcell:ref-to-id (cell-ref &optional kviewspec-flag)
  "Return a CELL-REF string converted to a cell idstamp (integer).
If CELL-REF contains both a relative and a permanent id, the permanent id is
returned.  If CELL-REF is invalid or does not exist, nil is returned.

If optional KVIEWSPEC-FLAG is non-nil and CELL-REF includes a
viewspec, return the the idstamp concatenated with the viewspec
\(begins with a | character) as a string.

CELL-REF may be a whole number:

  12       - permanent idstamp

or may be composed from these string forms:
  1 or 1b   - relative id, augment style
  1.2       - relative id, legal style
  012       - permanent idstamp
  1a=012    - both relative and permanent ids (in that order) separated by =
  |viewspec - a koutliner viewspec setting, rather than a cell reference
  :viewspec - an augment viewspec, ignored for now.

Optionally, any of these id forms (or the relative form) may be followed by
zero or more whitespace characters and optionally a comma, followed by
the '|' character and some view specification characters.

Augment capabilities not yet implemented and ignored for now:
  1. Augment viewspec characters preceded by a colon
  2. Any of the above id forms followed by a period and some
     alpha characters indicating a location relative to the id."
    (cond ((integerp cell-ref)
	   (if (zerop cell-ref)
	       0
	     (when (kproperty:position 'idstamp cell-ref)
	       cell-ref)))
	  ((stringp cell-ref)
	   (let (kviewspec
		 relative-id-string
		 idstamp-string)
	     ;; Remove whitespace and any comma
	     (setq cell-ref (replace-regexp-in-string "\\s-*,?\\s-*" "" cell-ref nil t))
	     (if (string-equal cell-ref "0")
		 (setq idstamp-string "0")
	       ;; Ignore Augment :viewspec.
	       (when (string-match ":" cell-ref)
		 (setq cell-ref (substring cell-ref 0 (match-beginning 0))))
	       ;; Separate koutline |kviewspec from cell id.
	       (when (string-match "|" cell-ref)
		 (setq kviewspec (substring cell-ref (match-beginning 0))
		       cell-ref (substring cell-ref 0 (match-beginning 0))))
	       (setq idstamp-string
		     (cond
		      ((string-match-p "[^.= \t\n\r\f0-9a-zA-Z]" cell-ref) nil)
		      ((or
			;; relative cell ref and idstamp
			(string-match "\\`\\([1-9][.0-9a-zA-Z]*\\)=\\(0[0-9]*\\)\\'" cell-ref)
			;; idstamp only
			(string-match "\\`\\(\\)\\(0[0-9]*\\)\\'" cell-ref))
		       (setq idstamp-string (match-string 2 cell-ref))
		       ;; Validate that idstamp value exists, else return nil
		       (when (kproperty:position 'idstamp (string-to-number idstamp-string))
			 idstamp-string))
		      ((string-match "\\`\\([1-9][.0-9a-zA-Z]*\\)\\'" cell-ref)
		       ;; relative cell ref
		       (setq  relative-id-string (match-string 1 cell-ref))
		       (save-excursion
			 (goto-char (point-min))
			 (when (re-search-forward (concat "^[ \t]*" (regexp-quote relative-id-string)
							  (regexp-quote (kview:label-separator kotl-kview)))
						  nil t)
			   (setq idstamp-string (kcell-view:idstamp))
			   ;; Validate that idstamp value exists, else return nil
			   (when (kproperty:position 'idstamp (string-to-number idstamp-string))
			     idstamp-string))))
		      ((save-excursion
			 (when (kotl-mode:goto-heading cell-ref)
			   ;; textual label at the beginning of a cell
			   (setq idstamp-string (kcell-view:idstamp))))))))

	     (if idstamp-string
		 (if (and kviewspec-flag kviewspec)
		     (concat idstamp-string kviewspec)
		   (string-to-number idstamp-string))
	       kviewspec)))))