elisp url库简要说明

Table of Contents

1. URL库简介

2. 解析URI

2.1. URI对象的结构

2.2. URI编码说明

3. 访问URI资源

4. 与各特定类型URI有关的函数

4.1. http和https协议

4.1.1. Cookies

4.1.2. Http编码

4.1.3. Http URL Options

4.1.4. 如何处理HTTP document

4.2. file与ftp协议

4.3. info

4.4. mailto协议

4.5. news,nntp与snews协议

4.6. rlogin,telnet和tn3270协议

4.7. irc

4.8. data协议

4.9. nfs协议

4.10. man协议

5. 其他函数说明

5.1. 缓存

5.2. 代理

5.3. 网关

5.4. 历史

6. 客户化配置

URL库简介

URL库可以用来解析URI或者从指定的URI处访问资源.

解析URI

一个URI由多个组件组成,使用函数`url-generic-parse-url’可以将一个URI字符串解析成URI对象(一个由各个URI组件组成的结构体). 使用`url-recreate-url’可以将解析的URI对象组合成URI字符串

(url-generic-parse-url uri-string)

将uri-string解析成URI对象,该对象由多个URI组件组成的结构体

(url-recreate-url url-obj)

将URI对象反转为URI字符串

URI对象的结构

URI对象是一个CL结构体,该结构体由如下slot组成:

slot	意义	值类型	是否可以为nil	备注
type	URI的协议类型	字符串	否
user	用户名	字符串	是
password	用户密码	字符串	是	nowadays, passwords are transmitted by other means, not as part of a URI
host	主机地址	字符串	是
port	端口号	整型	是	若为nil表示协议类型的默认端口号
filename	由URI的”path”和”query”两部分组成	字符串	是	“path”和”query”由字符\`?’拼接. “filename”的意义,由各协议类型决定
target	fragment组件(指明”secondary resource”的地址)	字符串	是
fullness	指明URI是否为完全指定的URI	t或nil	是

由于URI对象是一个CL结构体,因此这些slot都有各自的accessor函数,名为`url-SLOTNAME’

URI编码说明

`url-generic-parse-url’函数在解析URI时,不会转义URI字符串中的非ASCII字符. 然而根据 RFC 3986协议的要求,URI中的非ASC字符,需要被转换成百分号加UTF-8字节序列的形式,这一转换过程被称为”percent-encoding”.

(url-encode-url url-string)

该函数将url-string转换为标准格式. 它会将url-string中的的非ASCII字符转换为合适的形式,并将URI中的协议类型部分转换为小写形式

(url-hexify-string STRING &optional ALLOWED-CHARS)

该函数对STRING进行”percent-encoding”处理,并返回结果.

该函数与`url-encode-url’的不同之处在于,它不会分析URI的组成部分,而会对STRING中的所有字符进行转换. 而`url-encode-url’会解析URI中的各组成部分,仅对该转换的部分进行转换,例如

(url-encode-url "HTTP://测试?你=好")    ;=> "http://%E6%B5%8B%E8%AF%95?%E4%BD%A0=%E5%A5%BD"
(url-hexify-string "HTTP://测试?你=好") ;=> "HTTP%3A%2F%2F%E6%B5%8B%E8%AF%95%3F%E4%BD%A0%3D%E5%A5%BD"

参数ALLOWED-CHARS指明了那些字符可以不被转换,它需要为一个vector,且若它的第N个元素不为nil,则表示字符N可以不被转换.

若参数ALLOWED-CHARS为nil,表示不被转换的字符遵照RFC 3986的"unreserved characters"

(url-unhex-string string &optional allow-newline)

该函数是`url-hexify-string’的逆操作.

若参数ALLOW-NEWLINE为非nil,则表示允许转换的字符中包含回车符,而回车符一般是不允许出现在URI中的.

访问URI资源

下面三个函数可以用来访问URI资源. 且这三个函数的URL参数 既可以为URI字符串,也可以URI对象. 且函数内部会调用`url-encode-url’对URI字符串进行标准化

(url-rerieve-synchronously URL)

该函数同步访问URL处的资源,并将资源内容写到一个buffer中,然后返回该buffer作为返回值.

若URL指向无效地址,或者URL为`dired’,`info’,`mailto’类型,该函数返回nil

(url-retrieve URL CALLBACK &optional CBARGS SILENT NO-COOKIES)

该函数异步访问URL处的资源,将访问到的资源插入一个buffer中(buffer中既包括MIME头,也包括资源内容),然后将该buffer作为当前buffer,并调用

(apply CALLBACK STATUS CBARGS)

. 其中

STATUS为一个plist,指明了访问URI资源的过程中发生了什么事情,其中 最近发生的事件放在最前. 若没有事件发生,则STATUS为nil

plist中的每个pair可以是以下格式:

(:redirect NEW-URL)

表示请求被重定向到NEW-URL

(:error (ERROR-SYMBOL . DATA))

表示有错误发生.

若参数SILENT为非nil,则不会显示处理过程的信息

若参数NO-COOKIES为非nil,则不会存储和发送cookies

该函数的返回值为插入资源内容的buffer. 但若函数返回前整个处理过程已经结束,则返回nil

(url-queue-retrieve URL CALLBACK &optional CBARGS SILENT NO-COOKIES)

该函数与`url-retrieve’类似,但会根据`url-queue-parallel-processes’的值显示同时运行的网络进程. 并根据`url-queue-timeout’的值设置超时事件,单位为秒

使用该函数前,需要

(require 'url-queue)

配置项url-queue-parallel-processes

改变量的值限定了`url-queue-retrieve’最大能够并行运行的网络进程

配置项url-queue-timeout

该变量的值设定了`url-queue-retrieve’的超时时间

(url-copy-file URL NEWNAME &optional OK-IF-ALREADY-EXISTS KEEP-TIME PRESERVE-UID-GID)

该函数基于url-retrieve实现了将URL下载成NEWNAME文件保存.

该函数是定义在url-handlers.el中的

url-request-method

指定URL库请求URL资源时的方法,通常为POST或GET

url-request-extra-headers

请求URL时的头部信息列表,该变量应为元素为’(HEADERS . CONTENTS)的alist

url-request-data

请求URL时的数据.

与各特定类型URI有关的函数

http和https协议

当url处理https协议时,会调用`ssl’库中的网关方法,详见Gateways in general

配置项url-honor-refresh-requests

默认为t,表示`url’库支持HTTP协议中的”Refresh” header. 该头信息一般用于服务器告诉客户端从同一个或另一个URL重新加载一次文档.

若值为nil,表示`url’库忽略HTTP协议中的”Refresh” header.

其他值,表示询问用户是否忽略.

Cookies

命令(url-cookie-list)

若存在cookies,则该命令创建一个名为`*url cookies*’的buffer,列出当前的cookies.

在该buffer中,可以使用`C-k’调用`url-cookie-delete’命令删除指定cookie

配置项url-cookie-file

该配置项指明了cookies存放的文件路径.

默认为`url-configuration-directory’变量值目录下的`cookies’文件

配置项url-cookie-confirmation

当服务端请求创建cookies时,提示用户确定

配置项url-cookie-multiple-line

Specifies whether to put all cookies for the server on one line in the HTTP request to satisfy broken servers like http://www.hotmail.com.

配置项url-cookie-trusted-urls

该值为正则表达式的列表,匹配正则表达式的URL,总是允许它创建cookies

配置项url-cookie-untrusted-urls

该值为正则表达式的列表,匹配正则表达式的URL,总是拒绝它创建cookies

配置项url-cookie-save-interval

多少秒后,自动保存cookie到磁盘.默认为1小时

Http编码

HTTP协议允许客户端向服务端表达对请求文档的语言和编码的偏好.

下面的变量都是字符串类型. 它可以是表示单个的选择,也可以是由逗号分隔的多个选择.

默认情况下,各个选择的优先级从高到低递减. 但每个选择后都可以加上`;q=优先级’来明确指定该选择的优先级. 优先级的值为从0到1的小数

没有明确用`;q’指定优先级的选择,默认级别为1

配置项 url-mime-charset-string

指定客户端请求服务端文档时的字符集偏好

The default series is generated automatically from the associated MIME types of all defined coding systems, sorted by the coding system priority specified in Emacs. 参见Recognizing Code Systems

配置项 url-mime-language-string

指明客户端对语言的偏好. HTTP请求中的Accept-language域

指定语言时,使用RFC 1766的缩写标准. 如`en’表示英语,`de’表示德语

`*’ means get the first available language (as opposed to the default).

Http URL Options

使用`url-http-options’函数,可以获取url服务端的options信息

(url-http-options url)

获取URL服务端的options信息,以plist的形式返回.

methods

一个由symbol组成的list,指明了URL资源支持那些HTTP method

dav

一个由数字组成的list,指明了URL资源支持那些DAV协议的版本

dasl

A list of supported DASL search types supported (string form).

ranges

A list of the units available for use in partial document fetches.

p3p

The “Platform For Privacy Protection” description for the resource.

Currently this is just the raw header contents.

如何处理HTTP document

访问HTTP资源时,会把HTTP头部信息和HTTP document的信息都插入buffer中.

处理HTTP头部信息时,需要用到MIME库. 参见Emacs mime

file与ftp协议

URL库将ftp和file协议看成是一样的. 若URL指定的是本地文件,则访问URL资源时,URL直接读取该文件内容. 若URL指定的是远程文件时,URL通过`Ange-FTP’库来读取文件内容. 参见Remote Files

当访问的文件为‘.z’, ‘.gz’, ‘.Z’, ‘.bz2’, or ‘.xz’这几类文件时,会自动解压该文件. 且这些后缀名是硬编码在代码中的,无法通过配置`jka-compr-compression-info-list’来更改

用户项url-directory-index-file

该配置项指定了当URL指向的是一个目录时,访问该目录下的哪个文件. 默认值为’index.html’. 若该文件存在且可读则访问该文件,否则Emacs使用`Dired Mode’显示目录

info

info协议是非标准的协议.这种URL的格式为”

mailto协议

mailto协议的格式为`

news,nntp与snews协议

news,nntp与snews协议被定义来读取Usenet上的新闻组. URL通过Gnus库来访问这些协议的内容

为了兼容非标准的新闻阅读客户端,url库允许news协议的URL中带上主机和端口域

news和nntp URL有如下格式:

获取NEWSGROUP中的消息列表

获取指定MESSAGE-ID的消息内容

news:*

获取所有的可用新闻组

nntp://HOST:PORT/NEWSGROUP / nntp://HOST:PORT/MESSAGE-ID / nntp://HOST:PORT/*

类似news协议说明

snews协议与nntp协议类似,只是它通过SSL传输内容,且默认端口为563,而nntp与news协议的端口为119

配置项url-news-server

该变量指定了当URL中未指定news server的情况下,默认从哪个news server上获取新闻.

默认值为nil,表示使用环境变量`NNTPSERVER’或`news’的值

rlogin,telnet和tn3270协议

这些协议用来通过终端模拟器登录远程服务器. 他们的格式为`telnet://USER:PASSWORD@HOST:PORT’. 但其实PASSWORD域会被忽略,PORT域也可以忽略表示使用协议标准端口

URL在处理这些协议时,会在`terminal-emulator’ buffer中调用`rlogin’,`telnet’和`tn3270’外部程序

irc

irc协议的格式为`

data协议

data协议,用于描述URL中的MIME data,其格式为`data:[MEDIA-TYPE][;BASE64],DATA’

其中MEDIA-TYPE为MIME的`Content-Type’字符串. 默认值为`text/plain;charset=US-ASCII’

若有`;base64’,则表示后面的DATA域是经过base64编码过的.

nfs协议

nfs协议类似ftp,但是它会通过NFS automounter将远程路径安装到本地来使用.

nfs协议的格式为`nfs://USER:PASSWORD@HOST:PORT/FILE’

url-nfs-automounter-directory-spec

该变量为字符串类型,指明了如何调用NFS automounter.

字符串中有很多以`%’开头的转义字符,说明如下:

%h: NFS server的主机名

%n: NFS server的端口号

%u: 认证的用户名

%p: 认证的密码

%f: 远程服务器上的文件路径

%%: 字符`%’

man协议

man协议为非标准协议,它的格式为`man:PAGE-SPEC’

url在访问man协议的资源时,会将PAGE-SPEC传递给函数`man’

其他函数说明

缓存

缓存机制会将访问的资源缓存到本地,当下次再访问该资源时,url库会检查资源是否更过,若未更新过则直接使用本地缓存.

目前缓存不会自动被清理.

配置项url-automatic-caching

是否开启自动缓存

配置项url-cache-directory

指定存放cache文件的目录,默认为`url-configuration-diectory’变量值下的`cache’子目录

配置项url-cache-creation-function

该变量指定一个转换函数,将URL转换成对应的缓存文件的 绝对路径

url提供两个可选函数:`url-cache-create-filename-using-md5’和`url-cache-create-filename-human-readable’

(url-cache-expired URL &optional EXPIRE-TIME)

判断URL的缓存是否比EXPIRE-TIME要旧. 该函数一般用来判断缓存是否过期.

EXPIRE-TIME的默认值为`url-cache-expire-time’

若`url-standalone-mode’为非nil,则缓存永远不过期,该函数永远返回nil

配置项url-cache-expire-time

缓存过期时限,单位为秒

(url-fetch-from-cache url)

从缓存中访问URL的资源. 该函数返回一个buffer,gaibuffer的内容为缓存的数据.

代理

按照惯例,程序会检查环境变量`PROTOCOL_proxy’来获取\`PROTOCOL’协议的代理地址. 这里`PROTOCOL’可以使`http’,`ftp’等任何一个网络协议.

`PROTOCOL_proxy’环境变量的值可以是如下几种形式:

主机地址

主机地址:端口

完整proxy的URL

环境变量`NO_PROXY’指定了那些URL不通过代理服务器访问. 各URL之间使用逗号分隔. URL内可以使用*号作为通配符. 以.开头的URL表示的是该域名下的所有网址.

下面是一个`NO_PROXY’的例子:

NO_PROXY="*.aventail.com,home.com,.seanet.com"

URL库也遵循上面的惯例,且URL库在寻找环境变量时会忽略其大小写.

配置项url-proxy-services

该变量的值是一个alist,其中的元素格式为’(URL-TYPE . HOST:PORT)或’(no_proxy . URL-REGEXP) .例如

(setq url-proxy-services
'(("http"     . "proxy.aventail.com:80")
("no_proxy" . "^.*\\(aventail\\|seanet\\)\\.com")))

网关

(url-open-stream name buffer host service)

创建连接到HOST的流链接,该链接可能途径某个网关.

其他参数与`open-network-steam’中的参数意义一致.

若`url-gateway-unplugged’为非nil,则不会创建链接

url-gateway-local-host-regexp

该变量值为正则表达式,创建连接到匹配该正则表达式的HOST时,采取直连方式,不经过网关转发.

nil表示所有的连接都通过网关转发

url-gateway-method

该变量值为symbol类型,它决定了使用那种方式连接gateway. 可选值有以下几种:

telnet

在telnet远程服务器之前,先telnet到网关服务器

rlogin

类似telnet,不同之处在于使用rlogin登录不需要用户名和密码

socks

通过socks服务连接到网关

tls

通过TLS连接到网关

native

直接连接到网关(默认值)

配置项url-gateway-telnet-host

该变量的值指定了telnet到哪个网关主机.

使用telnet网关方法的时候,先要telnet到这个网关主机,然后才能telnet到其他远程服务器上

配置项url-gateway-telnet-parameters

telnet网关主机时传递給telnet程序的参数

配置项url-gateway-telnet-password-prompt

telnet到网关主机后,主机输入密码提示的正则表达式

配置项url-gateway-telnet-user-name

telnet到网关主机的用户名

配置项url-gateway-telnet-password

telnet到网关主机的密码

配置项url-gateway-prompt-pattern

网关主机的shell prompt正则表达式

配置项url-gateway-rlogin-host

telnet到远程服务器前先用rlogin登录到哪个网关服务器

配置项url-gateway-rlogin-parameters

rlogin到网关服务器时,传递给rsh的参数

配置项url-gateway-rlogin-user-name

rlogin到网关服务器时的用户名

url-gateway-unplugged

若该变量值为非nil,则URL不会再创建新的网络连接.

A typical case is when rendering HTML in a mail user agent, when external URLs should not be activated, particularly to avoid “bugs” which “call home” by fetch single-pixel images and the like

历史

url库会记住访问过的URL,这种记住历史的机制使得URL补全成为可能.

当调用函数`url-do-setup’设置URL库时,会自动开启历史机制.

url库使用一个名为`url-history-hash-table’变量来存储历史,其中URL作为key,访问该URL的时间戳作为value

注意:目前记住历史的机制没有设置限制

(url-history-update-url url time)

该函数更新历史表中URL的访问时间为TIME

配置项url-history-track

是否开启历史机制. 若值为非nil则URL库会保存所有访问URL的历史记录

若值为t,则Emacs session退出时,会保存历史记录到磁盘中

默认为nil

配置项url-history-file

保存历史记录的文件路径,默认为`url-configuration-directory’变量值目录下的`history’文件

配置项url-history-save-interval

自动保存历史记录的时间间隔,单位为秒. 默认是1小时.

注意,若你直接修改该变量,而不是通过Custom更改,且更改之前已经执行过了`url-do-setup’,则需要调用函数`url-history-setup-save-timer’才能生效

(url-history-parse-history &optional history-file)

解析history-file,并根据文件内容重设历史纪录

history-file默认为`url-history-file’的值

(url-history-save-history &optional history-file)

保存当前的历史记录到history-file中

history-file默认为`url-history-file’的值

(url-completion-function string predicate functiion)

该函数可以用来从历史记录中补全URL

客户化配置

配置项temporary-file-directory

指定临时文件的存放目录

配置项url-configuration-directory

指定URL库将它的各种配置文件,缓存文件等其他文件存放在哪个目录中.

默认该目录为`user-emacs-directory’变量值目录下的”url/”子目录

url-debug

指定URL库显示那种类型的调试信息. 这些调试信息会记录在名为`*URL-DEBUG*’ buffer中

该变量的值可能为:

t: 记录所有的信息

数字: 记录所有的信息,同时这些信息会通过`message’函数输出

列表: 列表中指定了那种类型的信息会被记录

配置项:url-personal-mail-address

配置项:url-privacy-level

配置项:url-uncompressor-alist

配置项:url-passwd-entry-func

配置项:url-standalone-mode

配置项:url-bad-port-list

配置项:url-max-password-attempts

配置项:url-temporary-directory

配置项:url-show-status

配置项:url-confirmation-func

URL库用来提示用户选择yes or no的函数.

配置项:url-gateway-method

该变量值为symbol类型,它决定了使用那种方式连接gateway. 可选值有以下几种:

telnet

在telnet远程服务器之前,先telnet到网关服务器

rlogin

类似telnet,不同之处在于使用rlogin登录不需要用户名和密码

socks

通过socks服务连接到网关

tls

通过TLS连接到网关

native

直接连接到网关(默认值)