[PATCH] Fixing documentation typos and omission, better formatting

Hello Alexandria developers,

attached is the patch that fixes some typos, omissions and formatting
in alexandria manual. Note that the manual at
http://common-lisp.net/project/alexandria/draft/alexandria.pdf is
outdated.

I had to manually comment fun-alexandria-sans.info entry, as this file
is not generated by docstring.lisp. I have no idea why :( - could it
be related to inlining?

Also, while compiling the pdf, I've noticed a bug in docstring.lisp:
title names for functions like
(defun (setf something) ...) should be surrounded by '{}'. An obvious
patch for that is also attached.

Best Regards,
Victor

_______________________________________________
alexandria-devel mailing list
alexandria-devel <at> common-lisp.net
http://common-lisp.net/cgi-bin/mailman/listinfo/alexandria-devel

Re: Anonymous modify macros through `CALLF'

On 9/13/07, Tobias C. Rittweiler <tcr <at> freebits.de> wrote:

> Alexandria seems to contain a lot of modify macro definitions. Which is
> no wonder, as those are quite practical: They're concise, and
> simultaneously guarantee that their arguments are only evaluated once.
>
> Inspired from CL.el in Emacs, I grew quite fond of CALLF which is a
> generalized modify macro, or if you look from the right angle, an
> anonymous modify macro facility.
>
> Instead of having to globally define modify macros each time you want
> one for a certain function, you simply use CALLF instead:
>
>  (callf #'append place l1 l2 l3 ...) == (appendf place l1 l2 l3)
>
>  (callf #'coerce place 'foo) == (coercef place 'foo)
>
>  and so on.

It may be just never having seen this before, but I admit this makes
me squint a bit. Having now fooled a bit with alternative ways to write
eg. DROP, I have to admit these are appealingly simple to use.

If nothing else, I think CALLF-N should index arguments from zero -- unless
there is a specific reason for starting from 1? (PROG1 / PROG2 analogue
actually just came to mind, maybe 1 is right after all.)

...then again, we _are_ going to run the pruning pass over Alexandria.
So I'll probably push these soonish, and we can see how using them feels.

Next steps

I last said something about this 6 months ago... I think it's time to close the
floodgates for version 1 any day now.

IMPORTANT: If there are people with patches languishing in the archives, who
would like to see them merged, please holler before the end of this month.

Likewise, if there are people with "you're still missing X" grievances, please
report them before the end of this month.

Likewise, if there are Alexandria hackers with pending _new_ additions, please
push them (or at least tell us about them) before the end of this month.

Starting February 1st, Alexandria version 1 will not be added to
anymore -- things
may still be changed and dropped, and all sorts of funky stuff may happen, but
new additions will have to wait for the start of Alexandria 2 cycle.

(Assuming this is all right with the veto-enabled people.)

Cheers,

 -- Nikodemus

Re: Next steps

"Nikodemus Siivola" <nikodemus <at> random-state.net> writes:

> Starting February 1st, Alexandria version 1 will not be added to
> anymore -- things may still be changed and dropped, and all sorts of
> funky stuff may happen, but new additions will have to wait for the
> start of Alexandria 2 cycle.

Please push that deadline until mid / end of march because upcoming
weeks and the following months is exams time (at least for me), so
academic people may be quite busy right now.

  -T.

Re: Re: Next steps

On 1/16/08, Tobias C. Rittweiler <tcr <at> freebits.de> wrote:
> "Nikodemus Siivola" <nikodemus <at> random-state.net> writes:
>
> > Starting February 1st, Alexandria version 1 will not be added to
> > anymore -- things may still be changed and dropped, and all sorts of
> > funky stuff may happen, but new additions will have to wait for the
> > start of Alexandria 2 cycle.
>
> Please push that deadline until mid / end of march because upcoming
> weeks and the following months is exams time (at least for me), so
> academic people may be quite busy right now.

Oh well, Alexandria is sufficiently glacial that what's another
two months between friends?

So, new-feature-freeze starting 1st of April 2008. (?)

Cheers,

 -- Nikodemus

MAYBECALL

I'd like to propose the addition of the following function:

  (defun maybecall (bool fn &rest args)
    "Call FN with ARGS if BOOL is T. Otherwise return ARGS as multiple values."
    (if bool (apply fn args) (values-list args)))

MAYBECALL is the general, or anonymous, solution to many ensure-foo
problems.

  (maybecall (not (listp thing)) #'list thing) == (ensure-list thing)

  (maybecall (listp thing) #'car thing) == (ensure-car thing)

I've thought about naming it FUNCALL-IF, but that could be read as
taking a predicate function a la all the sequence functions, rather than
a boolean value. And the result of making it take a predicate

  (funcall-if #'listp #'car thing)

is not so nice if you want the call not to depend directly on the
arguments passed. E.g. a use case where I often use MAYBECALL is to call
a function depending on a flag (most often argument to the surrounding
function.)

I.e.

   (maybecall removep #'remove foo bars)

vs.

SOMETIMES

I'd also like to propose the following addition:

  (defun sometimes (test then &optional (else nil else-p))
    "Returns a function that applies TEST on its arguments and returns
    either THEN or ELSE depending on the test result.

    If ELSE is not provided, the arguments passed to the returned function
    are returned as multiple values.

    Examples:

    (mapcar (sometimes #'plusp 1 -1) '(1 -1 2 -2 3 -3))

      ==> (1 -1 1 -1 1 -1)

    (mapcar (sometimes #'minusp 0) '(1 -1 2 -2 3 -3))

      ==> (1 0 2 0 3 0)
    "
    (flet ((%sometimes (&rest args)
             (if (apply test args)
                 then
                 (if else-p else (values-list args)))))
      #'%sometimes))

It's in the same spirit as CONSTANTLY, which is also the reason for its
name. (SOMETIMES #'PLUSP 1 -1) can be read as

  sometimes 1, sometimes -1, depending on PLUSP.

Re: MAYBECALL

>   (maybecall (not (listp thing)) #'list thing) == (ensure-list thing)

i don't see in which aspect it is better than writing

(unless (listp thing)
  (list thing))

note that the rationale for ensure-list is that it's actually a bit
shorter and also encodes the intention in a way that is much easier
for a human to process (which, imho, can not be said for maybecall).

just my 0.02

--

-- 
 attila

Re: MAYBECALL

"Attila Lendvai" <attila.lendvai <at> gmail.com> writes:

>>   (maybecall (not (listp thing)) #'list thing) == (ensure-list thing)
>
> i don't see in which aspect it is better than writing
>
> (unless (listp thing)
>   (list thing))

This would return NIL if THING is not a list. MAYBECALL behaves like a
identity function in that case, making it practical for chaining.

> note that the rationale for ensure-list is that it's actually a bit
> shorter and also encodes the intention in a way that is much easier
> for a human to process (which, imho, can not be said for maybecall).

I haven't said anything about taking ENSURE-LIST &c out. MAYBECALL
behaves to ENSURE-FOO as LAMBDA behaves to DEFUN/FLET.

An advantage of FUNCALL-IF is also single evaluation of its arguments,
so I actually opt for its inclusion.

  -T.c

Re: SOMETIMES

On 1/17/08, Tobias C. Rittweiler <tcr <at> freebits.de> wrote:

> I'd also like to propose the following addition:

I'm still on the fence re MAYBECALL, but this one I say no to. IMO the amount
of symbols already exported is possibly too large, and unless you see this
regularly, this is going to be a lot slower to read then

 (lambda (x)
   (if (test x) <then> <else>))

and not that much better to write.

I suspect there is also a stylistic issue of "when to LAMBDA and when to DEFUN
a generator" here. There are already borderline items in Alexandria
like OF-TYPE,
which despite the amusingly punny name and hopefully obvious meaning is maybe
_too_ trivial.

A word on my logic here: Alexandria wants to be widely used, and make it easier
to not just write, but also to read CL programs. Hence, I strongly believe that
symbols exported by Alexandria should fall into the following categories

 * Traditional: ONCE-ONLY, WITH-GENSYMS, etc.

 * Name is sufficient documentation for reading the code. FORMAT-SYMBOL,
   HASH-TABLE-ALIST, LASTCAR, REQUIRED-ARGUMENT, etc. MAYBECALL... maybe. :)

 * Seldom used, but _really_ convenient when you need them. I suspect CALLF
   is one of these, as long as it is use pretty much only for writing modify