inverse: Fix docs

[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 76f3a19dc07a7edaa08d4934fc53c2cb7a8e79a4..8f0a42c174980e035a54b4a007839423e6bc41b0 100644 (file)
--- 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-to
-{ $values { "url" { $or url string } } { "file" "a pathname string" } { "path" "a pathname string" } }
+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-to
-{ $values { "url" { $or url string } } { "file" "a pathname string" } { "path" "a pathname string" } }
+
+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-to
-    download-once-to
+    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"