From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: =?UTF-8?B?VsOtdG9yIERlIEFyYcO6am8=?= Newsgroups: gmane.lisp.guile.user Subject: Re: Python-style doctests in Guile (implemented, please comment) Date: Tue, 1 Aug 2017 19:04:33 -0300 Message-ID: <5980FAF1.8080806@sapo.pt> References: <87379d7m66.fsf@web.de> <87ini8zs4w.fsf@netris.org> <871sowmri4.fsf@web.de> NNTP-Posting-Host: blaine.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Trace: blaine.gmane.org 1501625138 15346 195.159.176.226 (1 Aug 2017 22:05:38 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Tue, 1 Aug 2017 22:05:38 +0000 (UTC) User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:38.0) Gecko/20100101 Icedove/38.8.0 To: guile-user@gnu.org Original-X-From: guile-user-bounces+guile-user=m.gmane.org@gnu.org Wed Aug 02 00:05:30 2017 Return-path: Envelope-to: guile-user@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by blaine.gmane.org with esmtp (Exim 4.84_2) (envelope-from ) id 1dcfI4-0003HF-NC for guile-user@m.gmane.org; Wed, 02 Aug 2017 00:05:24 +0200 Original-Received: from localhost ([::1]:44659 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dcfIA-00078J-Gd for guile-user@m.gmane.org; Tue, 01 Aug 2017 18:05:30 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:43890) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dcfHV-00076j-79 for guile-user@gnu.org; Tue, 01 Aug 2017 18:04:50 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1dcfHR-0006l2-6p for guile-user@gnu.org; Tue, 01 Aug 2017 18:04:49 -0400 Original-Received: from relay5.ptmail.sapo.pt ([212.55.154.25]:39237 helo=sapo.pt) by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1dcfHQ-0006gg-Il for guile-user@gnu.org; Tue, 01 Aug 2017 18:04:45 -0400 Original-Received: (qmail 461 invoked from network); 1 Aug 2017 22:04:38 -0000 Original-Received: (qmail 13040 invoked from network); 1 Aug 2017 22:04:37 -0000 Original-Received: from unknown (HELO [192.168.0.19]) (vbuaraujo@sapo.pt@[201.37.162.31]) (envelope-sender ) by ptmail-mta-auth02 (qmail-ptmail-1.0.0) with ESMTPSA for ; 1 Aug 2017 22:04:37 -0000 X-PTMail-RemoteIP: 201.37.162.31 X-PTMail-AllowedSender-Action: X-PTMail-Service: default In-Reply-To: <871sowmri4.fsf@web.de> X-detected-operating-system: by eggs.gnu.org: GNU/Linux 3.x [fuzzy] X-Received-From: 212.55.154.25 X-BeenThere: guile-user@gnu.org X-Mailman-Version: 2.1.21 Precedence: list List-Id: General Guile related discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: guile-user-bounces+guile-user=m.gmane.org@gnu.org Original-Sender: "guile-user" Xref: news.gmane.org gmane.lisp.guile.user:14008 Archived-At: Another possibility beside docstrings would be to add it as a property to the function. I'm not sure if this is a documented feature, but if the first form in a function is a literal vector rather than a string (or in addition to a string, I've just found out!), it will be interpreted as a sequence of (KEY . VAL) properties to the function. For example: (define (double x) "Returns twice the value of a given number." #((examples [(double 5) 10] [(double 0) 0])) (* 2 x)) scheme@(guile-user)> (procedure-properties double) $2 = ((name . double) (documentation . "Returns twice the value of a given number.") (examples ((double 5) 10) ((double 0) 0))) scheme@(guile-user)> (procedure-property double 'examples) $3 = (((double 5) 10) ((double 0) 0)) On 31/07/2017 14:23, Arne Babenhauserheide wrote: > Hi Mark, > > String-literals are a problem I did hit, and I’d be happy to lose that > problem without losing the ease of starting a procedure with tests which > double as automatically verified documentation. > > Mark H Weaver writes: >>> (import (examples doctests)) >>> >>> (define (one) >>> "(test 'foo >>> (test-equal 1 (one)))" >>> 1) >> >> While it may sometimes be beneficial to include a few >> examples in the documentation, a full test suite does not, IMO, belong >> in the doc string. > > I think there’s a misconception here: These doctests are not intended to > replace a full test suite. They provide simple tests which double as > automatically verified documentation. > > This is why I asked whether what I implemented is too complex (by > providing all of srfi-64 here). If you get clear benefits from > editor-support, the test is typically too complex for a doctest. > However editor-support could be provided as it is for org-mode: By > editing the region in a specialized sub-buffer. > > The tests here are first-of-all intended for humans to read. > > Why does code in string-literals bring a loss of hygiene? I’s read in > the module as if it had been written directly in a lambda and read > during parsing. Am I missing something or are you envisioning mutation > of the string prior to reading and evaluating it? > > Panicz Maciej Godek writes: >> I agree with Mark, that putting tests inside a string in Lisp is a >> terrible idea, because Lisp doesn't have Python's shortcommings, > … >> There is no point in trading something better for something worse merely >> because people from Python (or elsewhere) can't afford this "better". > > This doesn’t correctly represent the situation of Python. It is > perfectly possible in Python to write tests in literal code — for > example by using attributes of a function to hold functions which run > the tests. > > What doctests provide is a way to write example usage first and foremost > for humans, directly at the top of the function definition, and have it > checked automatically to ensure that these examples in auto-generated > documentation actually work and keep working. > > Using a define-with-tests (or define-with-examples) does not allow > writing for humans first, so it does not reach feature-parity. I could > use pretty-print to create an examples section of the documentation, but > I won’t know how it is going to be formatted while writing the code. > (though this need not be a pure drawback) > > This is why I’m looking into doctests in the first place. If you have > something which provides feature parity, I’m all for using that > instead. Requirements: > > - Can be verified automatically. > - Becomes part of auto-generated documentation. > - Is "physically" close to the definition of the procedure (same file, > no other definitions between the tests/examples and the procedure). > > Ideally it should look like what I’d run in the REPL to use the > procedure, but I don’t think that this must be a hard requirement. > > Best wishes, > Arne > -- Vítor De Araújo https://elmord.org/