Next: (maak niri), Previous: (maak main), Up: API
The download half of a task, without a shell string: curl and wget with their common flags as keyword arguments, plus the few higher-level answers a task actually asks for – fetch a URL to a file, read a URL into a string, check a status code, post JSON, mirror a site.
Every command helper has an ‘-argv’ builder. The builder returns the words without running anything: that is what the procedure feeds to ‘run’, what –dry-run prints, and what a test can assert without a network. The builders are exported for the same reason the archive and container builders are: a task that needs to log or extend a command should not have to rebuild its flags. ‘download’ is the exception, because it chooses between the two programs; it has no single command line of its own.
‘download’ is the one helper that chooses a program. ‘fetch-command’ is a parameter, detected as curl when it is installed and wget otherwise, and overridable with MAAK_FETCH or a lexical ‘parameterize’. The direct curl- and wget- helpers never consult it: when a task needs a particular tool, it names that tool.
Nothing here touches the network when the module is loaded.
Default value:
"curl"
Run curl with ARGUMENTS, a list of strings; see ‘curl-argv’.
Return the argv that runs curl with ARGUMENTS.
The escape hatch for a flag no helper models; nothing is handed to a shell, so an argument with a space in it stays one argument.
Download URL with curl; see ‘curl-download-argv’.
Return the argv that downloads URL to OUTPUT.
Without OUTPUT curl keeps the remote name, which is what –remote-name means. DIRECTORY is curl’s –output-dir, and CREATE-DIRS? makes the parents of the destination. RESUME? continues a partial download.
Fetch URL with curl; see ‘curl-get-argv’ for the options.
Return the argv that fetches URL with curl.
The defaults are the ones a task wants: redirects are followed, an HTTP error is a failure, and the progress meter is replaced by silence plus real errors. OUTPUT writes the body to a file, OUTPUT-DIR names the directory for it, and CREATE-DIRS? creates the parents. RESUME? continues a partial file.
Ask for URL’s headers with curl; see ‘curl-head-argv’.
Return the argv that asks for URL’s headers with a HEAD request.
Run curl with ARGUMENTS and return what it printed.
This is the reading counterpart of ‘curl’: the body is a value a task can trim, split or parse. In dry-run mode nothing runs, the command is printed, and the empty string comes back.
Send a POST request to URL; see ‘curl-post-argv’.
Return the argv that sends a POST request to URL.
DATA is a body string, JSON is a JSON body sent with curl’s –json (which also sets the content type and Accept header), DATA-FILE is a file whose bytes are the body, and FORM is a list of –form fields. At least one of them must be given. METHOD defaults to POST; pass another method for an API that spells its update differently.
Return URL’s HTTP status code as a number.
A transport failure raises unless ALLOW-FAILURE? is #t, in which case #f is returned when curl prints no code. An HTTP error is still a status: 404 comes back as 404.
Return the argv that prints URL’s HTTP status code.
The body is discarded and –fail is deliberately left off, so a 404 is reported as 404 rather than as a failed download.
Fetch URL with curl and return the body as a string.
Use this instead of ‘curl-get’ when the task needs the response, not a line on the terminal. A non-zero curl exits non-zero and raises, unless ALLOW-FAILURE? is #t.
Return the argv that fetches URL’s body for a task to read.
Upload FILE to URL with curl; see ‘curl-upload-argv’.
Return the argv that uploads FILE to URL with curl.
METHOD defaults to PUT, which is what an object store usually expects; pass POST for an API that takes the file as a form upload.
Return the download program ‘download’ should use.
PREFERRED, when non-empty, wins unchanged. Otherwise curl is chosen when it is on PATH, then wget. The fallback is curl even when neither is installed, so a missing program is reported as a missing program rather than silently replaced by the other one.
PATH is the search path, PATH itself by default, so the choice can be tested without changing the process environment.
(detect-fetch-command #:path search-path) (detect-fetch-command #:preferred "wget")
Download URL with the detected downloader.
TOOL is curl or wget; the default comes from ‘fetch-command’, which is curl when it is installed, wget otherwise, or whatever MAAK_FETCH names. OUTPUT is the destination file (the remote name when it is #f), DIRECTORY is the directory it belongs in, and CONTINUE? resumes a partial file. HEADERS, USER-AGENT, TIMEOUT and RETRIES are passed to either program; USER and PASSWORD become curl’s –user or wget’s –user/–password.
(download "https://example.org/release.tar.gz"
#:output "release.tar.gz"
#:continue? #t)
(parameterize ((fetch-command "wget"))
(download "https://example.org/" #:output "index.html"))
Return #t when COMMAND, the downloader ‘download’ would use, is on PATH.
Run wget with ARGUMENTS, a list of strings; see ‘wget-argv’.
Return the argv that runs wget with ARGUMENTS.
The escape hatch for a flag no helper models; nothing is handed to a shell, so an argument with a space in it stays one argument.
Download URL with wget; see ‘wget-download-argv’.
Return the argv that downloads URL with wget.
OUTPUT names the file, DIRECTORY is the prefix the file is written under, and CONTINUE? resumes a partial file. QUIET? silences the progress output; TIMESTAMPING? and NO-CLOBBER? decide what to do with an existing file.
Mirror the site at URL with wget; see ‘wget-mirror-argv’.
Return the argv that mirrors the site at URL with wget.
The defaults are the ones a documentation snapshot wants: recursion that stays under URL, no host directory at the top, and a DIRECTORY prefix when one is named. PAGE-REQUISITES? also fetches the images and stylesheets, CONVERT-LINKS? rewrites the saved pages to point at them, and CUT-DIRS drops leading path components from the local tree.
Run wget with ARGUMENTS and return what it printed.
In dry-run mode nothing runs, the command is printed, and the empty string comes back.
Fetch URL with wget and return the body as a string.
wget writes the body to standard output with –output-document=-, which is what lets a task read it instead of finding a file afterwards. The progress output is silenced so the result is only the body.
Return the argv that fetches URL’s body for a task to read.
Next: (maak niri), Previous: (maak main), Up: API