From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 29748 invoked by alias); 3 Jan 2014 21:31:19 -0000 Mailing-List: contact gdb-patches-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: gdb-patches-owner@sourceware.org Received: (qmail 29737 invoked by uid 89); 3 Jan 2014 21:31:18 -0000 Authentication-Results: sourceware.org; auth=none X-Virus-Found: No X-Spam-SWARE-Status: No, score=-1.9 required=5.0 tests=AWL,BAYES_00,RCVD_IN_DNSWL_NONE,RP_MATCHES_RCVD,SPF_HELO_PASS,SPF_PASS autolearn=ham version=3.3.2 X-HELO: plane.gmane.org Received: from plane.gmane.org (HELO plane.gmane.org) (80.91.229.3) by sourceware.org (qpsmtpd/0.93/v0.84-503-g423c35a) with (AES256-SHA encrypted) ESMTPS; Fri, 03 Jan 2014 21:31:17 +0000 Received: from list by plane.gmane.org with local (Exim 4.69) (envelope-from ) id 1VzCKj-0001yX-06 for gdb-patches@sourceware.org; Fri, 03 Jan 2014 22:31:09 +0100 Received: from reverse-83.fdn.fr ([80.67.176.83]) by main.gmane.org with esmtp (Gmexim 0.1 (Debian)) id 1AlnuQ-0007hv-00 for ; Fri, 03 Jan 2014 22:31:08 +0100 Received: from ludo by reverse-83.fdn.fr with local (Gmexim 0.1 (Debian)) id 1AlnuQ-0007hv-00 for ; Fri, 03 Jan 2014 22:31:08 +0100 To: gdb-patches@sourceware.org From: ludo@gnu.org (Ludovic =?utf-8?Q?Court=C3=A8s?=) Subject: Re: [PATCH v1 02/36] Guile extension language: doc additions Date: Fri, 03 Jan 2014 21:31:00 -0000 Message-ID: <87sit4kb1t.fsf@gnu.org> References: <52b9da59.64ab440a.0b0b.7e1c@mx.google.com> <83ha9w68av.fsf@gnu.org> Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-URL: http://www.fdn.fr/~lcourtes/ X-Revolutionary-Date: 14 =?utf-8?Q?Niv=C3=B4se?= an 222 de la =?utf-8?Q?R?= =?utf-8?Q?=C3=A9volution?= X-PGP-Key-ID: 0xEA52ECF4 X-PGP-Key: http://www.fdn.fr/~lcourtes/ludovic.asc X-PGP-Fingerprint: 83C4 F8E5 10A3 3B4C 5BEA D15D 77DD 95E2 EA52 ECF4 X-OS: x86_64-unknown-linux-gnu User-Agent: Gnus/5.130007 (Ma Gnus v0.7) Emacs/24.3 (gnu/linux) X-IsSubscribed: yes X-SW-Source: 2014-01/txt/msg00022.txt.bz2 Eli Zaretskii 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{} 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’.