API changes

API changes

[Ben Wing]

I've made the following API changes to stuff that's also in GNU Emacs:

scroll-up/scroll-down take a second optional argument, WINDOW.

commandp takes a second optional argument, CALL-INTERACTIVELY, which 
indicates whether the given item can be executed by `call-interactively' 
(normally, the return value indicates whether the item can be executed 
by `command-execute'; this includes vectors and strings, which are not 
allowed by `call-interactively').  this is a clean way of determining, 
for example, how to execute a callback in a menu spec or the like -- 
such callbacks are defined as "if an interactive thing, use 
call-interactively; else, use eval".

Recently I also added the function

(truncate-string-with-continuation-dots STR END-COLUMN &optional DOTS-STR)

Documentation:
Truncate string STR to end at column END-COLUMN, adding dots if needed.
The dots (normally `...', but can be controlled by DOTS-STR)' will be added
in such a way that the total string occupies no more than END-COLUMN
columns -- i.e. if the string goes past END-COLUMN, it will be truncated
somewhere short of END-COLUMN so that, with the dots added, the string
occupies END-COLUMN columns.

"columns" in here refers to the same thing that 
`truncate-string-to-width' deals in, i.e. "display columns" where 
Japanese characters get two.

ben

Re: API changes

[Daniel Pittman]

On Sat, 27 Apr 2002, Ben Wing wrote:

[...]

> Recently I also added the function
> 
> (truncate-string-with-continuation-dots STR END-COLUMN &optional
> DOTS-STR)
> 
> Documentation: Truncate string STR to end at column END-COLUMN, adding
> dots if needed. The dots (normally `...', but can be controlled by
> DOTS-STR)' will be added in such a way that the total string occupies
> no more than END-COLUMN columns -- i.e. if the string goes past
> END-COLUMN, it will be truncated somewhere short of END-COLUMN so
> that, with the dots added, the string occupies END-COLUMN columns.
> 
> "columns" in here refers to the same thing that
> `truncate-string-to-width' deals in, i.e. "display columns" where
> Japanese characters get two.

Can you please include the fact that this deals with display columns to
the documentation? Having dealt with the differing opinions of GNU Emacs
and XEmacs on what (format "%-10s" foo) outputs, it's /really/ nice to
have that in the docstring, not just the source. :)

Thanks,
        Daniel

-- 
In the present-day reconstruction of physics, fragments of the Newtonian
concepts are stubbornly retained. The result is to reduce modern physics to a
sort of mystic chant over an unintelligible universe.
        -- Alfred North Whitehead, _Modes of Thought_

Re: API changes

[Colin Walters]

On Sat, 2002-04-27 at 09:39, Ben Wing wrote:

> Recently I also added the function
> 
> (truncate-string-with-continuation-dots STR END-COLUMN &optional DOTS-STR)

I use something like this in several of my packages, and I think it
would be useful to have in Emacs.  If there are no objections from the
other Emacs people, I will implement it.

Ben, are you willing to contribute the docstring to Emacs?  I don't know
if you have assigned copyright for Emacs or not.  If not, may I ask that
you just post quick paraphrases of the docstrings?

On the other hand, perhaps this docstring comes in the "under 10 lines"
definition; I hope one of the other Emacs people can say whether or not
we can use it.

Re: API changes

[Stefan Monnier]

> commandp takes a second optional argument, CALL-INTERACTIVELY, which
> indicates whether the given item can be executed by `call-interactively'
> (normally, the return value indicates whether the item can be executed
> by `command-execute'; this includes vectors and strings, which are not
> allowed by `call-interactively').

I always disliked this.  I feel like the elisp layer should only
have one of the two (i.e. I think that Fcall_interactively should
not be exported to elisp and should be replaced by
(defalias 'call-interactively 'command-execute)).

>  this is a clean way of determining,
> for example, how to execute a callback in a menu spec or the like --
> such callbacks are defined as "if an interactive thing, use
> call-interactively; else, use eval".

For what it's worth, `functionp' seems to work just fine for that purpose
(after all, if it's a non-interactive function, `eval' won't be much more
useful than `call-interactively').


	Stefan

Re: API changes

[Richard Stallman]

I think it would be a cleaner interface to add an optional way to
specify an ellipsis in truncate-string-to-width.

Re: API changes

[Richard Stallman]

    On the other hand, perhaps this docstring comes in the "under 10 lines"
    definition; I hope one of the other Emacs people can say whether or not
    we can use it.

We can use a small number of lines from a person in Emacs.
However, we cannot do this over and over, because that would
add up to a significant amount of material.  We could only do
it once.

Re: API changes

[Colin Walters]

On Mon, 2002-04-29 at 01:05, Richard Stallman wrote:
>     On the other hand, perhaps this docstring comes in the "under 10 lines"
>     definition; I hope one of the other Emacs people can say whether or not
>     we can use it.
> 
> We can use a small number of lines from a person in Emacs.
> However, we cannot do this over and over, because that would
> add up to a significant amount of material.  We could only do
> it once.

In that case, I think we could establish the convention that our
discussions of API functions should include just the function prototype,
and a quick paraphrased version of the docstring.  Any objections?

We might also say that those with the appropriate copyright assignment
for Emacs could post a sample implementation; but this may end up
complicating the work for the Emacs maintainers, to make sure that all
code has been assigned.

Re: API changes

[Colin Walters]

On Mon, 2002-04-29 at 01:05, Richard Stallman wrote:

> I think it would be a cleaner interface to add an optional way to
> specify an ellipsis in truncate-string-to-width.

Have we come to any conclusion on this issue?  In this case I think
Richard is right in that adding to `truncate-string-to-width' would be
better.

Regardless, I would definitely like to have this functionality available
in both Emacs and XEmacs.

Re: API changes

[Ben Wing]

----- Original Message -----
From: "Colin Walters" <walters@verbum.org>
To: <ben@666.com>
Cc: <emacs-devel@gnu.org>; <xemacs-design@xemacs.org>
Sent: Friday, May 03, 2002 11:26 PM
Subject: Re: API changes


> On Mon, 2002-04-29 at 01:05, Richard Stallman wrote:
>
> > I think it would be a cleaner interface to add an optional way to
> > specify an ellipsis in truncate-string-to-width.
>
> Have we come to any conclusion on this issue?  In this case I think
> Richard is right in that adding to `truncate-string-to-width' would be
> better.
>
> Regardless, I would definitely like to have this functionality available
> in both Emacs and XEmacs.
>
>

OK, i agree with the change and I made it.  I'm attaching the new code.  I'm
willing to sign papers for this if someone tells me how I go about doing
that -- getting the forms, etc.

ben

(defun truncate-string-to-width (str end-column &optional start-column
padding
         ellipses)
  "Truncate string STR to end at column END-COLUMN.
The optional 3rd arg START-COLUMN, if non-nil, specifies
the starting column; that means to return the characters occupying
columns START-COLUMN ... END-COLUMN of STR.

The optional 4th arg PADDING, if non-nil, specifies a padding character
to add at the end of the result if STR doesn't reach column END-COLUMN,
or if END-COLUMN comes in the middle of a character in STR.
PADDING is also added at the beginning of the result
if column START-COLUMN appears in the middle of a character in STR.

If PADDING is nil, no padding is added in these cases, so
the resulting string may be narrower than END-COLUMN.

BUG: Currently assumes that the padding character is of width one.  You
will get weird results if not.

If ELLIPSES is non-nil, add ellipses (specified by ELLIPSES if a string,
else `...') if STR extends past END-COLUMN.  The ellipses will be added in
such a way that the total string occupies no more than END-COLUMN columns
-- i.e. if the string goes past END-COLUMN, it will be truncated somewhere
short of END-COLUMN so that, with the ellipses added (and padding, if the
proper place to truncate the string would be in the middle of a character),
the string occupies exactly END-COLUMN columns."
  (or start-column
      (setq start-column 0))
  (let ((len (length str))
 (idx 0)
 (column 0)
 (head-padding "") (tail-padding "")
 ch last-column last-idx from-idx)

    ;; find the index of START-COLUMN; bail out if end of string reached.
    (condition-case nil
 (while (< column start-column)
   (setq ch (aref str idx)
  column (+ column (char-width ch))
  idx (1+ idx)))
      (args-out-of-range (setq idx len)))
    (if (< column start-column)
 ;; if string ends before START-COLUMN, return either a blank string
 ;; or a string entirely padded.
 (if padding (make-string (- end-column start-column) padding) "")
      (if (and padding (> column start-column))
   (setq head-padding (make-string (- column start-column) padding)))
      (setq from-idx idx)
      ;; If END-COLUMN is before START-COLUMN, then bail out.
      (if (< end-column column)
   (setq idx from-idx ellipses "")

 ;; handle ELLIPSES
 (cond ((null ellipses) (setq ellipses ""))
       ((if (<= (string-width str) end-column)
     ;; string fits, no ellipses
     (setq ellipses "")))
       (t
        ;; else, insert default value and ...
        (or (stringp ellipses) (setq ellipses "..."))
        ;; ... take away the width of the ellipses from the
        ;; destination.  do all computations with new, shorter
        ;; width.  the padding computed will get us exactly up to
        ;; the shorted width, which is right -- it just gets added
        ;; to the right of the ellipses.
      (setq end-column (- end-column (string-width ellipses)))))

 ;; find the index of END-COLUMN; bail out if end of string reached.
 (condition-case nil
     (while (< column end-column)
       (setq last-column column
      last-idx idx
      ch (aref str idx)
      column (+ column (char-width ch))
      idx (1+ idx)))
   (args-out-of-range (setq idx len)))
 ;; if we went too far (stopped in middle of character), back up.
 (if (> column end-column)
     (setq column last-column idx last-idx))
 ;; compute remaining padding
 (if (and padding (< column end-column))
     (setq tail-padding (make-string (- end-column column) padding))))
      ;; get substring ...
      (setq str (substring str from-idx idx))
      ;; and construct result
      (if padding
   (concat head-padding str tail-padding ellipses)
 (concat str ellipses)))))

>
>
>
>
>
>
> _______________________________________________
> Emacs-devel mailing list
> Emacs-devel@gnu.org
> http://mail.gnu.org/mailman/listinfo/emacs-devel
>
>

Re: API changes

[Richard Stallman]

    OK, i agree with the change and I made it.  I'm attaching the new code.  I'm
    willing to sign papers for this if someone tells me how I go about doing
    that -- getting the forms, etc.

Thanks; I will take care of that.  Did you add the comments too?
I would like to install them also.

Re: API changes

[Colin Walters]

[-- Attachment #1: Type: text/plain, Size: 731 bytes --]

> OK, i agree with the change and I made it.  I'm attaching the new code.  

Well, I was about halfway through implementing it myself, so I just went
ahead and finished my implementation.  Along the way, there were enough
different cases to worry about that I wrote a little test suite; please
find it attached, along with my implementation.

Try typing M-C-x on the test suite; your implementation seems to behave
differently when the string is truncated, but too small to contain the
ellipsis.  In that case I just returned the truncated string.  On the
other test suite entries we agreed on the output.

(Incidentally, something is strange with your mail; your comments came
*after* the ----- Original Message ----- delimiter)


[-- Attachment #2: tstw-test.el --]
[-- Type: text/x-emacs-lisp, Size: 5098 bytes --]

;; -*- mode: emacs-lisp; coding: iso-2022-7bit -*-

;;;###autoload
(defun truncate-string-to-width (str end-column
				     &optional start-column padding ellipsis)
  "Truncate string STR to end at column END-COLUMN.
The optional 3rd arg START-COLUMN, if non-nil, specifies the starting
column; that means to return the characters occupying columns
START-COLUMN ... END-COLUMN of STR.  Both END-COLUMN and START-COLUMN
are specified in terms of character display width in the current
buffer; see also `char-width'.

The optional 4th arg PADDING, if non-nil, specifies a padding
character (which should have a display width of 1) to add at the end
of the result if STR doesn't reach column END-COLUMN, or if END-COLUMN
comes in the middle of a character in STR.  PADDING is also added at
the beginning of the result if column START-COLUMN appears in the
middle of a character in STR.

If PADDING is nil, no padding is added in these cases, so
the resulting string may be narrower than END-COLUMN.

If ELLIPSIS is non-nil, it should be a string which will replace the
end of STR (including any padding) if it extends beyond END-COLUMN,
unless the display width of STR is equal to or less than the display
width of ELLIPSIS.  If it is non-nil and not a string, then ELLIPSIS
defaults to \"...\"."
  (or start-column
      (setq start-column 0))
  (when (and ellipsis (not (stringp ellipsis)))
    (setq ellipsis "..."))
  (let ((str-len (length str))
	(str-width (string-width str))
	(ellipsis-len (if ellipsis (length ellipsis) 0))
	(ellipsis-width (if ellipsis (string-width ellipsis) 0))
	(idx 0)
	(column 0)
	(head-padding "") (tail-padding "")
	ch last-column last-idx from-idx)
    (condition-case nil
	(while (< column start-column)
	  (setq ch (aref str idx)
		column (+ column (char-width ch))
		idx (1+ idx)))
      (args-out-of-range (setq idx str-len)))
    (if (< column start-column)
	(if padding (make-string end-column padding) "")
      (when (and padding (> column start-column))
	(setq head-padding (make-string (- column start-column) padding)))
      (setq from-idx idx)
      (when (>= end-column column)
	(if (and (< end-column str-width)
		 (> str-width ellipsis-width))
	    (setq end-column (- end-column ellipsis-width))
	  (setq ellipsis ""))
	(condition-case nil
	    (while (< column end-column)
	      (setq last-column column
		    last-idx idx
		    ch (aref str idx)
		    column (+ column (char-width ch))
		    idx (1+ idx)))
	  (args-out-of-range (setq idx str-len)))
	(when (> column end-column)
	  (setq column last-column
		idx last-idx))
	(when (and padding (< column end-column))
	  (setq tail-padding (make-string (- end-column column) padding))))
      (concat head-padding (substring str from-idx idx)
	      tail-padding ellipsis))))

(dolist (test '(
		(("" 0) . "")
		(("x" 1) . "x")
		(("xy" 1) . "x")
		(("xy" 2 1) . "y")
		(("xy" 0) . "")
		(("xy" 3) . "xy")
		(("^[$AVP^[(B" 0) . "")
		(("^[$AVP^[(B" 1) . "")
		(("^[$AVP^[(B" 2) . "^[$AVP^[(B")
		(("^[$AVP^[(B" 1 nil ? ) . " ")
		(("^[$AVPND^[(B" 3 1 ? ) . "  ")
		(("x^[$AVP^[(Bx" 2) . "x")
		(("x^[$AVP^[(Bx" 3) . "x^[$AVP^[(B")
		(("x^[$AVP^[(Bx" 3) . "x^[$AVP^[(B")
		(("x^[$AVP^[(Bx" 4 1) . "^[$AVP^[(Bx")
		(("kor^[$(CGQ^[(Be^[$(C1[^[(Ban" 8 1 ? ) . "or^[$(CGQ^[(Be^[$(C1[^[(B")
		(("kor^[$(CGQ^[(Be^[$(C1[^[(Ban" 7 2 ? ) . "r^[$(CGQ^[(Be ")
		(("" 0 nil nil "...") . "")
		(("x" 3 nil nil "...") . "x")
		(("^[$AVP^[(B" 3 nil nil "...") . "^[$AVP^[(B")
		(("foo" 3 nil nil "...") . "foo")
		(("foo" 2 nil nil "...") . "fo") ;; XEmacs failure?
		(("foobar" 6 0 nil "...") . "foobar")
		(("foobarbaz" 6 nil nil "...") . "foo...")
		(("foobarbaz" 7 2 nil "...") . "ob...")
		(("foobarbaz" 9 3 nil "...") . "barbaz")
		(("^[$B$3^[(Bh^[$B$s^[(Be^[$B$K^[(Bl^[$B$A^[(Bl^[$B$O^[(Bo" 15 1 ?  t) . " h^[$B$s^[(Be^[$B$K^[(Bl^[$B$A^[(Bl^[$B$O^[(Bo")
		(("^[$B$3^[(Bh^[$B$s^[(Be^[$B$K^[(Bl^[$B$A^[(Bl^[$B$O^[(Bo" 14 1 ?  t) . " h^[$B$s^[(Be^[$B$K^[(Bl^[$B$A^[(B...")
		(("x" 3 nil nil "^[$(0GnM$^[(B") . "x")
		(("^[$AVP^[(B" 2 nil nil "^[$(0GnM$^[(B") . "^[$AVP^[(B")
		(("^[$AVP^[(B" 1 nil ?x "^[$(0GnM$^[(B") . "x") ;; XEmacs error
		(("^[$AVPND^[(B" 3 nil ?  "^[$(0GnM$^[(B") . "^[$AVP^[(B ") ;; XEmacs error
		(("foobarbaz" 4 nil nil  "^[$(0GnM$^[(B") . "^[$(0GnM$^[(B")
		(("foobarbaz" 5 nil nil  "^[$(0GnM$^[(B") . "f^[$(0GnM$^[(B")
		(("foobarbaz" 6 nil nil  "^[$(0GnM$^[(B") . "fo^[$(0GnM$^[(B")
		(("foobarbaz" 8 3 nil "^[$(0GnM$^[(B") . "b^[$(0GnM$^[(B")
		(("^[$B$3^[(Bh^[$B$s^[(Be^[$B$K^[(Bl^[$B$A^[(Bl^[$B$O^[(Bo" 14 4 ?x "^[$BF|K\8l^[(B") . "xe^[$B$KF|K\8l^[(B")
		(("^[$B$3^[(Bh^[$B$s^[(Be^[$B$K^[(Bl^[$B$A^[(Bl^[$B$O^[(Bo" 13 4 ?x "^[$BF|K\8l^[(B") . "xex^[$BF|K\8l^[(B")
		))
  (let (ret)
    (condition-case e 
	(setq ret (apply #'truncate-string-to-width (car test)))
      (error (setq ret e)))
    (unless (equal ret (cdr test))
      (error "%s: expected %s, got %s"
	     (prin1-to-string (cons 'truncate-string-to-width (car test)))
	     (prin1-to-string (cdr test))
	     (if (consp ret)
		 (format "error: %s: %s" (car ret)
			 (prin1-to-string (cdr ret)))
	       (prin1-to-string ret))))))

Re: API changes

[Colin Walters]

On Sun, 2002-05-19 at 15:40, Richard Stallman wrote:
> I know you were trying to help, but I wish you had not done this.
> To have Ben Wing signing legal papers for code going into Emacs
> could open the door to much bigger cooperation with him.

I agree, that would be a big win.

> I don't know whether your having written this function will geopardize
> that possibility, but it might.

I apologize; I wasn't thinking beyond the immediate term.

Re: API changes

[Stephen J. Turnbull]

>>>>> "Colin" == Colin Walters <walters@verbum.org> writes:

    Colin> On Sun, 2002-05-19 at 15:40, Richard Stallman wrote:

    >> I don't know whether your having written this function will
    >> geopardize that possibility, but it might.

    Colin> I apologize; I wasn't thinking beyond the immediate term.

Don't worry about it, Ben doesn't think that way.


-- 
Institute of Policy and Planning Sciences     http://turnbull.sk.tsukuba.ac.jp
University of Tsukuba                    Tennodai 1-1-1 Tsukuba 305-8573 JAPAN
 My nostalgia for Icon makes me forget about any of the bad things.  I don't
have much nostalgia for Perl, so its faults I remember.  Scott Gilbert c.l.py