Vim documentation: vital/Web/URI
main help file
vital/Web/URI.txt URI manipulation library
Maintainer: tyru <tyru.exe@gmail.com>
==============================================================================
CONTENTS Vital.Web.URI-contents
INTRODUCTION Vital.Web.URI-introduction
INTERFACE Vital.Web.URI-interface
Functions Vital.Web.URI-functions
URI Object Vital.Web.URI-URI
PatternSet Object Vital.Web.URI-PatternSet
NOTES Vital.Web.URI-notes
TODO Vital.Web.URI-todo
REFERENCES Vital.Web.URI-references
==============================================================================
INTRODUCTION Vital.Web.URI-introduction
Vital.Web.URI is URI manipulation library.
==============================================================================
INTERFACE Vital.Web.URI-interface
------------------------------------------------------------------------------
FUNCTIONS Vital.Web.URI-functions
new({str} [, {default} [, {patternset}]]) Vital.Web.URI.new()
Returns a Vital.Web.URI-URI object constructed by {str}.
If {default} is given and {str} is invalid,
returns {default}.
Otherwise, throws an exception.
See Vital.Web.URI-PatternSet for {patternset}.
new_from_uri_like_string({str} [, {default} [, {patternset}]])
Vital.Web.URI.new_from_uri_like_string()
This is same as Vital.Web.URI.new()
except when {str} has no scheme.
then this function prepends the string "http://" to {str}.
new_from_seq_string({str} [, {default} [, {patternset}]])
Vital.Web.URI.new_from_seq_string()
This is same as Vital.Web.URI.new(), except
1. When {str} contains illegal trailing string,
then this function DOES NOT throw an exception.
2. Returns List of [{uri}, {origuri}, {rest}]
{uri}
Vital.Web.URI-URI object constructed by {str}.
{origuri}
Original string which was used for constructing {uri}.
{rest}
Rest of string after parsing {str}.
is_uri({str}) Vital.Web.URI.is_uri()
Returns non-zero value if {str} is URI.
Returns zero value otherwise.
let URI = vital#{plugin-name}#new().import('Web.URI')
let ERROR = []
let like_uri = (URI.is_uri(a:str, ERROR) isnot ERROR)
like_uri({str}) Vital.Web.URI.like_uri()
Returns non-zero value if {str} looks like URI.
Returns zero value otherwise.
This is the Vital.Web.URI.new_from_uri_like_string() version
of Vital.Web.URI.is_uri().
(This uses Vital.Web.URI.new_from_uri_like_string()
instead of Vital.Web.URI.new())
Vital.Web.URI.new_default_pattern_set()
new_default_pattern_set()
Creates a new Vital.Web.URI-PatternSet object.
Vital.Web.URI.clone_pattern_set()
clone_pattern_set({patternset})
Clones a Vital.Web.URI-PatternSet object.
encode({str} [, {char-enc}]) Vital.Web.URI.encode()
Encodes {str} to Percent-encoding string.
Converts {str} to {char-enc}(or "utf-8" when omitted) before encode.
When {char-enc} is an empty string, {str} is not converted.
decode({str} [, {char-enc}]) Vital.Web.URI.decode()
Decodes {str} that is encoded by Percent-encoding.
Converts result from {char-enc}(or "utf-8" when omitted) to 'encoding'
after decode.
When {char-enc} is an empty string, result is not converted.
Note that this function does not convert "+" to " ".
Because this function is based on percent-encoding in RFC3986.
http://tools.ietf.org/html/rfc3986#section-2.1
But "+" conversion is based on
application/x-www-form-urlencoded in RFC1866.
http://tools.ietf.org/html/rfc1866#section-8.2.1
------------------------------------------------------------------------------
URI OBJECT Vital.Web.URI-URI Vital.Web.URI-object
NOTE: See Vital.Web.HTTP for encoding/decoding functions.
* Vital.Web.HTTP.encodeURI()
* Vital.Web.HTTP.encodeURIComponent()
* Vital.Web.HTTP.decodeURI()
Vital.Web.URI-URI.scheme() Vital.Web.URI-object.scheme()
Vital.Web.URI-URI.host() Vital.Web.URI-object.host()
Vital.Web.URI-URI.port() Vital.Web.URI-object.port()
Vital.Web.URI-URI.path() Vital.Web.URI-object.path()
Vital.Web.URI-URI.opaque() Vital.Web.URI-object.opaque()
Vital.Web.URI-URI.authority() Vital.Web.URI-object.authority()
Vital.Web.URI-URI.query() Vital.Web.URI-object.query()
Vital.Web.URI-URI.fragment() Vital.Web.URI-object.fragment()
scheme([{str}])
userinfo([{str}])
host([{str}])
port([{str}])
path([{str}])
authority([{str}])
opaque([{str}])
query([{str}])
fragment([{str}])
If no arguments are given, returns each part value.
If {str} is given, sets {str} as each part value,
and returns the URI object itself.
NOTE: opaque(), authority() do not support {str} yet.
NOTE: port({str}) allows both Number and String for {str}.
to_iri([{char-enc}]) Vital.Web.URI-object.to_iri()
Same as Vital.Web.URI-object.to_string(),
but do URI-unescape for Vital.Web.URI-object.path() part.
Passes {char-enc} to Vital.Web.URI.decode() if specified.
to_string() Vital.Web.URI-object.to_string()
Returns URI representation of this object.
Vital.Web.URI-URI.is_scheme()
Vital.Web.URI-URI.is_userinfo()
Vital.Web.URI-URI.is_host()
Vital.Web.URI-URI.is_port()
Vital.Web.URI-URI.is_path()
Vital.Web.URI-URI.is_query()
Vital.Web.URI-URI.is_fragment()
is_scheme({str})
is_userinfo({str})
is_host({str})
is_port({str})
is_path({str})
is_query({str})
is_fragment({str})
Returns non-zero value if {str} has right syntax
for each component. Returns zero otherwise.
Vital.Web.URI-URI.clone()
clone()
This method clones a URI object itself.
let s:URI = vital#{plugin-name}#new().import('Web.URI')
let uri = s:URI.new('http://example.com/')
let copyuri = uri.clone().relative('/a/b/c')
echo uri.to_string()
" => 'http://example.com/'
echo copyuri.to_string()
" => 'http://example.com/a/b/c'
Vital.Web.URI-URI.relative()
relative({reluri})
This method ...
* Calculates a URI from
base URI and relative URI({reluri}).
* Changes the URI object itself (destructive).
* Returns the URI object itself.
* Calls Vital.Web.URI-URI.relative() implicitly.
Example:
let s:URI = vital#{plugin-name}#new().import('Web.URI')
let BASE_URI = 'http://example.com/foo/bar'
let RELATIVE_URI = '../baz'
echo s:URI.new(BASE_URI).relative(RELATIVE_URI).to_string()
" => 'http://example.com/baz'
let BASE_URI = 'http://example.com/foo/bar/'
let RELATIVE_URI = '../baz'
echo s:URI.new(BASE_URI).relative(RELATIVE_URI).to_string()
" => 'http://example.com/foo/baz'
Vital.Web.URI-URI.canonicalize()
canonicalize()
This method ...
* Canonicalizes the URI.
* Changes the URI object itself (destructive).
* Returns the URI object itself.
See Web.URI.* modules for supported schemes.
For example, the following four URIs
becomes equivalent URI (http://example.com/).
* http://example.com
* http://example.com/
* http://example.com:/
* http://example.com:80/
Example:
let s:URI = vital#{plugin-name}#new().import('Web.URI')
echo s:URI.new('http://example.com:80/').to_string()
" => 'http://example.com/'
Vital.Web.URI-URI.default_port()
default_port()
This method returns the default port for current scheme.
(e.g.: 80 for "http" scheme)
See Web.URI.* modules for supported schemes.
------------------------------------------------------------------------------
PATTERNSET OBJECT Vital.Web.URI-PatternSet
PatternSet object is the set of patterns for URI syntax.
This object has each method for URI components based on RFC3986
and all components are fully customizable.
e.g.: scheme(), host(), path(), ...
Below is the example how to customize URI component definition.
This example allows more tolerant URI parsing.
(This example is from https://github.com/tyru/open-browser.vim/issues/72)
The default PatternSet is very strict
because it is completely RFC3986 based implementation.
(_default_ means the object which
Vital.Web.URI.new_default_pattern_set() returns)
According to RFC3986, URI allows
* ' (single quote)
* ( (left parenthesis)
* ) (right parenthesis)
but these characters often appears in ordinary text.
This code lets the parser ignore these characters.
let s:LoosePatternSet = s:URI.new_default_pattern_set()
" Remove "'", "(", ")" from default sub_delims().
function! s:LoosePatternSet.sub_delims() abort
return '[!$&*+,;=]'
endfunction
" Ignore trailing string after URI.
let NONE = []
let ret = URI.new_from_seq_string(
\ 'http://example.com)', NONE, s:LoosePatternSet)
if ret isnot NONE
...
endif
get({component}) Vital.Web.URI-PatternSet.get()
Returns each component definition.
let s:PatternSet = s:URI.new_default_pattern_set()
echo s:PatternSet.get('scheme')
Listing all customizable components here (alphabetic order).
NOTE: DON'T call these methods directly.
These methods are used when defining customized PatternSet.
See how-to at Vital.Web.URI-PatternSet.
dec_octet() Vital.Web.URI-PatternSet.dec_octet()
fragment() Vital.Web.URI-PatternSet.fragment()
h16() Vital.Web.URI-PatternSet.h16()
hexdig() Vital.Web.URI-PatternSet.hexdig()
host() Vital.Web.URI-PatternSet.host()
ip_literal() Vital.Web.URI-PatternSet.ip_literal()
ipv4address() Vital.Web.URI-PatternSet.ipv4address()
ipv6address() Vital.Web.URI-PatternSet.ipv6address()
ipv_future() Vital.Web.URI-PatternSet.ipv_future()
ls32() Vital.Web.URI-PatternSet.ls32()
path() Vital.Web.URI-PatternSet.path()
path_abempty() Vital.Web.URI-PatternSet.path_abempty()
path_absolute() Vital.Web.URI-PatternSet.path_absolute()
path_noscheme() Vital.Web.URI-PatternSet.path_noscheme()
path_rootless() Vital.Web.URI-PatternSet.path_rootless()
pchar() Vital.Web.URI-PatternSet.pchar()
pct_encoded() Vital.Web.URI-PatternSet.pct_encoded()
port() Vital.Web.URI-PatternSet.port()
query() Vital.Web.URI-PatternSet.query()
reg_name() Vital.Web.URI-PatternSet.reg_name()
scheme() Vital.Web.URI-PatternSet.scheme()
segment() Vital.Web.URI-PatternSet.segment()
segment_nz() Vital.Web.URI-PatternSet.segment_nz()
segment_nz_nc() Vital.Web.URI-PatternSet.segment_nz_nc()
sub_delims() Vital.Web.URI-PatternSet.sub_delims()
unreserved() Vital.Web.URI-PatternSet.unreserved()
userinfo() Vital.Web.URI-PatternSet.userinfo()
==============================================================================
NOTES Vital.Web.URI-notes
Empty authority
-----------------
Empty authority is allowed for "file" scheme,
but not for almost schemes, for example, "http" scheme.
However, Web.URI does not concern about
authority handling for each scheme,
because it is just a parser library for URI.
If a user wants to raise an error for a such case,
needs to raise an error for him or herself.
==============================================================================
TODO Vital.Web.URI-todo
* Punycode (RFC3492)
* IRI support (RFC3987)
* Vital.Web.URI-URI.opaque() with an argument
* Vital.Web.URI-URI.authority() with an argument
* Perl's URI, URI::Find module
*
*
*
*
*
* RFC 5890: IDNA (Internationalized Domain Names for Applications)
* A Label
* U Label
* NR-LDH Label
* should recompose string by the algorithm
based on https://tools.ietf.org/html/rfc3986#section-5.3
* : Write tests
* : Write document
* URN Support
* urn:isbn
* urn:uuid
* urn:ietf:rfc
* urn:oid
==============================================================================
REFERENCES Vital.Web.URI-references
* URL: Living Standard
https://url.spec.whatwg.org/#informative
* RFC3986
http://tools.ietf.org/html/rfc3986
* RFC3986 Errata
https://www.rfc-editor.org/errata_search.php?rfc=3987
==============================================================================
vim:tw=78:fo=tcq2mM:ts=8:ft=help:norl
top - main help file - tag index