This is the mail archive of the
gdb-patches@sourceware.org
mailing list for the GDB project.
Re: [PATCH v1 02/36] Guile extension language: doc additions
- From: ludo at gnu dot org (Ludovic CourtÃs)
- To: gdb-patches at sourceware dot org
- Date: Fri, 03 Jan 2014 22:30:54 +0100
- Subject: Re: [PATCH v1 02/36] Guile extension language: doc additions
- Authentication-results: sourceware.org; auth=none
- References: <52b9da59 dot 64ab440a dot 0b0b dot 7e1c at mx dot google dot com> <83ha9w68av dot fsf at gnu dot org>
Eli Zaretskii <eliz@gnu.org> skribis:
>> +Guile version 2.0.9 is well tested, earlier 2.0 versions are not.
>
> I'm not sure we should say this in the manual.
In practice the parts that are used (mostly the C API) have seen few
additions over 2.0, so itâs likely that it would work with any 2.0.x.
>> +The implementation uses Guile's @code{smob} (small object)
> ^^^^^^^^^^^^
> This should be in @dfn, as it's new terminology.
Better yet:
(@pxref{Smobs,,, guile, GNU Guile Reference Manual})
[...]
>> +Therefore @code{eq?} does not work as expected.
>> +However @code{equal?} does work.
>> +
>> +@smallexample
>> +(gdb) guile (eq? (make-value 1) (make-value 1))
>> +$1 = #f
>> +(gdb) guile (equal? (make-value 1) (make-value 1))
>> +$1 = #t
>> +@end smallexample
>
> Wouldn't this be confusing for Scheme programmers? Is it terribly
> hard to make eq? work?
We discussed this before, and I think thatâs fine if itâs not doable, as
long as itâs clearly documented.
However, rather than âdoes not work as expectedâ (which could be
misleading), what about something like:
âmake-valueâ always returns a fresh object. Therefore,
@code{<gdb:value>} returned by different calls to âmake-valueâ are
usually different:
@example
(eq? (make-value 1) (make-value 1))
@result{} #f
(equal? (make-value 1) (make-value 1))
@result{} #t
@end example
>> +@defun value? object
What about distinguishing Scheme functions, like:
@deffn {Scheme Procedure} value? object
>> +If @var{type} is not provided,
>> +a Scheme real is converted to the C @code{double} type for the
>> +current architecture.
>
> Isn't Guile built with libgmp? If so, doesn't it support floats
> which, when converted to a double, will lose accuracy?
Guile uses GMP, but GMP is for integers (bignums).
Real numbers in Guile (numbers for which âreal?â returns #t) are either
doubles or rationalsâcalled âinexactâ and âexactâ, respectively (info
"(guile) Real and Rational Numbers"):
scheme@(guile-user)> (real? 3.14)
$2 = #t
scheme@(guile-user)> (real? 22/7)
$3 = #t
scheme@(guile-user)> 22/7
$4 = 22/7
scheme@(guile-user)> (exact->inexact 22/7)
$5 = 3.142857142857143
Thereâs loss of accuracy only when converting a rational to a double.
>> +A Scheme string is converted to a target string, using the current
>> +target encoding.
>
> What if target encoding doesn't support some of the characters in the
> string?
Guileâs behavior can be controlled with
â%default-port-conversion-strategyâ: it can raise an exception, or
substitute any characters that could not be converted, or escape them
(info "(guile) Ports").
Perhaps this should be briefly mentioned, with a cross-ref.
>> +The optional @var{errors} argument is either @code{"strict"}
>> +or @code{"replace"}. A value of @code{"strict"} corresponds to
>> +Guile's @code{SCM_FAILED_CONVERSION_ERROR} and a value of @code{"replace"}
>> +corresponds to Guile's @code{SCM_FAILED_CONVERSION_QUESTION_MARK}.
>
> Suggest a cross-reference to Guile documentation here.
Agreed. Also, Guile talks of âconversion strategyâ and âconversion
error handlerâ, with values âerrorâ, âsubstituteâ, and âescapeâ (at the
Scheme level), and Iâd recommend sticking to those names and terminology.
>> +If the optional @var{length} argument is given, the string will be
>> +fetched and encoded to the length of characters specified. If
>> +the @var{length} argument is not provided, the string will be fetched
>> +and encoded until a null of appropriate width is found.
>
> Isn't this null termination description skewed towards C-like
> languages? Aren't there languages where strings don't have to be
> null-terminated?
Yes, and thatâs when LENGTH should be provided, AIUI.
(I agree with most of Eliâs other suggestions.)
Thanks to both of you,
Ludoâ.