http.download: fix up stack effects and write some docs

2 files changed, 79 insertions, 7 deletions

diff --git a/basis/http/download/download-docs.factor b/basis/http/download/download-docs.factor
index d3c97cdd68..8f0a42c174 100644
--- a/basis/http/download/download-docs.factor
+++ b/basis/http/download/download-docs.factor
@@ -4,24 +4,82 @@ USING: calendar help.markup help.syntax io.pathnames kernel math
 strings urls ;
 IN: http.download
 
+
 HELP: download
 { $values { "url" { $or url string } } { "path" "a pathname string" } }
 { $description "Downloads the contents of the URL to a file in the " { $link current-directory } " having the same file name and returns the pathname." }
 { $notes "Use this to download the file every time." }
 { $errors "Throws an error if the HTTP request fails." } ;
 
+HELP: download-into
+{ $values
+    { "url" url } { "directory" "a pathname string" }
+    { "path" "a pathname string" }
+}
+{ $description "Downloads the contents of the URL to a file the given directory and returns the pathname." } ;
+
 HELP: download-as
 { $values { "url" { $or url string } } { "path" "a pathname string" } }
 { $description "Downloads the contents of the URL to a file with the given pathname and returns the pathname." }
 { $notes "Use this to download the file every time." }
 { $errors "Throws an error if the HTTP request fails." } ;
 
+
+HELP: download-once
+{ $values
+    { "url" url }
+    { "path" "a pathname string" }
+}
+{ $description "Downloads a file to " { $link current-directory } " and returns the path. If the path already exists, this word does not download it again." } ;
+
+HELP: download-once-into
+{ $values
+    { "url" url } { "directory" "a pathname string" }
+    { "path" "a pathname string" }
+}
+{ $description "Downloads a file to " { $snippet "directory" } " and returns the path. If the path already exists, this word does not download it again." } ;
+
 HELP: download-once-as
 { $values { "url" { $or url string } } { "path" "a pathname string" } }
 { $description "If the file exists on disk, returns that pathname without downloading anything. Otherwise, downloads the contents of the URL to a file with the given pathname and returns the pathname." }
 { $notes "Use this if the contents of the URL are not expected to change." }
 { $errors "Throws an error if the HTTP request fails." } ;
 
+HELP: download-outdated
+{ $values
+    { "url" url } { "duration" duration }
+    { "path" "a pathname string" }
+}
+{ $description "Download a URL into " { $link current-directory } " unless the an existing file has a timestamp newer than " { $snippet "duration" } " ago." } ;
+
+HELP: download-outdated-as
+{ $values
+    { "url" url } { "path" "a pathname string" } { "duration" duration }
+    { "path'" "a pathname string" }
+}
+{ $description "Download a URL into a directory unless the an existing file has a timestamp newer than " { $snippet "duration" } " ago." } ;
+
+HELP: download-outdated-into
+{ $values
+    { "url" url } { "directory" "a pathname string" } { "duration" duration }
+    { "path" "a pathname string" }
+}
+{ $description "Download a URL into a directory unless the an existing file has a timestamp newer than " { $snippet "duration" } " ago." } ;
+
+
+HELP: download-to-temporary-file
+{ $values
+    { "url" url }
+    { "path" "a pathname string" }
+}
+{ $description "Downloads a url to a unique temporary file in " { $link current-directory } " named " { $snippet "temp.XXXXXXXXXreal-file-name.ext.temp" } "." } ;
+
+HELP: download-name
+{ $values
+    { "url" url }
+    { "name" object }
+}
+{ $description "Turns a URL into a filename suitable for downloading to locally." } ;
 
 ARTICLE: "http.download" "HTTP Download Utilities"
 "The " { $vocab-link "http.download" } " vocabulary provides utilities for downloading files from the web."
@@ -29,9 +87,20 @@ ARTICLE: "http.download" "HTTP Download Utilities"
 "Utilities to retrieve a " { $link url } " and save the contents to a file:"
 { $subsections
     download
+    download-into
     download-as
+    download-once
+    download-once-into
     download-once-as
+    download-outdated
+    download-outdated-into
+    download-outdated-as
 }
-;
+
+"Helper words:"
+{ $subsections
+    download-to-temporary-file
+    download-name
+} ;
 
 ABOUT: "http.download"
diff --git a/basis/http/download/download.factor b/basis/http/download/download.factor
index 618cfa2f9e..0ac7f7e42d 100644
--- a/basis/http/download/download.factor
+++ b/basis/http/download/download.factor
@@ -91,23 +91,26 @@ PRIVATE>
 : download-as ( url path -- path )
     [ download-to-temporary-file ] dip [ ?move-file ] keep ;
 
-: download-into ( url path -- path )
+: download-into ( url directory -- path )
     [ [ download-to-temporary-file ] keep ] dip
     dup make-directories to-directory nip
     [ move-file ] keep ;
 
+: download ( url -- path )
+    dup download-name download-as ;
+
 : download-once-as ( url path -- path )
     dup file-exists? [ nip ] [ download-as ] if ;
 
-: download-once-into ( url path -- path ) to-directory download-once-as ;
+: download-once-into ( url directory -- path ) to-directory download-once-as ;
 
 : download-once ( url -- path ) "resource:" download-once-into ;
 
-: download-outdated-as ( url path duration -- path )
+: download-outdated-as ( url path duration -- path' )
     2dup delete-when-old [ drop download-as ] [ drop nip ] if ;
 
-: download-outdated-into ( url path duration -- path )
+: download-outdated-into ( url directory duration -- path )
     [ to-directory ] dip download-outdated-as ;
 
-: download ( url -- path )
-    dup download-name download-as ;
+: download-outdated ( url duration -- path )
+    [ dup download-name "resource:" to-directory nip ] dip download-outdated-as ;