Re: A thought for later -- POD tables
L:uke, just a note before I reply to you specifically: I understand your concerns, and I have no interest in blurring the line between presentation and markup, which I think ultimately is where your concern comes from. In fact, if you re-read what I wrote (and what I write below), you'll see that I take great pains to make sure that that's not the case. Luke Palmer wrote: I don't want to read perlpod to figure out how to write a table. Well then don't. No one is prying ASCII-art tables out of your hands here. I just write my table and it works as long as I indent. Sure, it won't be as pretty when it gets turned into HTML or LaTeX, but the point is, that it's readable when it gets there in any case. The point of documentation isn't to be pretty Pretty is not the issue. The issue is markup. If, for example, I happen to be blind, and I'm reading Perl documentation via a text-to-speech program, it may well know how to take an HTML document and read "a table" to me in some reasonable way, but if you hand it a pre-formatted block of text that is supposed to LOOK like a table, I'm pretty (no pun intended) much SOL. Ok, so that's an extreme example (though, I have a mostly blind friend who might not think so). How about the simple fact that S4 is supposed to be a "living document", but if Larry wants to change that table, he has to go in and re-hand-format that entire ASCII-art picture of it! I know that I've avoided making changes to tables in my documentation at work for EXACTLY that reason. If you have a table markup, then you can add or remove a column with minimal pain. If you just wanted to draw your documentation using ASCII-art, then there would be no need for POD at all. You would simply write plain text. The point behind POD was to make writing documentation for diverse markup systems more reasonable. Such markup systems all have the ability to format a table, so why exactly would you not want to take advantage of that? What happens when Larry w Also, you pointed out that my example was hard to read, but you only pointed out the particularly complex example (where I WANTED to demonstrate all of the complex cases), not the simple one. The general case would probably look like: H< Function | Returns > T< foo | nothing > T< bar | a number between 1 and 1000 > T< baz | your program as a string > That's certainly no harder to read than an ASCII-art table, and provides you with many more options in terms of presentation, accessibility and the ability to post-process the documentation (e.g. to extract information in an automated way).
Re: Synopsis 2 draft 1 -- each and every
On Fri, 20 Aug 2004, Dan Hursh wrote:
> Peter Behroozi wrote:
>
> > I'm not particular to any of the verbs used yet, but maybe that's
> > because I don't think of the <> as a general iterator, but more of a
> > gobbler-type creature (and formerly a globber, too). Could we try:
> >
> > for $foo.fetch { ... } #or
> > for $foo.grab { ... } #or
> > for $foo.eat { ... }
> >
> > And to replace $/ we could have something like:
> >
> > for $foo.fetch :upto(",") { ... } #or
> > for $foo.fetch :until(",") { ... }
>
> general impose scalar impose list
> --- --
>D $foo.eat$foo.bite $foo.gobble
>N $foo.look $foo.peek $foo.peruse
>
> hmm, I don't like eat in this case
>
>D $foo.take $foo.grab $foo.horde
D $foo.drink $foo.sip$foo.slurp
N $foo.taste
Ok, I'll stop now. But I do sort of (very minorly) like sip as a mini-slurp.
>
> That assumes folks think of grab as being singular and take as being
> open ended. That, and I don't want take to colide with gather{take}.
> Oh well.
>
> Dan
>
--
Adam Lopresto
http://cec.wustl.edu/~adam/
Keyboard not found. Think F1 to continue.
Re: "<->" as "->" with automatic "is rw"
On Fri, 20 Aug 2004, Larry Wall wrote:
> On Fri, Aug 20, 2004 at 10:07:02PM +0200, Juerd wrote:
> : I'm proposing
> :
> : for zip(@foos, @bars, @xyzzies) <-> $foo, $bar, $xyzzy { ... }
> : for %quux.kv <-> $key, $value { ... }
>
> That'd probably work on the keys only if the hash was declared to have
> object keys. At least in Perl 5, the key is always a copy.
>
> : to mean
> :
> : for zip(@foos, @bars, @xyzzies) -> $foo is rw, $bar is rw, $xyzzy is rw { ... }
> : for %quux.kv -> $key is rw, $value is rw { ... }
> :
> : Comments, anyone?
>
> It's really sick, and cute, and I love it. Unfortunately I'm not sure
> it passes the "Are there already too many ways to declare a sub?" test...
>
> It's vaguely possible I could be persuaded on the basis that
>
> for zip @a ¥ @b <-> { ($^a,$^b) = ($^b,$^a) }
>
> could be made to work. But I'm still dubious. And arguably -> {...}
> means the same as sub () {...}, implying there are no arguments.
Arguably it already means that. But if <-> were added, it might be a good
reason to make -> {...} mean -> $_ {...}, using <-> {...} for -> $_ is rw
{...}. A good way to remove one more special case (maybe offsetting the extra
way to declare a sub, and sweeten the whole deal).
--
Adam Lopresto
http://cec.wustl.edu/~adam/
Yesterday upon the stair
I met a man who wasn't there.
He wasn't there again today --
I think he's from the CIA.
Re: Synopsis 2 draft 1 -- each and every
On 8/20/04, [EMAIL PROTECTED] (Luke Palmer) wrote:
>So all the laziness goes into the array implementation. But you don't
>even need to write your iterator fancily. If you just write your scalar
>version of postcircumfix:<>, Perl will do the rest.
So if you use an iterator in list context, Perl will automatically call it
repeatedly for you?
That still means Perl has to know when something is an iterator, which is
fine for <> (or whatever it ends up being called), but when your object
has different ways to iterate (e.g. .keys, .values, .kv), they'd have to
be defined as "is iterator" or some such.
...or... you could just do the extra not-so-fancy work yourself. Multiple
iterators probably aren't really very common anyway, and it's not that
much work after all to make your own method that iterates lazily:
>method postcircumfix:<> ($self: *%opt) returns List {
>scalar $self.<*%opt>, $self.<*%opt> # [1]
>}
>If I write it functionally like that, Perl will still do all the rest.
>Laziness is built right in the language.
Ah, nice! But doesn't the scalar definition need to be part of the method
too?
method postcircumfix:<> ($self: *%opt) returns Scalar|List #??
{
given want
{
when Scalar { get_next_value, increment_counter, etc; }
when List { return scalar $self.<*%opt>, list $self.<*%opt>; }
# hm, what about void context?
# (should probably iterate once, like scalar context)
}
}
Or can you define separate methods for scalar and list contexts, and have
Perl call whichever one is appropriate? (Which would be neat...
polymorphism from the other end.)
-David "polly going crackers" Green
Re: A thought for later -- POD tables
> > $_ $xType of Match ImpliedMatching Code > > == = == > > Any Code<$> scalar sub truth match if $x($_) How about making paragraphs that have a line like the divider one above special? By simply parsing the = lines, it's easy to make it a table for formatters that understand tables, and you have full control over how things look in plain text. It would mean being a little more careful with the lines, as they should indicate column width, and not just end at the end of the column header. Podchecker can of course be made to warn if there is non-whitespace in a column that had an = in the divider (now: column specification) line. $_ $xType of Match ImpliedMatching Code - == = == + == === == Any Code<$> scalar sub truth match if $x($_) An HTML formatter could generate code like: $_ $x Type of Match Implied Matching Code Any Code<$> scalar sub truth match if $x($_) I haven't thought of a solution for non-verbatim cells yet. I'm not convinced that they are needed. Juerd
Re: "<->" as "->" with automatic "is rw"
Larry Wall skribis 2004-08-20 13:31 (-0700): > Unfortunately I'm not sure it passes the "Are there already too many > ways to declare a sub?" test... I'm not seeing it as another way. Technically, of course it is different, but by the user, <-> and -> will probably be seen as one thing, with one of them being the other's specialized form. > It's really sick Sick would be if <- were introduced to make the variable write-only ;) W R @foos -> $foo @foos <-> $foo @foos <- $foo It would be consistent, though... Juerd
Re: Return with no expression
Larry Wall wrote: On Fri, Aug 20, 2004 at 09:21:02AM +0100, Matthew Walton wrote: : It would be nice if rand behaved a bit more sanely in Perl 6. I can : understand the reasoning for making rand 0 produce between 0 and 1, but : that doesn't mean I have to like it. What makes you think there was any "reasoning" involved? As far as I can recall, it was entirely due to random factors. :-) Sush, I'm giving you credit from pure blind faith here ;-) I suspect there's an argument that [0,0) ought to be considered undef (which would conveniently numerify to 0 with an optional warning). In the absence of a paradox value, undef would be fine there I think :-)
Re: A thought for later -- POD tables
Luke Palmer wrote: Aaron Sherman writes: <> H< C<$_> | C<$x> | Type of Match Implied | Matching Code > T< Any | CodeC<< <$> >> | scalar sub truth | match if C<$x($_)> > Oh, and BTW: My mailer seems to have snuck some extra noise in there. I think it got confused and thought there was inline quoting going on. That leading C<< <> >> should not be there. One of the things I was trying to demonstrate here was the fact that, even though, you could now have C, L (hey! imagine perl.com no longer having to hack perl.pod to make each manpage reference into a link!), or whatever other markup inside a table correctly, you could still visually line up the information so that when viewing the talble as plain text, it was still just as readable as C<$_> C<$x> etc ever was. Woefully, my mailer thought that such clarity was a bad idea ;-)
Re: Return with no expression
Matthew Walton wrote: Larry Wall wrote: I suspect there's an argument that [0,0) ought to be considered undef (which would conveniently numerify to 0 with an optional warning). In the absence of a paradox value, undef would be fine there I think :-) Too bad we don't have NaRN (Not a Random Number)... that's in the IEEE spec, isn't it? ;-)
Re: Return with no expression
> "AS" == Aaron Sherman <[EMAIL PROTECTED]> writes: AS> Matthew Walton wrote: >> Larry Wall wrote: >> >>> I suspect there's an argument that [0,0) ought to be considered undef >>> (which would conveniently numerify to 0 with an optional warning). >> >> In the absence of a paradox value, undef would be fine there I think :-) AS> Too bad we don't have NaRN (Not a Random Number)... that's in the IEEE AS> spec, isn't it? ;-) no, narns are in the babylon 5 bible! :) uri -- Uri Guttman -- [EMAIL PROTECTED] http://www.stemsystems.com --Perl Consulting, Stem Development, Systems Architecture, Design and Coding- Search or Offer Perl Jobs http://jobs.perl.org
Re: A thought for later -- POD tables
Aaron Sherman writes: > Also, you pointed out that my example was hard to read, but you only > pointed out the particularly complex example (where I WANTED to > demonstrate all of the complex cases), not the simple one. The general > case would probably look like: > >H< Function | Returns > >T< foo | nothing > >T< bar | a number between 1 and 1000 > >T< baz | your program as a string > You said that your mailer screwed up in the other one. I saw misalgined columns and some weird stuff in there and so I immediately deemed it non PODish. Now that I look more carefully and that I see this table, your proposal seems much more viable. On the other hand, Larry had a good point. Why couldn't we do: =begin table ... =end table For some sufficiently simple ...? Obviously this gives the formatter control over how the table is formatted, which is arguably a bad thing since it won't be implemented (POD tools are mostly lazy about that kind of thing). So I'm starting to like it. I do think that it should be left aligned, as it'll be verbatim text if it's indented. We might want a =begin/=end table around it anyway, to avoid making the formatters do too much bookkeeping. Luke > That's certainly no harder to read than an ASCII-art table, and provides > you with many more options in terms of presentation, accessibility and > the ability to post-process the documentation (e.g. to extract > information in an automated way). >
Re: Synopsis 2 draft 1 -- each and every
David Green writes:
> On 8/20/04, [EMAIL PROTECTED] (Luke Palmer) wrote:
> >So all the laziness goes into the array implementation. But you don't
> >even need to write your iterator fancily. If you just write your scalar
> >version of postcircumfix:<>, Perl will do the rest.
>
> So if you use an iterator in list context, Perl will automatically call it
> repeatedly for you?
> That still means Perl has to know when something is an iterator, which is
> fine for <> (or whatever it ends up being called), but when your object
> has different ways to iterate (e.g. .keys, .values, .kv), they'd have to
> be defined as "is iterator" or some such.
Since operators are going to be less DWIMmy this time around, I suppose
I should have said "Perl does the rest if your class does iterator". So
the iterator role would define the listy version for you.
> >method postcircumfix:<> ($self: *%opt) returns List {
> >scalar $self.<*%opt>, $self.<*%opt> # [1]
> >}
> >If I write it functionally like that, Perl will still do all the rest.
> >Laziness is built right in the language.
>
> Ah, nice! But doesn't the scalar definition need to be part of the method
> too?
>
> method postcircumfix:<> ($self: *%opt) returns Scalar|List #??
> {
> given want
> {
> when Scalar { get_next_value, increment_counter, etc; }
> when List { return scalar $self.<*%opt>, list $self.<*%opt>; }
> # hm, what about void context?
> # (should probably iterate once, like scalar context)
> }
> }
>
> Or can you define separate methods for scalar and list contexts, and have
> Perl call whichever one is appropriate? (Which would be neat...
> polymorphism from the other end.)
That was the idea, but I realize that I did it wrong. I also realize
that there isn't a right way yet. Dispatching on return value is
something that is pretty hard to implement, and impossible to implement
correctly, as it has a tendency to create paradoxes.
So for now I'd say that you have to put them both in the same method.
Which seems to imply that the iterator role would look for a method name
to use for scalar context. Like sip :-)
Luke
Re: A thought for later -- POD tables
Maybe this train has already left the station, but I find myself preferring Kwiki syntax to POD these days... any chance we could use Kwiki with WAFL for the Perl 6 POD? That of course has already got tables. (Still bracketing with the =for ... =cut directives, though.) Just a thought... -- Peter Scott
Re: A thought for later -- POD tables
Luke Palmer wrote: On the other hand, Larry had a good point. Why couldn't we do: =begin table ... =end table For some sufficiently simple ...? Obviously this gives the formatter control over how the table is formatted, which is arguably a bad thing since it won't be implemented (POD tools are mostly lazy about that kind of thing). There's nothing wrong with that. For long tables it would be more efficient, but for shorter tables it would be a tad more cumbersome. The only thing I wanted to avoid (like the plague) was an C<=>-introduced set of table elements like C<=cell> and so on. That would lead to a very anti-POD visual breakdown. So I'm starting to like it. I do think that it should be left aligned, as it'll be verbatim text if it's indented. We might want a =begin/=end table around it anyway, to avoid making the formatters do too much bookkeeping. A begin/end would also allow for paragraphs inside of table elements. You get to decide if that's a good or bad thing ;-)
Re: "<->" as "->" with automatic "is rw"
Juerd <[EMAIL PROTECTED]> writes:
> Sick would be if <- were introduced to make the variable write-only ;)
Sicker still would be if - were introduced to make the variable
neither readable nor writeable. HTH.HAND.
--
$;=sub{$/};@;=map{my($a,$b)=($_,$;);$;=sub{$a.$b->()}}
split//,"[EMAIL PROTECTED]/ --";$\=$ ;-> ();print$/
