Re: read-line is limited to 4095 chars

[Juraj Martinka]

I'm running on Mac OS X Sierra with Clojure 1.8.
I have to admit that behavior when trying to read a long line in 
terminal/repl is a bit odd (it may be the limitation of terminal).
However, If I try this via input from the text file it works properly:

wc -c very-long-line.txt
8101 very-long-line.txt

java -cp 
/Users/jumar/.m2/repository/org/clojure/clojure/1.8.0/clojure-1.8.0.jar 
clojure.main read-line.clj < very-long-line.txt
8100

Note: I actually put 8100 chars into the file, so 8101 reported by wc 
probably includes new line character.


On Tuesday, 26 September 2017 18:12:37 UTC+2, baptiste...@oscaro.com wrote:
>
> > I'm not experiencing this on Windows...  Could it be that your 
> > terminal or tooling is limiting the input to 4096 characters?
>
> Are you able to read more than 8k characters?
>
> Le mardi 26 septembre 2017 16:56:24 UTC+2, David Powell a écrit :
>>
>> I'm not experiencing this on Windows...  Could it be that your 
>> terminal or tooling is limiting the input to 4096 characters? 
>>
>> On Tue, Sep 26, 2017 at 2:20 PM, Alex Miller  
>> wrote: 
>> > Please file a jira enhancement. Changes could include updating the doc 
>> > string, or adding a new arity to read-line that takes a size and passes 
>> it 
>> > through to the buffered reader. 
>> > 
>> > 
>> > On Tuesday, September 26, 2017 at 6:28:26 AM UTC-5, 
>> > baptiste...@oscaro.com wrote: 
>> >> 
>> >> Hello there, 
>> >> 
>> >> I was using read-line to read a large line and found it limits its 
>> input 
>> >> to 4095 chars. I tested this on both Clojure 1.8.0 and 1.9.0-beta1. 
>> >> 
>> >> Steps to reproduce: 
>> >> 
>> >> $ lein new foo 
>> >> $ cd foo 
>> >> $ lein repl 
>> >> ... 
>> >> => (count (read-line)) 
>> >> 
>> >> Then enter a line that’s longer than 4095 characters; I used 8000 a's. 
>> >> 
>> >> Expected output: 
>> >> 
>> >> 8000 
>> >> 
>> >> Actual output: 
>> >> 
>> >> 4095 
>> >> 
>> >> No matter the real length of your input, it’ll always be truncated to 
>> 4095 
>> >> chars if it’s longer. 
>> >> 
>> >> This is not in the documentation so I assume it’s either an 
>> implementation 
>> >> bug or a documentation miss. I wanted to know which one it is before 
>> trying 
>> >> to fix it. 
>> >> 
>> >> I’ve done some research and it appears to be a limitation of the 
>> >> BufferedReader’s readLine method that uses a buffer of either 4k or 8k 
>> >> depending on the implementation. Should we (1) work around this limit 
>> in the 
>> >> code so that read-line does actually read a whole line or (2) just 
>> update 
>> >> the documentation to note this limit? 
>> >> 
>> >> Thanks, 
>> >> 
>> >> -- Baptiste Fontaine 
>> > 
>> > -- 
>> > You received this message because you are subscribed to the Google 
>> > Groups "Clojure" group. 
>> > To post to this group, send email to clo...@googlegroups.com 
>> > Note that posts from new members are moderated - please be patient with 
>> your 
>> > first post. 
>> > To unsubscribe from this group, send email to 
>> > clojure+u...@googlegroups.com 
>> > For more options, visit this group at 
>> > http://groups.google.com/group/clojure?hl=en 
>> > --- 
>> > You received this message because you are subscribed to the Google 
>> Groups 
>> > "Clojure" group. 
>> > To unsubscribe from this group and stop receiving emails from it, send 
>> an 
>> > email to clojure+u...@googlegroups.com. 
>> > For more options, visit https://groups.google.com/d/optout. 
>>
>
> Le mardi 26 septembre 2017 16:56:24 UTC+2, David Powell a écrit :
>>
>> I'm not experiencing this on Windows...  Could it be that your 
>> terminal or tooling is limiting the input to 4096 characters? 
>>
>> On Tue, Sep 26, 2017 at 2:20 PM, Alex Miller  
>> wrote: 
>> > Please file a jira enhancement. Changes could include updating the doc 
>> > string, or adding a new arity to read-line that takes a size and passes 
>> it 
>> > through to the buffered reader. 
>> > 
>> > 
>> > On Tuesday, September 26, 2017 at 6:28:26 AM UTC-5, 
>> > baptiste...@oscaro.com wrote: 
>> >> 
>> >> Hello there, 
>> >> 
>> >> I was using read-line to read a large line and found it limits its 
>> input 
>> >> to 4095 chars. I tested this on both Clojure 1.8.0 and 1.9.0-beta1. 
>> >> 
>> >> Steps to reproduce: 
>> >> 
>> >> $ lein new foo 
>> >> $ cd foo 
>> >> $ lein repl 
>> >> ... 
>> >> => (count (read-line)) 
>> >> 
>> >> Then enter a line that’s longer than 4095 characters; I used 8000 a's. 
>> >> 
>> >> Expected output: 
>> >> 
>> >> 8000 
>> >> 
>> >> Actual output: 
>> >> 
>> >> 4095 
>> >> 
>> >> No matter the real length of your input, it’ll always be truncated to 
>> 4095 
>> >> chars if it’s longer. 
>> >> 
>> >> This is not in the documentation so I assume it’s either an 
>> implementation 
>> >> bug or a documentation miss. I wanted to know which one it is before 
>> trying 
>> >> to fix it. 
>> >> 
>> >> I’ve done some research and it appears to be a limitation of the 
>> 

[ANN] data.xml 0.2.0-alpha3

[Herwig Hochleitner]

data.xml is a Clojure contrib library that parses and emits XML.

Github: https://github.com/clojure/data.xml
Changelog: https://github.com/clojure/data.xml/blob/master/CHANGES.md

Information on updating the dependency is here
.

0.2.0-alpha3 features the ability to emit empty elements as self-closing
tags. This came at the cost of implementing xml namespace tracking, due to
bug in the jdk's xml library. On the other hand, this is a major building
block for getting a platform-independent parser/emitter. The implementation

takes full advantage of transients to get maximum performance, but please
report if you notice any performance degradation when switching from -alpha2

0.2.0-alpha3 also fixes clojure.core/empty for the element deftype.
Apologies for holding up the release on this critical fix.

Thanks to @WickedShell, to all data.xml contributors and to @dominicm for
prodding me to do the release!

-- 
You received this message because you are subscribed to the Google
Groups "Clojure" group.
To post to this group, send email to clojure@googlegroups.com
Note that posts from new members are moderated - please be patient with your 
first post.
To unsubscribe from this group, send email to
clojure+unsubscr...@googlegroups.com
For more options, visit this group at
http://groups.google.com/group/clojure?hl=en
--- 
You received this message because you are subscribed to the Google Groups 
"Clojure" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to clojure+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Generative testing of Ring web apps

[Steve Buikhuizen]

Hi all, in case this is useful to the community, I thought I'd share the 
repo I used in a talk at Clojure Sydney last night.

https://github.com/stevebuik/stateful-generative-tests

Enjoy!

-- 
You received this message because you are subscribed to the Google
Groups "Clojure" group.
To post to this group, send email to clojure@googlegroups.com
Note that posts from new members are moderated - please be patient with your 
first post.
To unsubscribe from this group, send email to
clojure+unsubscr...@googlegroups.com
For more options, visit this group at
http://groups.google.com/group/clojure?hl=en
--- 
You received this message because you are subscribed to the Google Groups 
"Clojure" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to clojure+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: read-line is limited to 4095 chars

[baptiste . fontaine]

> I'm not experiencing this on Windows...  Could it be that your 
> terminal or tooling is limiting the input to 4096 characters?

Are you able to read more than 8k characters?

Le mardi 26 septembre 2017 16:56:24 UTC+2, David Powell a écrit :
>
> I'm not experiencing this on Windows...  Could it be that your 
> terminal or tooling is limiting the input to 4096 characters? 
>
> On Tue, Sep 26, 2017 at 2:20 PM, Alex Miller  > wrote: 
> > Please file a jira enhancement. Changes could include updating the doc 
> > string, or adding a new arity to read-line that takes a size and passes 
> it 
> > through to the buffered reader. 
> > 
> > 
> > On Tuesday, September 26, 2017 at 6:28:26 AM UTC-5, 
> > baptiste...@oscaro.com  wrote: 
> >> 
> >> Hello there, 
> >> 
> >> I was using read-line to read a large line and found it limits its 
> input 
> >> to 4095 chars. I tested this on both Clojure 1.8.0 and 1.9.0-beta1. 
> >> 
> >> Steps to reproduce: 
> >> 
> >> $ lein new foo 
> >> $ cd foo 
> >> $ lein repl 
> >> ... 
> >> => (count (read-line)) 
> >> 
> >> Then enter a line that’s longer than 4095 characters; I used 8000 a's. 
> >> 
> >> Expected output: 
> >> 
> >> 8000 
> >> 
> >> Actual output: 
> >> 
> >> 4095 
> >> 
> >> No matter the real length of your input, it’ll always be truncated to 
> 4095 
> >> chars if it’s longer. 
> >> 
> >> This is not in the documentation so I assume it’s either an 
> implementation 
> >> bug or a documentation miss. I wanted to know which one it is before 
> trying 
> >> to fix it. 
> >> 
> >> I’ve done some research and it appears to be a limitation of the 
> >> BufferedReader’s readLine method that uses a buffer of either 4k or 8k 
> >> depending on the implementation. Should we (1) work around this limit 
> in the 
> >> code so that read-line does actually read a whole line or (2) just 
> update 
> >> the documentation to note this limit? 
> >> 
> >> Thanks, 
> >> 
> >> -- Baptiste Fontaine 
> > 
> > -- 
> > You received this message because you are subscribed to the Google 
> > Groups "Clojure" group. 
> > To post to this group, send email to clo...@googlegroups.com 
>  
> > Note that posts from new members are moderated - please be patient with 
> your 
> > first post. 
> > To unsubscribe from this group, send email to 
> > clojure+u...@googlegroups.com  
> > For more options, visit this group at 
> > http://groups.google.com/group/clojure?hl=en 
> > --- 
> > You received this message because you are subscribed to the Google 
> Groups 
> > "Clojure" group. 
> > To unsubscribe from this group and stop receiving emails from it, send 
> an 
> > email to clojure+u...@googlegroups.com . 
> > For more options, visit https://groups.google.com/d/optout. 
>

Le mardi 26 septembre 2017 16:56:24 UTC+2, David Powell a écrit :
>
> I'm not experiencing this on Windows...  Could it be that your 
> terminal or tooling is limiting the input to 4096 characters? 
>
> On Tue, Sep 26, 2017 at 2:20 PM, Alex Miller  > wrote: 
> > Please file a jira enhancement. Changes could include updating the doc 
> > string, or adding a new arity to read-line that takes a size and passes 
> it 
> > through to the buffered reader. 
> > 
> > 
> > On Tuesday, September 26, 2017 at 6:28:26 AM UTC-5, 
> > baptiste...@oscaro.com  wrote: 
> >> 
> >> Hello there, 
> >> 
> >> I was using read-line to read a large line and found it limits its 
> input 
> >> to 4095 chars. I tested this on both Clojure 1.8.0 and 1.9.0-beta1. 
> >> 
> >> Steps to reproduce: 
> >> 
> >> $ lein new foo 
> >> $ cd foo 
> >> $ lein repl 
> >> ... 
> >> => (count (read-line)) 
> >> 
> >> Then enter a line that’s longer than 4095 characters; I used 8000 a's. 
> >> 
> >> Expected output: 
> >> 
> >> 8000 
> >> 
> >> Actual output: 
> >> 
> >> 4095 
> >> 
> >> No matter the real length of your input, it’ll always be truncated to 
> 4095 
> >> chars if it’s longer. 
> >> 
> >> This is not in the documentation so I assume it’s either an 
> implementation 
> >> bug or a documentation miss. I wanted to know which one it is before 
> trying 
> >> to fix it. 
> >> 
> >> I’ve done some research and it appears to be a limitation of the 
> >> BufferedReader’s readLine method that uses a buffer of either 4k or 8k 
> >> depending on the implementation. Should we (1) work around this limit 
> in the 
> >> code so that read-line does actually read a whole line or (2) just 
> update 
> >> the documentation to note this limit? 
> >> 
> >> Thanks, 
> >> 
> >> -- Baptiste Fontaine 
> > 
> > -- 
> > You received this message because you are subscribed to the Google 
> > Groups "Clojure" group. 
> > To post to this group, send email to clo...@googlegroups.com 
>  
> > Note that posts from new members are moderated - please be patient with 
> your 
> > first post. 
> > To unsubscribe from this group, send email to 
> > clojure+u...@googlegroups.com  
> > For more options, visit this group at 
> > 

Re: read-line is limited to 4095 chars

[David Powell]

I'm not experiencing this on Windows...  Could it be that your
terminal or tooling is limiting the input to 4096 characters?

On Tue, Sep 26, 2017 at 2:20 PM, Alex Miller  wrote:
> Please file a jira enhancement. Changes could include updating the doc
> string, or adding a new arity to read-line that takes a size and passes it
> through to the buffered reader.
>
>
> On Tuesday, September 26, 2017 at 6:28:26 AM UTC-5,
> baptiste.fonta...@oscaro.com wrote:
>>
>> Hello there,
>>
>> I was using read-line to read a large line and found it limits its input
>> to 4095 chars. I tested this on both Clojure 1.8.0 and 1.9.0-beta1.
>>
>> Steps to reproduce:
>>
>> $ lein new foo
>> $ cd foo
>> $ lein repl
>> ...
>> => (count (read-line))
>>
>> Then enter a line that’s longer than 4095 characters; I used 8000 a's.
>>
>> Expected output:
>>
>> 8000
>>
>> Actual output:
>>
>> 4095
>>
>> No matter the real length of your input, it’ll always be truncated to 4095
>> chars if it’s longer.
>>
>> This is not in the documentation so I assume it’s either an implementation
>> bug or a documentation miss. I wanted to know which one it is before trying
>> to fix it.
>>
>> I’ve done some research and it appears to be a limitation of the
>> BufferedReader’s readLine method that uses a buffer of either 4k or 8k
>> depending on the implementation. Should we (1) work around this limit in the
>> code so that read-line does actually read a whole line or (2) just update
>> the documentation to note this limit?
>>
>> Thanks,
>>
>> -- Baptiste Fontaine
>
> --
> You received this message because you are subscribed to the Google
> Groups "Clojure" group.
> To post to this group, send email to clojure@googlegroups.com
> Note that posts from new members are moderated - please be patient with your
> first post.
> To unsubscribe from this group, send email to
> clojure+unsubscr...@googlegroups.com
> For more options, visit this group at
> http://groups.google.com/group/clojure?hl=en
> ---
> You received this message because you are subscribed to the Google Groups
> "Clojure" group.
> To unsubscribe from this group and stop receiving emails from it, send an
> email to clojure+unsubscr...@googlegroups.com.
> For more options, visit https://groups.google.com/d/optout.

-- 
You received this message because you are subscribed to the Google
Groups "Clojure" group.
To post to this group, send email to clojure@googlegroups.com
Note that posts from new members are moderated - please be patient with your 
first post.
To unsubscribe from this group, send email to
clojure+unsubscr...@googlegroups.com
For more options, visit this group at
http://groups.google.com/group/clojure?hl=en
--- 
You received this message because you are subscribed to the Google Groups 
"Clojure" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to clojure+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: read-line is limited to 4095 chars

[Alex Miller]

Please file a jira enhancement. Changes could include updating the doc 
string, or adding a new arity to read-line that takes a size and passes it 
through to the buffered reader.

On Tuesday, September 26, 2017 at 6:28:26 AM UTC-5, 
baptiste.fonta...@oscaro.com wrote:
>
> Hello there, 
>
> I was using read-line to read a large line and found it limits its input 
> to 4095 chars. I tested this on both Clojure 1.8.0 and 1.9.0-beta1. 
>
> Steps to reproduce: 
>
> $ lein new foo 
> $ cd foo 
> $ lein repl 
> ... 
> => (count (read-line)) 
>
> Then enter a line that’s longer than 4095 characters; I used 8000 a's. 
>
> Expected output: 
>
> 8000 
>
> Actual output: 
>
> 4095 
>
> No matter the real length of your input, it’ll always be truncated to 4095 
> chars if it’s longer. 
>
> This is not in the documentation so I assume it’s either an implementation 
> bug or a documentation miss. I wanted to know which one it is before trying 
> to fix it. 
>
> I’ve done some research and it appears to be a limitation of the 
> BufferedReader’s readLine method that uses a buffer of either 4k or 8k 
> depending on the implementation. Should we (1) work around this limit in 
> the code so that read-line does actually read a whole line or (2) just 
> update the documentation to note this limit?
>
> Thanks,
>
> -- Baptiste Fontaine
>

-- 
You received this message because you are subscribed to the Google
Groups "Clojure" group.
To post to this group, send email to clojure@googlegroups.com
Note that posts from new members are moderated - please be patient with your 
first post.
To unsubscribe from this group, send email to
clojure+unsubscr...@googlegroups.com
For more options, visit this group at
http://groups.google.com/group/clojure?hl=en
--- 
You received this message because you are subscribed to the Google Groups 
"Clojure" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to clojure+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

read-line is limited to 4095 chars

[baptiste . fontaine]

Hello there, 

I was using read-line to read a large line and found it limits its input to 
4095 chars. I tested this on both Clojure 1.8.0 and 1.9.0-beta1. 

Steps to reproduce: 

$ lein new foo 
$ cd foo 
$ lein repl 
... 
=> (count (read-line)) 

Then enter a line that’s longer than 4095 characters; I used 8000 a's. 

Expected output: 

8000 

Actual output: 

4095 

No matter the real length of your input, it’ll always be truncated to 4095 
chars if it’s longer. 

This is not in the documentation so I assume it’s either an implementation 
bug or a documentation miss. I wanted to know which one it is before trying 
to fix it. 

I’ve done some research and it appears to be a limitation of the 
BufferedReader’s readLine method that uses a buffer of either 4k or 8k 
depending on the implementation. Should we (1) work around this limit in 
the code so that read-line does actually read a whole line or (2) just 
update the documentation to note this limit?

Thanks,

-- Baptiste Fontaine

-- 
You received this message because you are subscribed to the Google
Groups "Clojure" group.
To post to this group, send email to clojure@googlegroups.com
Note that posts from new members are moderated - please be patient with your 
first post.
To unsubscribe from this group, send email to
clojure+unsubscr...@googlegroups.com
For more options, visit this group at
http://groups.google.com/group/clojure?hl=en
--- 
You received this message because you are subscribed to the Google Groups 
"Clojure" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to clojure+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: Clojure core documentation

[Phillip Lord]

Alex Miller  writes:

> On Monday, September 25, 2017 at 11:42:12 AM UTC-5, Phillip Lord wrote:
>> Clojure's doc strings, though, contain knowledge that is not 
>> clear. Consider, this documentation: 
>>
>> Returns a new seq where x is the first element and seq is the rest. 
>>
>> x is the name of a parameter. So is the the second occurence of seq, but 
>> not the first. Neither first, nor rest refer to the functions in 
>> clojure.core, although both probably should do. 
>>
>
> You didn't mention it but this is the docstring for cons. You also stripped 
> half the context (the arglist):
>
> -
> clojure.core/cons
> ([x seq])
>   Returns a new seq where x is the first element and seq is
> the rest.
>
> To me, first and rest here are clearly referring to the English meaning, 
> not the functions, but also intentionally echoes the actual function names 
> which can be used to extract x and seq. I think that's all good.

Yes, I agree with first and rest. But you are inferring this. A tool
will not.

> You can go further with echoing the first/rest stuff by using a spec
> with a :fn too:



>
> -
> clojure.core/cons
> ([x seq])
>   Returns a new seq where x is the first element and seq is
> the rest.
> Spec
>   args: (cat :x any? :seq seqable?)
>   ret: seq?
>   fn: (fn [{:keys [args ret]}] (and (= (:x args) (first ret)) (= (sequence 
> (:seq args)) (rest ret
>
> I think this is way better in specifying the args and ret and actually 
> includes a very precise description of how the args and return value relate 
> to first and ret.


Yep. Precise, but not very readable.



>> Compare this to the documentation for "apply" from Andy Fingerhuts 
>> thalia. 
>>
>
> It seems weird to me to give the docstring from cons above and then from 
> Andy's apply below as a comparison.


Thalia is nice but, alas, not comprehensive.


> I do think it would be useful if the docstring for apply said that args had 
> to be seqable. Of course, if apply had a spec, you'd have that:
>
> user=> (s/fdef clojure.core/apply :args (s/cat :f ifn? :prepend (s/* any?) 
> :args seqable?))
> clojure.core/apply
> user=> (doc apply)
> -
> clojure.core/apply
> ([f args] [f x args] [f x y args] [f x y z args] [f a b c d & args])
>   Applies fn f to the argument list formed by prepending intervening 
> arguments to args.
> Spec
>   args: (cat :f ifn? :prepend (* any?) :args seqable?)
>   ret: any?
>
> Some slight alterations in the :arglists, :doc, and spec names could align 
> these even better.

Indeed, this would be a nice addition.



> Examples: 
>> ```clojure\nuser=> (apply + [1 2])   ; same as (+ 1 2) 3 
>>user=> (apply + 1 2 [3 4 5 6])   ; same as (+ 1 2 3 4 5 6) 
>>
>
> I think one example in this docstring would actually say a lot. I don't 
> like the formatting here (why the clojure? why the user prompt? why the 
> dangling 3?).

The formatting is mine -- I converted the newline chars from the
string. The 3 is my mistaken transcription.


>> It would be possible to go even further than this; consider the runnable 
>> doc strings of rust -- the examples are also tests. Emacs' dash.el does 
>> the same thing. 
>>
>
> Cool idea. As I showed above, we're 95% of the way there already, but with 
> *automatically generated examples*. Although hand-picked ones would 
> undoubtedly serve as better examples, but you could actually inject custom 
> arg generators to even handle that.

As you say, hand-picked ones would be better -- documentation is not the
same thing as a test. Rather, it is good to be able to test the
documentation.

Why not ensure that the right thing (hand-picked examples) are
supported first? Automatically generated examples can come later.

Still, it is good to know that these things are being actively worked
on. The documentation has been static for a long time, and improvements
would be gratefully recieved.

Phil

-- 
You received this message because you are subscribed to the Google
Groups "Clojure" group.
To post to this group, send email to clojure@googlegroups.com
Note that posts from new members are moderated - please be patient with your 
first post.
To unsubscribe from this group, send email to
clojure+unsubscr...@googlegroups.com
For more options, visit this group at
http://groups.google.com/group/clojure?hl=en
--- 
You received this message because you are subscribed to the Google Groups 
"Clojure" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to clojure+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: Clojure core documentation

[Gordon Syme]

Hi Alex,

Thank you for the work you've already put in to improving docstrings in 
Clojure 1.9, I noticed a bunch of docstring Jiras land recently which is 
really encouraging.

Specs certainly helps those of us who are familiar with Clojure and 
clojure.spec already, and know how to use specs to generate examples. 
However, as they are currently presented, clojure.spec is incredibly 
beginner-hostile in a way that docstrings aren't.
It would be interesting to see if the docstrings presented by tooling, the 
various documentation websites, and so on could be augmented by 
clojure.spec. I do not see how that augmentation would remove the need for 
a clearly worded and complete docstring.

There is also a very important case that I don't think clojure.spec 
addresses at all, which is the the ways that functions fail. I haven't come 
across a way to specify exception behaviour with clojure.spec which is just 
as important as documenting the "happy path" behaviour.

Thanks for listening

-Gordon


On Monday, 25 September 2017 23:15:45 UTC+1, Alex Miller wrote:
>
>
>
> On Monday, September 25, 2017 at 11:42:12 AM UTC-5, Phillip Lord wrote:
>>
>>
>>
>> Clojure's doc strings, though, contain knowledge that is not 
>> clear. Consider, this documentation: 
>>
>> Returns a new seq where x is the first element and seq is the rest. 
>>
>> x is the name of a parameter. So is the the second occurence of seq, but 
>> not the first. Neither first, nor rest refer to the functions in 
>> clojure.core, although both probably should do. 
>>
>
> You didn't mention it but this is the docstring for cons. You also 
> stripped half the context (the arglist):
>
> -
> clojure.core/cons
> ([x seq])
>   Returns a new seq where x is the first element and seq is
> the rest.
>
> To me, first and rest here are clearly referring to the English meaning, 
> not the functions, but also intentionally echoes the actual function names 
> which can be used to extract x and seq. I think that's all good. You can go 
> further with echoing the first/rest stuff by using a spec with a :fn too:
>
> -
> clojure.core/cons
> ([x seq])
>   Returns a new seq where x is the first element and seq is
> the rest.
> Spec
>   args: (cat :x any? :seq seqable?)
>   ret: seq?
>   fn: (fn [{:keys [args ret]}] (and (= (:x args) (first ret)) (= (sequence 
> (:seq args)) (rest ret
>
> I think this is way better in specifying the args and ret and actually 
> includes a very precise description of how the args and return value relate 
> to first and ret. And you can property test it with stest/check!
>  
>
>> Compare this to the documentation for "apply" from Andy Fingerhuts 
>> thalia. 
>>
>
> It seems weird to me to give the docstring from cons above and then from 
> Andy's apply below as a comparison.
> For actual comparison the docstring of apply:
>
> -
> clojure.core/apply
> ([f args] [f x args] [f x y args] [f x y z args] [f a b c d & args])
>   Applies fn f to the argument list formed by prepending intervening 
> arguments to args.
>
>  
>
>> `f` is a function and the last argument `args` is a sequence.  Calls  
>
> this is wrong, should be something seqable  --^
> see:  (apply vector 1 "abc")  ;; [1 \a \b \c]
>
> I do think it would be useful if the docstring for apply said that args 
> had to be seqable. Of course, if apply had a spec, you'd have that:
>
> user=> (s/fdef clojure.core/apply :args (s/cat :f ifn? :prepend (s/* any?) 
> :args seqable?))
> clojure.core/apply
> user=> (doc apply)
> -
> clojure.core/apply
> ([f args] [f x args] [f x y args] [f x y z args] [f a b c d & args])
>   Applies fn f to the argument list formed by prepending intervening 
> arguments to args.
> Spec
>   args: (cat :f ifn? :prepend (* any?) :args seqable?)
>   ret: any?
>
> Some slight alterations in the :arglists, :doc, and spec names could align 
> these even better.
>
> `f` with the elements of `args` as its arguments.  If more arguments 
>> `x`, `y`, etc.  are specified, they are added to the beginning of 
>> `args` to form the complete argument list with which `f` is called. 
>>
>
> I find this confusing in that it starts with the beginning and end and 
> then talks about the middle and prefer the original, but matter of taste I 
> suppose. I'd take the spec over either.
>
> Examples: 
>> ```clojure\nuser=> (apply + [1 2])   ; same as (+ 1 2) 3 
>>user=> (apply + 1 2 [3 4 5 6])   ; same as (+ 1 2 3 4 5 6) 
>>
>
> I think one example in this docstring would actually say a lot. I don't 
> like the formatting here (why the clojure? why the user prompt? why the 
> dangling 3?). Could actually use the spec to generate as many examples as 
> you like though using s/exercise-fn!
>
> user=> (s/exercise-fn 'clojure.core/cons)
> ([(nil "") (nil)] 
> [(() "") (())] 
> [(nil nil) (nil)] 
> [(nil {Hr-* -1.0, false #uuid 

Re: Clojure core documentation

[Phillip Lord]

If the docstring were more structured (either using conventions within
the docstring, or additional metadata elements on the var), then this
would not be a problem. First line for tooltip, main doc for hover-over,
examples on request, that kind of thing.

Phil

Beau Fabry  writes:

> As a docstring I don't find this superior. Docstrings (for me) are usually
> viewed as quick little pop-up boxes in my editor. The existing clojure 
> docstring for `apply` gives me the information I need much faster and 
> with less screen real estate. YMMV.
>
>
> On Monday, September 25, 2017 at 9:42:12 AM UTC-7, Phillip Lord wrote:
>>
>>
>>
>> Clojure's doc strings, though, contain knowledge that is not 
>> clear. Consider, this documentation: 
>>
>> Returns a new seq where x is the first element and seq is the rest. 
>>
>> x is the name of a parameter. So is the the second occurence of seq, but 
>> not the first. Neither first, nor rest refer to the functions in 
>> clojure.core, although both probably should do. 
>>
>> Compare this to the documentation for "apply" from Andy Fingerhuts 
>> thalia. 
>>
>> `f` is a function and the last argument `args` is a sequence.  Calls 
>> `f` with the elements of `args` as its arguments.  If more arguments 
>> `x`, `y`, etc.  are specified, they are added to the beginning of 
>> `args` to form the complete argument list with which `f` is called. 
>>
>> Examples: 
>> ```clojure\nuser=> (apply + [1 2])   ; same as (+ 1 2) 3 
>>user=> (apply + 1 2 [3 4 5 6])   ; same as (+ 1 2 3 4 5 6) 
>>
>> Which is essentially superior in every way. The existence of neither 
>> specs nor clojure.org don't really change this. 
>>
>> It would be possible to go even further than this; consider the runnable 
>> doc strings of rust -- the examples are also tests. Emacs' dash.el does 
>> the same thing. 
>>
>> Still, it's been this way since I first started using clojure (1.3/1.4) 
>> so I suspect that it's not going to change. 
>>
>> Phil 
>>
>>
>>
>> Stuart Halloway  writes: 
>>
>> > Clojure has great data, and great metadata. Documentation strings are 
>> *not* 
>> > great data, they are strings. 
>> > 
>> > If you want to provide more structured support than docstrings to help 
>> > someone use Clojure, look at specs for inspiration. They are made of 
>> data, 
>> > and they live in a registry separate from Clojure's var system. This 
>> kind 
>> > of decoupling supports composition and tooling without requiring any 
>> > addition or change to Clojure. 
>> > 
>> > I would also echo Matching Socks: Having more and better guides at 
>> > clojure.org would be great. The contribution process is described at 
>> > 
>> https://github.com/clojure/clojure-site/blob/master/content/community/contributing_site.adoc
>> > . 
>> > 
>> > Regards, 
>> > Stu 
>> > 
>> > On Mon, Sep 11, 2017 at 5:23 AM, Matching Socks > > 
>> > wrote: 
>> > 
>> >> I am not convinced I would have found the API docs on reducers or 
>> zippers 
>> >> more informative if all references had been tidily markdown'ed. 
>> >> 
>> >> The new clojure.org welcomes contributions of topical overviews. 
>>  That's 
>> >> helpful. 
>> >> 
>> >> But, to interpret docstrings, nothing helps like perspective.  The 
>> thing 
>> >> about perspective is that there could be so many.  I like "Clojure 
>> >> Programming" by Emerick, Carper & Grand. 
>>

-- 
Phillip Lord,   Phone: +44 (0) 191 208 7827
Biology, Medicine, ComputingEmail: phillip.l...@newcastle.ac.uk
School of Computing,
http://homepages.cs.ncl.ac.uk/phillip.lord
Room 5.012 Urban Sciences Building, skype: russet_apples
Newcastle University,   twitter: phillord
NE4 5TG

-- 
You received this message because you are subscribed to the Google
Groups "Clojure" group.
To post to this group, send email to clojure@googlegroups.com
Note that posts from new members are moderated - please be patient with your 
first post.
To unsubscribe from this group, send email to
clojure+unsubscr...@googlegroups.com
For more options, visit this group at
http://groups.google.com/group/clojure?hl=en
--- 
You received this message because you are subscribed to the Google Groups 
"Clojure" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to clojure+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.