Re: Guile vectors

[Ian Price <ianprice90@googlemail.com>]

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

Dmitry Bogatov <KAction@gnu.org> writes:

> Documentation for vectors says:
> 	Like lists, vectors have to be quoted:

Which is wrong, vectors are self quoting.

> Altho:
>         (define foo #((+ 1 2) 2))
>         (eq? foo (eval foo (current-module))) ;; #t

And that is a weird example you've chosen, as I don't expect eval to
eval a vector, I'd have just printed it. 

> Am I missing something, or documentation is not in sync with current
> state of art?

The latter, though there is no penalty (performance or stylistic) if you
are quoting your vectors.

I've done a git grep though the docs, and there are a few referenes to
it in texi files.

- r5rs.texi should _not_ be change, since r5rs says vectors must be quoted.
- guile.texi is autogenerated
- api-evaluation.texi has an example in the section on quoting
- api-compound.texi

The last one is the only one that needs to be changed IMO.

Most of the other references are in code or tests where they do no harm,
but I'm not sure about vectors.c. There it appears in comments (which
might be snarfed into guile.texi?) and one uncommented docstring. Is it
worth changing?

Patch attached that changes api-compound.texi. I split the paragraph to
make it easier.

-- 
Ian Price -- shift-reset.com

"Programming is like pinball. The reward for doing it well is
the opportunity to do it again" - from "The Wizardy Compiled"


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: self quoting fix --]
[-- Type: text/x-patch, Size: 2547 bytes --]

From ddda4d53e588441e15b39c36033ed7f425fa3895 Mon Sep 17 00:00:00 2001
From: Ian Price <ianprice90@googlemail.com>
Date: Wed, 9 Oct 2013 22:48:16 +0100
Subject: [PATCH] Doc: mention vectors are self-quoting

Reported by Dmitry Bogatov <KAction@gnu.org>.

* doc/ref/api-compound.texi (Vector Syntax, Vector Creation): Mention
  that vectors are self-quoting. Remove examples with quote signs.
---
 doc/ref/api-compound.texi | 22 +++++++++-------------
 1 file changed, 9 insertions(+), 13 deletions(-)

diff --git a/doc/ref/api-compound.texi b/doc/ref/api-compound.texi
index 1990d77..94e0145 100644
--- a/doc/ref/api-compound.texi
+++ b/doc/ref/api-compound.texi
@@ -689,22 +689,18 @@ Vectors can literally be entered in source code, just like strings,
 characters or some of the other data types.  The read syntax for vectors
 is as follows: A sharp sign (@code{#}), followed by an opening
 parentheses, all elements of the vector in their respective read syntax,
-and finally a closing parentheses.  The following are examples of the
-read syntax for vectors; where the first vector only contains numbers
-and the second three different object types: a string, a symbol and a
-number in hexadecimal notation.
+and finally a closing parentheses.  Like strings, vectors do not have to
+be quoted.
+
+The following are examples of the read syntax for vectors; where the
+first vector only contains numbers and the second three different object
+types: a string, a symbol and a number in hexadecimal notation.
 
 @lisp
 #(1 2 3)
 #("Hello" foo #xdeadbeef)
 @end lisp
 
-Like lists, vectors have to be quoted:
-
-@lisp
-'#(a b c) @result{} #(a b c)
-@end lisp
-
 @node Vector Creation
 @subsubsection Dynamic Vector Creation and Validation
 
@@ -735,7 +731,7 @@ The inverse operation is @code{vector->list}:
 Return a newly allocated list composed of the elements of @var{v}.
 
 @lisp
-(vector->list '#(dah dah didah)) @result{}  (dah dah didah)
+(vector->list #(dah dah didah)) @result{}  (dah dah didah)
 (list->vector '(dididit dah)) @result{}  #(dididit dah)
 @end lisp
 @end deffn
@@ -796,8 +792,8 @@ Return the number of elements in @var{vec} as a @code{size_t}.
 Return the contents of position @var{k} of @var{vec}.
 @var{k} must be a valid index of @var{vec}.
 @lisp
-(vector-ref '#(1 1 2 3 5 8 13 21) 5) @result{} 8
-(vector-ref '#(1 1 2 3 5 8 13 21)
+(vector-ref #(1 1 2 3 5 8 13 21) 5) @result{} 8
+(vector-ref #(1 1 2 3 5 8 13 21)
     (let ((i (round (* 2 (acos -1)))))
       (if (inexact? i)
         (inexact->exact i)
-- 
1.7.11.7