The trivial-download Reference Manual

This is the trivial-download Reference Manual, version 0.3, generated automatically by Declt version 4.0 beta 2 "William Riker" on Sun Sep 15 06:56:25 2024 GMT+0.

Table of Contents


1 Introduction


2 Systems

The main system appears first, followed by any subsystem dependency.


2.1 trivial-download

Download files from Common Lisp

Maintainer

Fernando Borretti <>

Author

Fernando Borretti <>

Home Page

https://github.com/eudoxia0/trivial-download

Source Control

(GIT git@github.com:eudoxia0/trivial-download.git)

Bug Tracker

https://github.com/eudoxia0/trivial-download/issues

License

MIT

Long Description

# trivial-download

[![Build Status](https://travis-ci.org/eudoxia0/trivial-download.svg?branch=master)](https://travis-ci.org/eudoxia0/trivial-download)
[![Coverage Status](https://coveralls.io/repos/eudoxia0/trivial-download/badge.svg?branch=master)](https://coveralls.io/r/eudoxia0/trivial-download?branch=master) [![Quicklisp](http://quickdocs.org/badge/trivial-download.svg)](http://quickdocs.org/trivial-download/)

trivial-download allows you to download files from the Internet from Common
Lisp. It even provides a progress bar.

# Usage

“‘lisp
cl-user> (download "http://www.google.com/robots.txt" "/tmp/robots.txt")
Downloading "http://www.google.com/robots.txt" (Unknown size)
t
cl-user> (download "https://github.com/favicon.ico" "/tmp/favicon.ico")
Downloading "https://github.com/favicon.ico" (6.518 kB) .........10%.........20%.........30%.........40%.........50%.........60%.........70%.........80%.........90%.........100%t
“‘

# Documentation

You probably want the ‘download‘ function, which downloads files from the
network to the local disk. If you want more control over that – like, say,
writing the downloaded bytes to a database instead – you want the
‘with-download‘ macro.

‘trivial-download‘ downloads everything in chunks that are ‘*chunk-size*‘ bytes
long. ‘*chunk-size*‘, by default, is 256.

* [Function] ‘download‘ *(url output)*

Downloads the content of ‘url‘ and writes it to ‘output‘. The file is written as
it is downloaded, chunk-by-chunk, not downloaded into memory and written at
once.

* [Macro] ‘with-download‘ *(url (file-size total-bytes-read array stream) &rest body)*

Downloads the contents of ‘url‘, executing ‘body‘ in every chunk.

The extra arguments are:

- ‘stream‘: A ‘flexi-io-stream‘ bivalent stream.
- ‘file-size‘: The size, in bytes, of the file to download.
- ‘bytes-read‘: The number of bytes read.
- ‘array‘: As every chunk is downloaded, its contents are written to ‘array‘.

Example:

“‘lisp
(with-download "https://github.com/favicon.ico"
;; Do something
)
“‘

* [Macro] ‘with-download-progress‘ *(url (file-size total-bytes-read array stream) &rest body)*

The same as ‘with-download‘, only this prints progress information while
downloading.

# License

Copyright (c) 2014-2015 Fernando Borretti (eudoxiahp@gmail.com)

Licensed under the MIT License.

Version

0.3

Dependency

drakma (system).

Source

trivial-download.asd.

Child Component

src (module).


3 Modules

Modules are listed depth-first from the system components tree.


3.1 trivial-download/src

Source

trivial-download.asd.

Parent Component

trivial-download (system).

Child Component

trivial-download.lisp (file).


4 Files

Files are sorted by type and then listed depth-first from the systems components trees.


4.1 Lisp


4.1.1 trivial-download/trivial-download.asd

Source

trivial-download.asd.

Parent Component

trivial-download (system).

ASDF Systems

trivial-download.


4.1.2 trivial-download/src/trivial-download.lisp

Source

trivial-download.asd.

Parent Component

src (module).

Packages

trivial-download.

Public Interface
Internals

5 Packages

Packages are listed by definition order.


5.1 trivial-download

Source

trivial-download.lisp.

Use List

common-lisp.

Public Interface
Internals

6 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


6.1 Public Interface


6.1.1 Special variables

Special Variable: *chunk-size*

Files are downloaded in chunks of this many bytes.

Package

trivial-download.

Source

trivial-download.lisp.


6.1.2 Macros

Macro: with-download (url (file-size total-bytes-read array stream &key quiet) &body body)

Execute body at every chunk that is downloaded.

Package

trivial-download.

Source

trivial-download.lisp.

Macro: with-download-progress (url (file-size total-bytes-read array stream &key quiet) &body body)

Like with-download but with a progress bar.

Package

trivial-download.

Source

trivial-download.lisp.


6.1.3 Ordinary functions

Function: download (url output &key quiet)

Download a file and save it to a pathname. Directories containing ‘output‘ are created if they don’t exist.

Package

trivial-download.

Source

trivial-download.lisp.

Function: file-size (headers)

Take the headers of a http request, return the size (in bytes).

Package

trivial-download.

Source

trivial-download.lisp.


6.1.4 Conditions

Condition: http-error
Package

trivial-download.

Source

trivial-download.lisp.

Direct superclasses

error.

Direct methods
Direct slots
Slot: code
Initargs

:code

Readers

response-code.

Writers

(setf response-code).


6.2 Internals


6.2.1 Special variables

Special Variable: +size-symbol-map+
Package

trivial-download.

Source

trivial-download.lisp.


6.2.2 Ordinary functions

Function: http-request (url &rest args)
Package

trivial-download.

Source

trivial-download.lisp.

Function: human-file-size (size)

Take a file size (in bytes), return it as a human-readable string.

Package

trivial-download.

Source

trivial-download.lisp.

Function: percentage (total-bytes current-bytes)
Package

trivial-download.

Source

trivial-download.lisp.


6.2.3 Generic functions

Generic Reader: response-code (condition)
Generic Writer: (setf response-code) (condition)
Package

trivial-download.

Methods
Reader Method: response-code ((condition http-error))
Writer Method: (setf response-code) ((condition http-error))
Source

trivial-download.lisp.

Target Slot

code.


Appendix A Indexes


A.1 Concepts