From 5c193a888e84836b3d3e19539e5c580da11d2a79 Mon Sep 17 00:00:00 2001 From: Pavel Semyonov Date: Wed, 28 Sep 2022 13:50:52 +0700 Subject: [PATCH 1/4] Extend usi functions descriptions --- doc/reference/reference_lua/uri.rst | 51 +++++++++++++++++++++++------ 1 file changed, 41 insertions(+), 10 deletions(-) diff --git a/doc/reference/reference_lua/uri.rst b/doc/reference/reference_lua/uri.rst index c32f68fdd8..ebac6fff8a 100644 --- a/doc/reference/reference_lua/uri.rst +++ b/doc/reference/reference_lua/uri.rst @@ -57,9 +57,23 @@ Below is a list of all ``uri`` functions. .. function:: parse(URI-string) + Parse a URI string by components. Possible components are: + + * ``fragment`` + * ``host`` + * ``ipv4`` + * ``ipv6`` + * ``login`` + * ``password`` + * ``path`` + * ``query`` + * ``scheme`` + * ``service`` + * ``unix`` + :param URI-string: a Uniform Resource Identifier - :return: URI-components-table. Possible components are fragment, host, - login, password, path, query, scheme, service. + :return: URI-components table. + :rtype: Table **Example:** @@ -70,31 +84,48 @@ Below is a list of all ``uri`` functions. --- ... - tarantool> uri.parse('http://x.html#y') + tarantool> uri.parse('scheme://login:password@host:service'.. + '/path1/path2/path3?q1=v1&q2=v2&q3=v3:1|v3:2#fragment') --- - - host: x.html - scheme: http - fragment: y + - login: login + params: + q1: + - v1 + q2: + - v2 + q3: + - v3:1|v3:2 + service: service + fragment: fragment + password: password + scheme: scheme + query: q1=v1&q2=v2&q3=v3:1|v3:2 + host: host + path: /path1/path2/path3 ... .. _uri-format: .. function:: format(URI-components-table[, include-password]) - :param URI-components-table: a series of name:value pairs, one for each + Form a URI string from its components. ``uri.format()`` is the reverse of + :ref:`uri.parse() `. + + :param URI-components-table: a series of ``name=value`` pairs, one for each component :param include-password: boolean. If this is supplied and is ``true``, then the password component is rendered in clear text, otherwise it is omitted. - :return: URI-string. Thus uri.format() is the reverse of uri.parse(). + :return: URI-string :rtype: string **Example:** .. code-block:: tarantoolsession - tarantool> uri.format({host = 'x.html', scheme = 'http', fragment = 'y'}) + tarantool> uri.format({scheme='scheme', login='login', password='password', host='host', + service='service', path='/path1/path2/path3', query='q1=v1&q2=v2&q3=v3'}) --- - - http://x.html#y + - scheme://login@host:service/path1/path2/path3 ... From d53713b88a26e7f6156858d5139c5ee3e879ef80 Mon Sep 17 00:00:00 2001 From: Pavel Semyonov Date: Wed, 28 Sep 2022 14:08:02 +0700 Subject: [PATCH 2/4] Extend usi functions descriptions --- doc/reference/reference_lua/uri.rst | 28 ++++++++++++++++++++++------ 1 file changed, 22 insertions(+), 6 deletions(-) diff --git a/doc/reference/reference_lua/uri.rst b/doc/reference/reference_lua/uri.rst index ebac6fff8a..343921e8bd 100644 --- a/doc/reference/reference_lua/uri.rst +++ b/doc/reference/reference_lua/uri.rst @@ -6,7 +6,8 @@ Overview =============================================================================== -A "URI" is a "Uniform Resource Identifier". +*URI* stands for *Uniform Resource Identifier* - a sequence of characters that +identifies a logical or physical resource. The `IETF standard `_ says a URI string looks like this: @@ -27,7 +28,7 @@ has three components: * ``tarantool.org/x.html`` is the path, * ``y`` is the fragment. -Tarantool's URI module provides routines which convert URI strings into their +Tarantool's URI module provides functions that convert URI strings into their components, or turn components into URI strings. =============================================================================== @@ -71,8 +72,10 @@ Below is a list of all ``uri`` functions. * ``service`` * ``unix`` + ``uri.parse()`` is the reverse of :ref:`uri.format() `. + :param URI-string: a Uniform Resource Identifier - :return: URI-components table. + :return: URI components table. :rtype: Table @@ -108,15 +111,28 @@ Below is a list of all ``uri`` functions. .. function:: format(URI-components-table[, include-password]) - Form a URI string from its components. ``uri.format()`` is the reverse of - :ref:`uri.parse() `. + Form a URI string from its components. Possible components are: + + * ``fragment`` + * ``host`` + * ``ipv4`` + * ``ipv6`` + * ``login`` + * ``password`` + * ``path`` + * ``query`` + * ``scheme`` + * ``service`` + * ``unix`` + + ``uri.format()`` is the reverse of :ref:`uri.parse() `. :param URI-components-table: a series of ``name=value`` pairs, one for each component :param include-password: boolean. If this is supplied and is ``true``, then the password component is rendered in clear text, otherwise it is omitted. - :return: URI-string + :return: URI string :rtype: string **Example:** From 5de306c7c6ec6d4eaccc05c134ba76215c57239e Mon Sep 17 00:00:00 2001 From: Pavel Semyonov Date: Wed, 28 Sep 2022 14:13:12 +0700 Subject: [PATCH 3/4] Fix grammar --- doc/reference/reference_lua/uri.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/reference/reference_lua/uri.rst b/doc/reference/reference_lua/uri.rst index 343921e8bd..156296dec4 100644 --- a/doc/reference/reference_lua/uri.rst +++ b/doc/reference/reference_lua/uri.rst @@ -58,7 +58,7 @@ Below is a list of all ``uri`` functions. .. function:: parse(URI-string) - Parse a URI string by components. Possible components are: + Parse a URI string into components. Possible components are: * ``fragment`` * ``host`` From 5ee7c4fb2663d9c1a0925129d37e3e768d24281f Mon Sep 17 00:00:00 2001 From: Pavel Semyonov Date: Fri, 30 Sep 2022 18:40:23 +0700 Subject: [PATCH 4/4] Fix list punctuation --- doc/reference/reference_lua/uri.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/reference/reference_lua/uri.rst b/doc/reference/reference_lua/uri.rst index 156296dec4..e8da505213 100644 --- a/doc/reference/reference_lua/uri.rst +++ b/doc/reference/reference_lua/uri.rst @@ -24,8 +24,8 @@ A common type, a hierarchical URI, looks like this: For example the string ``'https://tarantool.org/x.html#y'`` has three components: -* ``https`` is the scheme, -* ``tarantool.org/x.html`` is the path, +* ``https`` is the scheme. +* ``tarantool.org/x.html`` is the path. * ``y`` is the fragment. Tarantool's URI module provides functions that convert URI strings into their