The asdf-encodings Reference Manual

Table of Contents

The asdf-encodings Reference Manual

This is the asdf-encodings Reference Manual, generated automatically by Declt version 2.4 "Will Decker" on Wed Jun 20 10:46:30 2018 GMT+0.

1 Introduction

ASDF-ENCODINGS

This library allows you to use ASDF with Lisp source files
that use an encoding different from either ASCII or UTF-8.
It depends on ASDF 2.21 or later (actually 2.20.18 or later).

TODO:
(1) actually support more implementations.
(2) Add a test suite.
(3) Test it.
(4) Add more corner cases.


==== Exported Functionality ====

The asdf-encodings defines a package ASDF-ENCODINGS.
It uses ASDF 2.21's asdf:*encoding-external-format-hook*
to define a simple mapping from encodings specified as portable keywords
to implementation-defined external formats.
It issues warnings or errors when no matching external-format is available,
depending on asdf-encodings.


function ENCODING-EXTERNAL-FORMAT (ENCODING &KEY (ON-ERROR *ON-UNSUPPORTED-ENCODING*))
  This function takes a keyword which is one of
  :default
  :utf-8 :utf8
  :latin1 :latin-1 :iso-8859-1
  a whole lot of other possibilities as per asdf-encodings::*encodings*
  and returns a value suitable for use as :external-format argument to
  the current implementation's CL:OPEN, CL:LOAD or CL:COMPILE-FILE functions.
  If the encoding is not supported on this implementation, the ON-ERROR
  argument, which is one of :ERROR, :WARN, NIL, specifies what to do.

variable *ON-UNSUPPORTED-ENCODING*
  One of :error, :warn or nil,
  specifies what to do when passed an unsupported encoding.
  Defaults to :error.

function DETECT-FILE-ENCODING (PATHNAME)
  This function takes a pathname designator,
  and returns a portable encoding as detected by the file contents,
  either an emacs-style -*- coding: foo -*- declaration,
  or something deduced from the octet patterns in the file.

function NORMALIZE-ENCODING (ENCODING)
  Given a portable encoding keyword, returns the normalized keyword
  describing that encoding on the current implementations, if any,
  or NIL if the encoding is not present on the implementation
  (or not recognized by asdf-encodings).

function FIND-IMPLEMENTATION-ENCODING (ENCODING)
  Given a normalized encoding keyword, returns
  an external-format suitable for use on the current implementation, if any.

2 Systems

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

2.1 asdf-encodings

Author

Francois-Rene Rideau

Description

Portable interface to character encodings and your implementation’s external-format

Defsystem Dependency

asdf (at least version 3.0)

Source

asdf-encodings.asd (file)

Components

• pkgdcl.lisp (file)
• encodings.lisp (file)
• autodetect.lisp (file)
• asdf-support.lisp (file)
• initialization.lisp (file)

3 Files

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

3.1 Lisp

3.1.1 asdf-encodings.asd

Location

asdf-encodings.asd

Systems

asdf-encodings (system)

3.1.2 asdf-encodings/pkgdcl.lisp

Parent

asdf-encodings (system)

Location

pkgdcl.lisp

Packages

asdf-encodings

3.1.3 asdf-encodings/encodings.lisp

Dependency

pkgdcl.lisp (file)

Parent

asdf-encodings (system)

Location

encodings.lisp

Exported Definitions

• find-implementation-encoding (function)
• normalize-encoding (function)

Internal Definitions

• *encodings* (special variable)
• *normalized-encodings* (special variable)
• initialize-normalized-encodings (function)

3.1.4 asdf-encodings/autodetect.lisp

Dependency

pkgdcl.lisp (file)

Parent

asdf-encodings (system)

Location

autodetect.lisp

Exported Definitions

detect-file-encoding (function)

Internal Definitions

• decode-ascii-encoded-declaration (function)
• detect-buffer-encoding-header (function)
• detect-utf-8 (function)

3.1.5 asdf-encodings/asdf-support.lisp

Dependency

pkgdcl.lisp (file)

Parent

asdf-encodings (system)

Location

asdf-support.lisp

Exported Definitions

• *on-unsupported-encoding* (special variable)
• encoding-external-format (function)

Internal Definitions

register-asdf-encodings (function)

3.1.6 asdf-encodings/initialization.lisp

Dependencies

• encodings.lisp (file)
• autodetect.lisp (file)
• asdf-support.lisp (file)

Parent

asdf-encodings (system)

Location

initialization.lisp

4 Packages

Packages are listed by definition order.

4.1 asdf-encodings

Source

pkgdcl.lisp (file)

Use List

• asdf/interface
• common-lisp

Exported Definitions

• *on-unsupported-encoding* (special variable)
• detect-file-encoding (function)
• encoding-external-format (function)
• find-implementation-encoding (function)
• normalize-encoding (function)

Internal Definitions

• *encodings* (special variable)
• *normalized-encodings* (special variable)
• decode-ascii-encoded-declaration (function)
• detect-buffer-encoding-header (function)
• detect-utf-8 (function)
• initialize-normalized-encodings (function)
• register-asdf-encodings (function)

5 Definitions

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

5.1 Exported definitions

5.1.1 Special variables

Special Variable: *on-unsupported-encoding*

One of :error, :warn or nil, specifies what to do when passed an unsupported encoding.

Package

asdf-encodings

Source

asdf-support.lisp (file)

5.1.2 Functions

Function: detect-file-encoding FILE

Package

asdf-encodings

Source

autodetect.lisp (file)

Function: encoding-external-format ENCODING &key ON-ERROR

Package

asdf-encodings

Source

asdf-support.lisp (file)

Function: find-implementation-encoding ENCODING

Package

asdf-encodings

Source

encodings.lisp (file)

Function: normalize-encoding ENCODING

Package

asdf-encodings

Source

encodings.lisp (file)

5.2 Internal definitions

5.2.1 Special variables

Special Variable: *encodings*

Package

asdf-encodings

Source

encodings.lisp (file)

Special Variable: *normalized-encodings*

Package

asdf-encodings

Source

encodings.lisp (file)

5.2.2 Functions

Function: decode-ascii-encoded-declaration BUFFER AVAILABLE START SIZE OFFSET

Package

asdf-encodings

Source

autodetect.lisp (file)

Function: detect-buffer-encoding-header BUFFER AVAILABLE

Package

asdf-encodings

Source

autodetect.lisp (file)

Function: detect-utf-8 FILE

Package

asdf-encodings

Source

autodetect.lisp (file)

Function: initialize-normalized-encodings &optional WARN

Package

asdf-encodings

Source

encodings.lisp (file)

Function: register-asdf-encodings ()

Package

asdf-encodings

Source

asdf-support.lisp (file)

Appendix A Indexes

A.1 Concepts

A.2 Functions

A.3 Variables

A.4 Data types