www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - RFC curl

reply Jonas Drewsen <jdrewsen nospam.com> writes:
Hi,

    So after the last review of the etc.curl there were some requests 
for making it simpler.

After some thinking, refactoring and documentation I've come up with a 
somewhat changed API.

Before sending it for official review again I would really like some 
comments on the new API and if you think it is better or worse etc.

http://freeze.steamwinter.com/D/web/phobos/etc_curl.html

Thanks,
Jonas
Nov 09 2011
next sibling parent "Marco Leise" <Marco.Leise gmx.de> writes:
Am 09.11.2011, 21:53 Uhr, schrieb Jonas Drewsen <jdrewsen nospam.com>:


 Hi,

     So after the last review of the etc.curl there were some requests  
 for making it simpler.

 After some thinking, refactoring and documentation I've come up with a  
 somewhat changed API.

 Before sending it for official review again I would really like some  
 comments on the new API and if you think it is better or worse etc.

 http://freeze.steamwinter.com/D/web/phobos/etc_curl.html

 Thanks,
 Jonas


Amazing! D docs that look like they were made to be read by a human being!  
;)
I like the accessibility, that gets you right to the point for any use  
case. I did not compare it to your previous version though.
The external links sometimes have four slashes http://// and the text  
"Authentication method equal to" looks incomplete and you wrote valie  
instead of value. Good luck with the next review!
Nov 09 2011
prev sibling next sibling parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 11/9/2011 12:53 PM, Jonas Drewsen wrote:

 Before sending it for official review again I would really like some comments
on
 the new API and if you think it is better or worse etc.

 http://freeze.steamwinter.com/D/web/phobos/etc_curl.html


Thank you so much for doing this. I think it's a nice piece of work.

Some nitpicky comments:

* libcurl should be a link to where people can read up on what it is.
I suggest http://curl.haxx.se/libcurl
Point out that the user will need libcurl installed on their system in order to 
use etc.curl.

* Need a brief statement on why a D programmer should prefer using etc.curl 
rather than directly use libcurl.

* "ranges" should be a link to what a range is

* examples should include

     import etc.curl;

and any other needed, like std.stdio. In fact, they should be cut & paste 
complete examples that are compilable and runnable.

* Keep comment lines under 40 characters; use multiple lines for longer 
comments. (This is so things format better for small screens.) Try to format 
code so it doesn't need more than 40 lines. I tend to indent by only two spaces 
in documentation which helps.

* Remove all instances of the word "you". For example,

"If you need more control than the low high level functions provide, you'll
have 
to use the low level API:"

rewrite as:

"For more control than the low high level functions provide, use the low level
API:"

Note how much simpler and direct it is. "You" is almost always an unnecessary 
filler word, and frankly has no place in a reference work.

* For the same reason, get rid of "we":

"First, we create an instance" => "First, create an instance"
"We then set" => "Then set"

* derivate => derived

* "Connection type used when the url should be used to auto detect protocol"
  .. I have no idea what this sentence means.

* "HTTP/FTP upload from local file system." => Upload file from local
  file system using the HTTP or FTP protocol."
And which protocol would be used?

* "A string with the content of the resource pointer to by the url"
Missing period. Grammar problems, how about:
"A string containing the content of the resource pointed to by the url."

Most of these apply to the rest of the documentation.

Also, need more examples.

I tend to like references to things in other modules to be hyperlinks. For 
example, writeln should be $(LINK2 
http://www.d-programming-language.org/phobos/std_stdio.html#writeln, writeln)
Nov 09 2011
next sibling parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 11/9/2011 4:24 PM, Walter Bright wrote:

 On 11/9/2011 12:53 PM, Jonas Drewsen wrote:

 Before sending it for official review again I would really like some comments
on
 the new API and if you think it is better or worse etc.

 http://freeze.steamwinter.com/D/web/phobos/etc_curl.html


 Thank you so much for doing this. I think it's a nice piece of work.


I forgot to mention: I like the cheat sheet a lot.
Nov 09 2011
next sibling parent reply =?utf-8?Q?Simen_Kj=C3=A6r=C3=A5s?= <simen.kjaras gmail.com> writes:
On Thu, 10 Nov 2011 01:25:29 +0100, Walter Bright  
<newshound2 digitalmars.com> wrote:


 On 11/9/2011 4:24 PM, Walter Bright wrote:

 On 11/9/2011 12:53 PM, Jonas Drewsen wrote:

 Before sending it for official review again I would really like some  
 comments on
 the new API and if you think it is better or worse etc.

 http://freeze.steamwinter.com/D/web/phobos/etc_curl.html


 Thank you so much for doing this. I think it's a nice piece of work.


 I forgot to mention: I like the cheat sheet a lot.


Indeed. I am tempted to argue all of our docs should have that.
Nov 09 2011
parent "Jonathan M Davis" <jmdavisProg gmx.com> writes:
On Wednesday, November 09, 2011 17:05 Simen Kjærås wrote:

 On Thu, 10 Nov 2011 01:25:29 +0100, Walter Bright
 
 <newshound2 digitalmars.com> wrote:

 On 11/9/2011 4:24 PM, Walter Bright wrote:

 On 11/9/2011 12:53 PM, Jonas Drewsen wrote:

 Before sending it for official review again I would really like some
 comments on
 the new API and if you think it is better or worse etc.
 
 http://freeze.steamwinter.com/D/web/phobos/etc_curl.html


 
 Thank you so much for doing this. I think it's a nice piece of work.


 
 I forgot to mention: I like the cheat sheet a lot.


 
 Indeed. I am tempted to argue all of our docs should have that.


It's essentially what std.algorithm does now, and std.container does something 
similar. I'd love to do something like that with std.datetime, but the fact 
that the anchors that ddoc generates have no concept of hiearchy (e.g. every 
year function in the file gets #year for its anchor rather than something like 
#Date.year, #DateTime.year, etc.). So, I couldn't provide any links in such a 
cheat sheat. I think that one or two people have said that they'd look into 
fixing it, but no one has actually fixed it yet. If no one else fixes it any 
time soon, I may be forced to go dig into ddoc to figure it out myself, which 
is definitely not where I want to be spending my time if I can avoid it.

- Jonathan M Davis
Nov 09 2011
prev sibling parent Jonas Drewsen <jdrewsen nospam.com> writes:
On 10/11/11 01.25, Walter Bright wrote:

 On 11/9/2011 4:24 PM, Walter Bright wrote:

 On 11/9/2011 12:53 PM, Jonas Drewsen wrote:

 Before sending it for official review again I would really like some
 comments on
 the new API and if you think it is better or worse etc.

 http://freeze.steamwinter.com/D/web/phobos/etc_curl.html


 Thank you so much for doing this. I think it's a nice piece of work.


 I forgot to mention: I like the cheat sheet a lot.


Me to... stole it from std.algorithm :)

/Jonas
Nov 10 2011
prev sibling next sibling parent reply bearophile <bearophileHUGS lycos.com> writes:
Walter:


 Thank you so much for doing this. I think it's a nice piece of work.


I agree.
As they say, easy things should be easy and hard things should be possible.



 * libcurl should be a link to where people can read up on what it is.
 I suggest http://curl.haxx.se/libcurl
 Point out that the user will need libcurl installed on their system in order
to 
 use etc.curl.


Is the (just) Windows compiled version present in the DMD zip? I don't remember
what was the decision on this (I'd like it to be present).

Bye,
bearophile
Nov 09 2011
next sibling parent reply "Jonathan M Davis" <jmdavisProg gmx.com> writes:
On Wednesday, November 09, 2011 16:58 bearophile wrote:

 Is the (just) Windows compiled version present in the DMD zip? I don't
 remember what was the decision on this (I'd like it to be present).


Currently, no version of libcurl is included in the zip file. I don't believe 
that there has been any decision on what to do about it. But if we do end up 
including it, then that's one more reason to consider splitting up the zip 
file by OS.

- Jonathan M Davis
Nov 09 2011
parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 11/9/2011 5:13 PM, Jonathan M Davis wrote:

 On Wednesday, November 09, 2011 16:58 bearophile wrote:

 Is the (just) Windows compiled version present in the DMD zip? I don't
 remember what was the decision on this (I'd like it to be present).


 Currently, no version of libcurl is included in the zip file. I don't believe
 that there has been any decision on what to do about it. But if we do end up
 including it, then that's one more reason to consider splitting up the zip
 file by OS.


I don't want us to get caught in the rat race of "the version that comes with 
the compiler is out of date". libcurl has its own development cycle, and dmd 
should not be slaved to that.
Nov 09 2011
parent reply Jonathan M Davis <jmdavisProg gmx.com> writes:
On Wednesday, November 09, 2011 18:38:48 Walter Bright wrote:

 On 11/9/2011 5:13 PM, Jonathan M Davis wrote:

 On Wednesday, November 09, 2011 16:58 bearophile wrote:

 Is the (just) Windows compiled version present in the DMD zip? I don't
 remember what was the decision on this (I'd like it to be present).


 
 Currently, no version of libcurl is included in the zip file. I don't
 believe that there has been any decision on what to do about it. But if
 we do end up including it, then that's one more reason to consider
 splitting up the zip file by OS.


 
 I don't want us to get caught in the rat race of "the version that comes
 with the compiler is out of date". libcurl has its own development cycle,
 and dmd should not be slaved to that.


Yeah. That's one reason why I'm not a fan of the idea of distributing it with 
dmd. So, it won't hurt my feelings any if it never gets put into the zip file. 
However, we're going to have to make it clear in the documentation on how to 
get your hands on an appropriate libcurl library (especially since any version 
of it that you're likely to find online would be in the wrong library format).

- Jonathan M Davis
Nov 09 2011
parent reply Jacob Carlborg <doob me.com> writes:
On 2011-11-10 04:39, Jonathan M Davis wrote:

 On Wednesday, November 09, 2011 18:38:48 Walter Bright wrote:

 On 11/9/2011 5:13 PM, Jonathan M Davis wrote:

 On Wednesday, November 09, 2011 16:58 bearophile wrote:

 Is the (just) Windows compiled version present in the DMD zip? I don't
 remember what was the decision on this (I'd like it to be present).


 Currently, no version of libcurl is included in the zip file. I don't
 believe that there has been any decision on what to do about it. But if
 we do end up including it, then that's one more reason to consider
 splitting up the zip file by OS.


 I don't want us to get caught in the rat race of "the version that comes
 with the compiler is out of date". libcurl has its own development cycle,
 and dmd should not be slaved to that.


 Yeah. That's one reason why I'm not a fan of the idea of distributing it with
 dmd. So, it won't hurt my feelings any if it never gets put into the zip file.
 However, we're going to have to make it clear in the documentation on how to
 get your hands on an appropriate libcurl library (especially since any version
 of it that you're likely to find online would be in the wrong library format).

 - Jonathan M Davis


What about distributing it from the dpl page but not in the dmd zip?

-- 
/Jacob Carlborg
Nov 10 2011
parent Jonathan M Davis <jmdavisProg gmx.com> writes:
On Thursday, November 10, 2011 10:30:15 Jacob Carlborg wrote:

 On 2011-11-10 04:39, Jonathan M Davis wrote:

 On Wednesday, November 09, 2011 18:38:48 Walter Bright wrote:

 On 11/9/2011 5:13 PM, Jonathan M Davis wrote:

 On Wednesday, November 09, 2011 16:58 bearophile wrote:

 Is the (just) Windows compiled version present in the DMD zip? I
 don't
 remember what was the decision on this (I'd like it to be
 present).


 
 Currently, no version of libcurl is included in the zip file. I
 don't
 believe that there has been any decision on what to do about it. But
 if
 we do end up including it, then that's one more reason to consider
 splitting up the zip file by OS.


 
 I don't want us to get caught in the rat race of "the version that
 comes
 with the compiler is out of date". libcurl has its own development
 cycle, and dmd should not be slaved to that.


 
 Yeah. That's one reason why I'm not a fan of the idea of distributing it
 with dmd. So, it won't hurt my feelings any if it never gets put into
 the zip file. However, we're going to have to make it clear in the
 documentation on how to get your hands on an appropriate libcurl
 library (especially since any version of it that you're likely to find
 online would be in the wrong library format).
 
 - Jonathan M Davis


 
 What about distributing it from the dpl page but not in the dmd zip?


We definitely need to make it relatively easy to get the library, and I have no 
problem with us providing a separate download for it. But Phobos isn't tied to 
a particular version of libcurl, so if we provide it, we need to be providing 
it as a convenience rather than saying that this is the version to use. And 
really, we need better instructions in general about how to get a 3rd party C 
library to work with D code on Windows. It's obvious a bit of an ordeal for 
anyone who tries.

- Jonathan M Davis
Nov 10 2011
prev sibling parent reply Kapps <Kapps NotValidEmail.com> writes:
Windows is generally a place where people expect to not have to go and 
install other external packages for things like this, but rather have it 
bundled with the installer (zip in this case). Whereas on Linux, you 
could just use your package manager to install the libraries, for 
Windows, you'd have to actually find the website, find the library, 
possibly compile it (difficult on Windows), implib/coffimplib it 
(something which has little to no documentation and is very hard for new 
people to figure out, and something I had a LOT of problems with trying 
to figure out originally; it doesn't even come with DMD), and finally 
link it and hope for the best. It would be MUCH better and simpler to 
just include it in the zip for Windows.

On 09/11/2011 6:58 PM, bearophile wrote:

 Walter:


 Thank you so much for doing this. I think it's a nice piece of work.


 I agree.
 As they say, easy things should be easy and hard things should be possible.



 * libcurl should be a link to where people can read up on what it is.
 I suggest http://curl.haxx.se/libcurl
 Point out that the user will need libcurl installed on their system in order to
 use etc.curl.


 Is the (just) Windows compiled version present in the DMD zip? I don't
remember what was the decision on this (I'd like it to be present).

 Bye,
 bearophile
Nov 09 2011
next sibling parent Brad Anderson <eco gnuk.net> writes:
On Wed, Nov 9, 2011 at 9:31 PM, Kapps <Kapps notvalidemail.com> wrote:


 Windows is generally a place where people expect to not have to go and
 install other external packages for things like this, but rather have it
 bundled with the installer (zip in this case). Whereas on Linux, you could
 just use your package manager to install the libraries, for Windows, you'd
 have to actually find the website, find the library, possibly compile it
 (difficult on Windows), implib/coffimplib it (something which has little to
 no documentation and is very hard for new people to figure out, and
 something I had a LOT of problems with trying to figure out originally; it
 doesn't even come with DMD), and finally link it and hope for the best. It
 would be MUCH better and simpler to just include it in the zip for Windows.


I agree.  Python's "batteries included" style approach is a huge boon.  The
number of users who would need a different version than the one included
pales in comparison to the productivity gains of including it.  People who
need a different version can just replace it themselves.  We could also
just make the installer give the user a choice of installing it or not.




On 09/11/2011 6:58 PM, bearophile wrote:

 Walter:

  Thank you so much for doing this. I think it's a nice piece of work.


 I agree.
 As they say, easy things should be easy and hard things should be
 possible.


  * libcurl should be a link to where people can read up on what it is.

 I suggest http://curl.haxx.se/libcurl
 Point out that the user will need libcurl installed on their system in
 order to
 use etc.curl.


 Is the (just) Windows compiled version present in the DMD zip? I don't
 remember what was the decision on this (I'd like it to be present).

 Bye,
 bearophile







 Nov 09 2011



prev sibling  parent  Jimmy Cao <jcao219 gmail.com>  writes:


2011/11/9 Brad Anderson <eco gnuk.net>


 On Wed, Nov 9, 2011 at 9:31 PM, Kapps <Kapps notvalidemail.com> wrote:


 Windows is generally a place where people expect to not have to go and
 install other external packages for things like this, but rather have it
 bundled with the installer (zip in this case). Whereas on Linux, you could
 just use your package manager to install the libraries, for Windows, you'd
 have to actually find the website, find the library, possibly compile it
 (difficult on Windows), implib/coffimplib it (something which has little to
 no documentation and is very hard for new people to figure out, and
 something I had a LOT of problems with trying to figure out originally; it
 doesn't even come with DMD), and finally link it and hope for the best. It
 would be MUCH better and simpler to just include it in the zip for Windows.


 I agree.  Python's "batteries included" style approach is a huge boon.
  The number of users who would need a different version than the one
 included pales in comparison to the productivity gains of including it.
  People who need a different version can just replace it themselves.  We
 could also just make the installer give the user a choice of installing it
 or not.




  On 09/11/2011 6:58 PM, bearophile wrote:

 Walter:

  Thank you so much for doing this. I think it's a nice piece of work.


 I agree.
 As they say, easy things should be easy and hard things should be
 possible.


  * libcurl should be a link to where people can read up on what it is.

 I suggest http://curl.haxx.se/libcurl
 Point out that the user will need libcurl installed on their system in
 order to
 use etc.curl.


 Is the (just) Windows compiled version present in the DMD zip? I don't
 remember what was the decision on this (I'd like it to be present).

 Bye,
 bearophile






I agree, on Windows it would be best to have a competent installer that
does this.



 Nov 09 2011



prev sibling next sibling parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org>  writes:


On 11/9/11 6:24 PM, Walter Bright wrote:

 I tend to like references to things in other modules to be hyperlinks.
 For example, writeln should be $(LINK2
 http://www.d-programming-language.org/phobos/std_stdio.html#writeln,
 writeln)


That should be XREF actually.

Andrei



 Nov 09 2011



  parent reply Jacob Carlborg <doob me.com>  writes:


On 2011-11-10 03:57, Andrei Alexandrescu wrote:

 On 11/9/11 6:24 PM, Walter Bright wrote:

 I tend to like references to things in other modules to be hyperlinks.
 For example, writeln should be $(LINK2
 http://www.d-programming-language.org/phobos/std_stdio.html#writeln,
 writeln)


 That should be XREF actually.

 Andrei


I would be nice to have some documentation of these macros that are used 
through out Phobos.

-- 
/Jacob Carlborg



 Nov 10 2011



  parent reply Jonathan M Davis <jmdavisProg gmx.com>  writes:


On Thursday, November 10, 2011 10:27:46 Jacob Carlborg wrote:

 On 2011-11-10 03:57, Andrei Alexandrescu wrote:

 On 11/9/11 6:24 PM, Walter Bright wrote:

 I tend to like references to things in other modules to be hyperlinks.
 For example, writeln should be $(LINK2
 http://www.d-programming-language.org/phobos/std_stdio.html#writeln,
 writeln)


 
 That should be XREF actually.
 
 Andrei


 
 I would be nice to have some documentation of these macros that are used
 through out Phobos.


Look at the bottom std.ddoc in the d-programming-language.org repository - 
though it may be a good idea to actually put them on a page somewhere. Still, 
since it really only affects Phobos devs, it's not quite as critical as a lot 
of other documentation.

- Jonathan M Davis



 Nov 10 2011



  parent  Jacob Carlborg <doob me.com>  writes:


On 2011-11-10 11:12, Jonathan M Davis wrote:

 On Thursday, November 10, 2011 10:27:46 Jacob Carlborg wrote:

 On 2011-11-10 03:57, Andrei Alexandrescu wrote:

 On 11/9/11 6:24 PM, Walter Bright wrote:

 I tend to like references to things in other modules to be hyperlinks.
 For example, writeln should be $(LINK2
 http://www.d-programming-language.org/phobos/std_stdio.html#writeln,
 writeln)


 That should be XREF actually.

 Andrei


 I would be nice to have some documentation of these macros that are used
 through out Phobos.


 Look at the bottom std.ddoc in the d-programming-language.org repository -
 though it may be a good idea to actually put them on a page somewhere. Still,
 since it really only affects Phobos devs, it's not quite as critical as a lot
 of other documentation.

 - Jonathan M Davis


I would not consider that documentation but it's good to know where I 
can find them. They could be put on a "contribute" page at d-p-l.org. I 
have thought several times that there should be a "contribute" page at 
d-p-l.org that contains information like this.

-- 
/Jacob Carlborg



 Nov 10 2011



prev sibling next sibling parent  Jonas Drewsen <jdrewsen nospam.com>  writes:


On 10/11/11 01.24, Walter Bright wrote:

 On 11/9/2011 12:53 PM, Jonas Drewsen wrote:

 Before sending it for official review again I would really like some
 comments on
 the new API and if you think it is better or worse etc.

 http://freeze.steamwinter.com/D/web/phobos/etc_curl.html


 Thank you so much for doing this. I think it's a nice piece of work.


Thank you.

It seems that people like this API better. I'll head on to implement the 
last common HTTP request types (head() etc.), polish and fix the stuff 
you've mentioned below then.

/Jonas


 Some nitpicky comments:

 * libcurl should be a link to where people can read up on what it is.
 I suggest http://curl.haxx.se/libcurl
 Point out that the user will need libcurl installed on their system in
 order to use etc.curl.

 * Need a brief statement on why a D programmer should prefer using
 etc.curl rather than directly use libcurl.

 * "ranges" should be a link to what a range is

 * examples should include

 import etc.curl;

 and any other needed, like std.stdio. In fact, they should be cut &
 paste complete examples that are compilable and runnable.

 * Keep comment lines under 40 characters; use multiple lines for longer
 comments. (This is so things format better for small screens.) Try to
 format code so it doesn't need more than 40 lines. I tend to indent by
 only two spaces in documentation which helps.

 * Remove all instances of the word "you". For example,

 "If you need more control than the low high level functions provide,
 you'll have to use the low level API:"

 rewrite as:

 "For more control than the low high level functions provide, use the low
 level API:"

 Note how much simpler and direct it is. "You" is almost always an
 unnecessary filler word, and frankly has no place in a reference work.

 * For the same reason, get rid of "we":

 "First, we create an instance" => "First, create an instance"
 "We then set" => "Then set"

 * derivate => derived

 * "Connection type used when the url should be used to auto detect
 protocol"
 .. I have no idea what this sentence means.

 * "HTTP/FTP upload from local file system." => Upload file from local
 file system using the HTTP or FTP protocol."
 And which protocol would be used?

 * "A string with the content of the resource pointer to by the url"
 Missing period. Grammar problems, how about:
 "A string containing the content of the resource pointed to by the url."

 Most of these apply to the rest of the documentation.

 Also, need more examples.

 I tend to like references to things in other modules to be hyperlinks.
 For example, writeln should be $(LINK2
 http://www.d-programming-language.org/phobos/std_stdio.html#writeln,
 writeln)





 Nov 10 2011



prev sibling  parent reply Jonas Drewsen <jdrewsen nospam.com>  writes:


Den 10-11-2011 01:24, Walter Bright skrev:

 I tend to like references to things in other modules to be hyperlinks.
 For example, writeln should be $(LINK2
 http://www.d-programming-language.org/phobos/std_stdio.html#writeln,
 writeln)


The only places I use writeln is in the examples. Do you want hyperlinks 
in there? I haven't seen that in any other module.

If this is something we want to do then a new markup token should be 
added to std.ddoc I think. This should ensure that the examples does not 
look messy because of normal hyperlink highlighting.

/Jonas



 Nov 11 2011



  parent  Jonathan M Davis <jmdavisProg gmx.com>  writes:


On Friday, November 11, 2011 20:45:28 Jonas Drewsen wrote:

 Den 10-11-2011 01:24, Walter Bright skrev:

 I tend to like references to things in other modules to be hyperlinks.
 For example, writeln should be $(LINK2
 http://www.d-programming-language.org/phobos/std_stdio.html#writeln,
 writeln)


 
 The only places I use writeln is in the examples. Do you want hyperlinks
 in there? I haven't seen that in any other module.
 
 If this is something we want to do then a new markup token should be
 added to std.ddoc I think. This should ensure that the examples does not
 look messy because of normal hyperlink highlighting.


I don't think that it's possible to have links in examples with ddoc. It just 
prints exactly what you put in there as-is. References to functions outside of 
the examples should use XREF (for functions in other modules in Phobos) and 
LREF (for functions in the same module).

- Jonathan M Davis



 Nov 11 2011



prev sibling next sibling parent reply Jacob Carlborg <doob me.com>  writes:


On 2011-11-09 21:53, Jonas Drewsen wrote:

 Hi,

 So after the last review of the etc.curl there were some requests for
 making it simpler.

 After some thinking, refactoring and documentation I've come up with a
 somewhat changed API.

 Before sending it for official review again I would really like some
 comments on the new API and if you think it is better or worse etc.

 http://freeze.steamwinter.com/D/web/phobos/etc_curl.html

 Thanks,
 Jonas


I like the new high level API, that's how easy it should be to download 
a file or get the content of a webpage.

What is the actual Phobos guideline in naming things that are keywords 
in D. I'm thinking about Method.del, shouldn't it be Method.delete_ or 
something similar, don't know what the guidelines say in this case. BTW, 
I would really like to have more official guidelines somewhere at the 
dpl page.

-- 
/Jacob Carlborg



 Nov 09 2011



 next sibling parent reply Jonathan M Davis <jmdavisProg gmx.com>  writes:


On Thursday, November 10, 2011 08:27:53 Jacob Carlborg wrote:

 What is the actual Phobos guideline in naming things that are keywords
 in D. I'm thinking about Method.del, shouldn't it be Method.delete_ or
 something similar, don't know what the guidelines say in this case. BTW,
 I would really like to have more official guidelines somewhere at the
 dpl page.


Thus far, we've taken the approach of tacking an underscore on the end (so 
delete would be delete_), but we haven't made any kind of official decision on 
it. However, if it's reasonable to use a different word entirely, then that's 
generally better. It's stuff like std.traits.FunctionAttribute which pretty 
much _has_ to match the keyword where we've appended the underscore (e.g. 
pure_ and nothrow_).

- Jonathan M Davis



 Nov 10 2011



  parent reply Jacob Carlborg <doob me.com>  writes:


On 2011-11-10 09:50, Jonathan M Davis wrote:

 On Thursday, November 10, 2011 08:27:53 Jacob Carlborg wrote:

 What is the actual Phobos guideline in naming things that are keywords
 in D. I'm thinking about Method.del, shouldn't it be Method.delete_ or
 something similar, don't know what the guidelines say in this case. BTW,
 I would really like to have more official guidelines somewhere at the
 dpl page.


 Thus far, we've taken the approach of tacking an underscore on the end (so
 delete would be delete_), but we haven't made any kind of official decision on
 it. However, if it's reasonable to use a different word entirely, then that's
 generally better. It's stuff like std.traits.FunctionAttribute which pretty
 much _has_ to match the keyword where we've appended the underscore (e.g.
 pure_ and nothrow_).

 - Jonathan M Davis


I agree, but this case it's not a completely different word, it's a 
shorting of the word.

I just like that there should be something more official when these 
things pop up.

-- 
/Jacob Carlborg



 Nov 10 2011



  parent reply Jonathan M Davis <jmdavisProg gmx.com>  writes:


On Thursday, November 10, 2011 10:58:14 Jacob Carlborg wrote:

 On 2011-11-10 09:50, Jonathan M Davis wrote:

 On Thursday, November 10, 2011 08:27:53 Jacob Carlborg wrote:

 What is the actual Phobos guideline in naming things that are keywords
 in D. I'm thinking about Method.del, shouldn't it be Method.delete_ or
 something similar, don't know what the guidelines say in this case.
 BTW,
 I would really like to have more official guidelines somewhere at the
 dpl page.


 
 Thus far, we've taken the approach of tacking an underscore on the end
 (so delete would be delete_), but we haven't made any kind of official
 decision on it. However, if it's reasonable to use a different word
 entirely, then that's generally better. It's stuff like
 std.traits.FunctionAttribute which pretty much _has_ to match the
 keyword where we've appended the underscore (e.g. pure_ and nothrow_).
 
 - Jonathan M Davis


 
 I agree, but this case it's not a completely different word, it's a
 shorting of the word.
 
 I just like that there should be something more official when these
 things pop up.


Well, for better or worse, we don't have an official policy on it. In general,
I 
think that the tact is to try and rename the item so that it doesn't pose a 
problem, but that's not always possible (hence FunctionAttribute.pure_). In 
this case, since it comes from something else, it looks like it really should 
be some version of delete. However, whereas FunctionAttribute pretty much 
_had_ to be as close to the keyword as possible since it represented the 
keyword, that's not the case here, and given how ugly it is to tack the _ on, 
del seems like a reasonable solution.

In any case, if we want something official, we'd have to discuss it, and we 
generally have a hard time coming to any kind of consensus on stuff like that. 
So, I don't generally try unless it seems particularly important.

- Jonathan M Davis



 Nov 10 2011



  parent reply Jacob Carlborg <doob me.com>  writes:


On 2011-11-10 11:21, Jonathan M Davis wrote:

 Well, for better or worse, we don't have an official policy on it. In general,
I
 think that the tact is to try and rename the item so that it doesn't pose a
 problem, but that's not always possible (hence FunctionAttribute.pure_). In
 this case, since it comes from something else, it looks like it really should
 be some version of delete. However, whereas FunctionAttribute pretty much
 _had_ to be as close to the keyword as possible since it represented the
 keyword, that's not the case here, and given how ugly it is to tack the _ on,
 del seems like a reasonable solution.

 In any case, if we want something official, we'd have to discuss it, and we
 generally have a hard time coming to any kind of consensus on stuff like that.
 So, I don't generally try unless it seems particularly important.

 - Jonathan M Davis


I think we should write down, somewhere, what we have, what we have 
agreed on unofficially. It may not be complete and not contain details 
for everything but it would at least be something. Instead of having to 
explain this every time we get a new contributor to Phobos or one has to 
try to find this information in the newsgroup.

-- 
/Jacob Carlborg



 Nov 10 2011



  parent reply Manu <turkeyman gmail.com>  writes:


This must be a really silly question, or it would have been asked already,
so I apologise in advance.

It appears you have written a low level http, ftp, smtp library included in
this library... why is there not a standard library for each of these
protocols, and why aren't you building on top of that?

- me

On 10 November 2011 15:43, Jacob Carlborg <doob me.com> wrote:


 On 2011-11-10 11:21, Jonathan M Davis wrote:


 Well, for better or worse, we don't have an official policy on it. In
 general, I
 think that the tact is to try and rename the item so that it doesn't pose
 a
 problem, but that's not always possible (hence FunctionAttribute.pure_).
 In
 this case, since it comes from something else, it looks like it really
 should
 be some version of delete. However, whereas FunctionAttribute pretty much
 _had_ to be as close to the keyword as possible since it represented the
 keyword, that's not the case here, and given how ugly it is to tack the _
 on,
 del seems like a reasonable solution.

 In any case, if we want something official, we'd have to discuss it, and
 we
 generally have a hard time coming to any kind of consensus on stuff like
 that.
 So, I don't generally try unless it seems particularly important.

 - Jonathan M Davis


 I think we should write down, somewhere, what we have, what we have agreed
 on unofficially. It may not be complete and not contain details for
 everything but it would at least be something. Instead of having to explain
 this every time we get a new contributor to Phobos or one has to try to
 find this information in the newsgroup.

 --
 /Jacob Carlborg





 Nov 10 2011



  parent reply Jonas Drewsen <jdrewsen nospam.com>  writes:


On 10/11/11 14.58, Manu wrote:

 This must be a really silly question, or it would have been asked
 already, so I apologise in advance.

 It appears you have written a low level http, ftp, smtp library included
 in this library... why is there not a standard library for each of these
 protocols, and why aren't you building on top of that?


The new etc.curl (std.curl) module is actually build on top of the 
libcurl bindings located in etc.c.curl. So all low level stuff is 
handled by the standard libcurl library.

/Jonas



 - me

 On 10 November 2011 15:43, Jacob Carlborg <doob me.com
 <mailto:doob me.com>> wrote:

     On 2011-11-10 11:21, Jonathan M Davis wrote:

         Well, for better or worse, we don't have an official policy on
         it. In general, I
         think that the tact is to try and rename the item so that it
         doesn't pose a
         problem, but that's not always possible (hence
         FunctionAttribute.pure_). In
         this case, since it comes from something else, it looks like it
         really should
         be some version of delete. However, whereas FunctionAttribute
         pretty much
         _had_ to be as close to the keyword as possible since it
         represented the
         keyword, that's not the case here, and given how ugly it is to
         tack the _ on,
         del seems like a reasonable solution.

         In any case, if we want something official, we'd have to discuss
         it, and we
         generally have a hard time coming to any kind of consensus on
         stuff like that.
         So, I don't generally try unless it seems particularly important.

         - Jonathan M Davis


     I think we should write down, somewhere, what we have, what we have
     agreed on unofficially. It may not be complete and not contain
     details for everything but it would at least be something. Instead
     of having to explain this every time we get a new contributor to
     Phobos or one has to try to find this information in the newsgroup.

     --
     /Jacob Carlborg





 Nov 10 2011



  parent  Manu <turkeyman gmail.com>  writes:


Ah, I see :)

Are those extremely useful protocols already supported in the D standard
library? I haven't checked... (yes, I *could* check right now ;)

On 10 November 2011 16:09, Jonas Drewsen <jdrewsen nospam.com> wrote:


 On 10/11/11 14.58, Manu wrote:


 This must be a really silly question, or it would have been asked
 already, so I apologise in advance.

 It appears you have written a low level http, ftp, smtp library included
 in this library... why is there not a standard library for each of these
 protocols, and why aren't you building on top of that?


 The new etc.curl (std.curl) module is actually build on top of the libcurl
 bindings located in etc.c.curl. So all low level stuff is handled by the
 standard libcurl library.

 /Jonas


  - me

 On 10 November 2011 15:43, Jacob Carlborg <doob me.com
 <mailto:doob me.com>> wrote:

    On 2011-11-10 11:21, Jonathan M Davis wrote:

        Well, for better or worse, we don't have an official policy on
        it. In general, I
        think that the tact is to try and rename the item so that it
        doesn't pose a
        problem, but that's not always possible (hence
        FunctionAttribute.pure_). In
        this case, since it comes from something else, it looks like it
        really should
        be some version of delete. However, whereas FunctionAttribute
        pretty much
        _had_ to be as close to the keyword as possible since it
        represented the
        keyword, that's not the case here, and given how ugly it is to
        tack the _ on,
        del seems like a reasonable solution.

        In any case, if we want something official, we'd have to discuss
        it, and we
        generally have a hard time coming to any kind of consensus on
        stuff like that.
        So, I don't generally try unless it seems particularly important.

        - Jonathan M Davis


    I think we should write down, somewhere, what we have, what we have
    agreed on unofficially. It may not be complete and not contain
    details for everything but it would at least be something. Instead
    of having to explain this every time we get a new contributor to
    Phobos or one has to try to find this information in the newsgroup.

    --
    /Jacob Carlborg







 Nov 10 2011



prev sibling  parent  Jonas Drewsen <jdrewsen nospam.com>  writes:


On 10/11/11 08.27, Jacob Carlborg wrote:

 On 2011-11-09 21:53, Jonas Drewsen wrote:

 Hi,

 So after the last review of the etc.curl there were some requests for
 making it simpler.




<snip>


 What is the actual Phobos guideline in naming things that are keywords
 in D. I'm thinking about Method.del, shouldn't it be Method.delete_ or
 something similar, don't know what the guidelines say in this case. BTW,
 I would really like to have more official guidelines somewhere at the
 dpl page.


Yes.. it would be nice with a standard for this. I have the same problem 
with CurlOption.intrface which it ugly I think. But so is 
CurlOption.interface_

/Jonas



 Nov 10 2011



prev sibling  parent reply Jacob Carlborg <doob me.com>  writes:


On 2011-11-09 21:53, Jonas Drewsen wrote:

 Hi,

 So after the last review of the etc.curl there were some requests for
 making it simpler.

 After some thinking, refactoring and documentation I've come up with a
 somewhat changed API.

 Before sending it for official review again I would really like some
 comments on the new API and if you think it is better or worse etc.

 http://freeze.steamwinter.com/D/web/phobos/etc_curl.html

 Thanks,
 Jonas


BTW, why is this "etc.culr" and not "std.curl".

-- 
/Jacob Carlborg



 Nov 09 2011



  parent reply Jonas Drewsen <jdrewsen nospam.com>  writes:


On 10/11/11 08.32, Jacob Carlborg wrote:

 On 2011-11-09 21:53, Jonas Drewsen wrote:

 Hi,

 So after the last review of the etc.curl there were some requests for
 making it simpler.




<snip>


 BTW, why is this "etc.culr" and not "std.curl".


I think Andrei mentioned that he wanted it to go to std.curl. Another 
option would be std.net.curl.

Anyone have an opinion about this?

/Jonas



 Nov 10 2011



 next sibling parent  Jacob Carlborg <doob me.com>  writes:


On 2011-11-10 13:14, Jonas Drewsen wrote:

 On 10/11/11 08.32, Jacob Carlborg wrote:

 On 2011-11-09 21:53, Jonas Drewsen wrote:

 Hi,

 So after the last review of the etc.curl there were some requests for
 making it simpler.




 <snip>


 BTW, why is this "etc.culr" and not "std.curl".


 I think Andrei mentioned that he wanted it to go to std.curl. Another
 option would be std.net.curl.

 Anyone have an opinion about this?

 /Jonas


I forgot about the std.net package. I think that would be a good place.

-- 
/Jacob Carlborg



 Nov 10 2011



prev sibling next sibling parent reply Brad Anderson <eco gnuk.net>  writes:


On Thu, Nov 10, 2011 at 5:14 AM, Jonas Drewsen <jdrewsen nospam.com> wrote:


 On 10/11/11 08.32, Jacob Carlborg wrote:


 On 2011-11-09 21:53, Jonas Drewsen wrote:


 Hi,

 So after the last review of the etc.curl there were some requests for
 making it simpler.


 <snip>



  BTW, why is this "etc.culr" and not "std.curl".


 I think Andrei mentioned that he wanted it to go to std.curl. Another
 option would be std.net.curl.

 Anyone have an opinion about this?

 /Jonas


I think putting the high level API (which I really like the clean and
simple design of, by the way) under something like std.net and the low
level curl specific API in etc.curl might be nice.  I know what curl is but
looking for std.curl to download a file isn't obvious for anyone who isn't
aware of curl.  This also leaves the option of keeping the high level API
and swapping out the curl backend with something else if that was ever
needed or wanted.  That's not very likely to happen anytime soon but I
think a good guideline might be to keep the phobos API focused on what,
specifically, you want to do rather than what is doing what you want to do.



 Nov 10 2011



  parent reply "Marco Leise" <Marco.Leise gmx.de>  writes:


Am 10.11.2011, 17:52 Uhr, schrieb Brad Anderson <eco gnuk.net>:


 On Thu, Nov 10, 2011 at 5:14 AM, Jonas Drewsen <jdrewsen nospam.com>  
 wrote:


 On 10/11/11 08.32, Jacob Carlborg wrote:


 On 2011-11-09 21:53, Jonas Drewsen wrote:


 Hi,

 So after the last review of the etc.curl there were some requests for
 making it simpler.


 <snip>



  BTW, why is this "etc.culr" and not "std.curl".


 I think Andrei mentioned that he wanted it to go to std.curl. Another
 option would be std.net.curl.

 Anyone have an opinion about this?

 /Jonas


 I think putting the high level API (which I really like the clean and
 simple design of, by the way) under something like std.net and the low
 level curl specific API in etc.curl might be nice.  I know what curl is  
 but
 looking for std.curl to download a file isn't obvious for anyone who  
 isn't
 aware of curl.  This also leaves the option of keeping the high level API
 and swapping out the curl backend with something else if that was ever
 needed or wanted.  That's not very likely to happen anytime soon but I
 think a good guideline might be to keep the phobos API focused on what,
 specifically, you want to do rather than what is doing what you want to  
 do.


Ok, let's do an experiment. I don't think I've seen community polls yet,  
so I created one on a random online poll site:

http://www.easypolls.net/poll.html?p=4ebd3219011eb0e4518d35ab

When everyone has cast their vote, there should be no useless discussion  
about the decision afterwards. :) ... I hope.
(I wont vote myself this time, so it doesn't look like I created a poll  
tailored to my opinion.)



 Nov 11 2011



  parent reply "Marco Leise" <Marco.Leise gmx.de>  writes:


Am 11.11.2011, 16:30 Uhr, schrieb Marco Leise <Marco.Leise gmx.de>:


 Ok, let's do an experiment. I don't think I've seen community polls yet,  
 so I created one on a random online poll site:

 http://www.easypolls.net/poll.html?p=4ebd3219011eb0e4518d35ab

 When everyone has cast their vote, there should be no useless discussion  
 about the decision afterwards. :) ... I hope.
 (I wont vote myself this time, so it doesn't look like I created a poll  
 tailored to my opinion.)


There are 12 votes in now and these are the results so far:

etc.curl                                    50% (6)
std.net.curl                                25% (3)
etc.curl (low-level) / std.net (high-level) 17% (2)
std.curl                                     8% (1)

Thanks for voting and generating a clear result !



 Nov 12 2011



  parent  Jonas Drewsen <jdrewsen nospam.com>  writes:


Den 12-11-2011 13:17, Marco Leise skrev:

 Am 11.11.2011, 16:30 Uhr, schrieb Marco Leise <Marco.Leise gmx.de>:


 Ok, let's do an experiment. I don't think I've seen community polls
 yet, so I created one on a random online poll site:

 http://www.easypolls.net/poll.html?p=4ebd3219011eb0e4518d35ab

 When everyone has cast their vote, there should be no useless
 discussion about the decision afterwards. :) ... I hope.
 (I wont vote myself this time, so it doesn't look like I created a
 poll tailored to my opinion.)


 There are 12 votes in now and these are the results so far:

 etc.curl 50% (6)
 std.net.curl 25% (3)
 etc.curl (low-level) / std.net (high-level) 17% (2)
 std.curl 8% (1)

 Thanks for voting and generating a clear result !


I'll stick to etc.curl for now then.

/Jonas



 Nov 13 2011



prev sibling  parent reply Mirko Pilger <pilger cymotec.de>  writes:


 Anyone have an opinion about this?


i mean no disrespect to the work you have invested. i like the new api 
and looking forward to use it, but isn't the integration of curl into 
phobos a kind of placeholder until somebody finally implements 
std.net.http, std.net.ftp, etc.?

i really believe high or low level wrapper code around 3rd party 
libraries shouldn't "pollute" the std.* namespace and stay in etc.* or 
maybe end up in a new package like lib.*, external.* or extra.*.

mirko



 Nov 11 2011



  parent  Jonas Drewsen <jdrewsen nospam.com>  writes:


Den 11-11-2011 19:25, Mirko Pilger skrev:

 Anyone have an opinion about this?


 i mean no disrespect to the work you have invested. i like the new api
 and looking forward to use it, but isn't the integration of curl into
 phobos a kind of placeholder until somebody finally implements
 std.net.http, std.net.ftp, etc.?

 i really believe high or low level wrapper code around 3rd party
 libraries shouldn't "pollute" the std.* namespace and stay in etc.* or
 maybe end up in a new package like lib.*, external.* or extra.*.

 mirko


I agree. That is why I put it into etc.curl initially and not std.curl. 
Then when a package manager is in place (think CPAN) the entire etc.* 
could be pulled out. But until then it is a nice place to have it I think.

Anyway - it seems there are several people who wants it in std for now. 
I guess it wouldn't be that bad to move it out of std again at some 
point when a native http/ftp is implemented.

/Jonas



 Nov 11 2011