http.download: ?download-to -> download-to-once

[factor.git] / basis / http / download / download-docs.factor

diff --git a/basis/http/download/download-docs.factor b/basis/http/download/download-docs.factor
index 72dc7b2d9d69dab6f053b57703f7b16c7624f898..76f3a19dc07a7edaa08d4934fc53c2cb7a8e79a4 100644 (file)
--- a/basis/http/download/download-docs.factor
+++ b/basis/http/download/download-docs.factor
@@ -7,11 +7,19 @@ 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-to
 { $values { "url" { $or url string } } { "file" "a pathname 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-to
+{ $values { "url" { $or url string } } { "file" "a pathname 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." } ;
 
 
@@ -22,6 +30,7 @@ ARTICLE: "http.download" "HTTP Download Utilities"
 { $subsections
     download
     download-to
+    download-once-to
 }
 ;