Module: Escape

Module | Escape
In: | escape.rb

Escape module provides several escape functions.

- URI
- HTML
- shell command

### Methods

html_attr_value html_form html_text shell_command shell_single_word uri_path uri_segment

### Classes and Modules

Class Escape::HTMLAttrValue
Class Escape::HTMLEscaped
Class Escape::PercentEncoded
Class Escape::ShellEscaped
Class Escape::StringWrapper

### Public Instance methods

html_attr_value(str)

Escape.html_attr_value encodes a string as a double-quoted HTML attribute using character references. It returns an instance of HTMLAttrValue.

     Escape.html_attr_value("abc") #=> #<Escape::HTMLAttrValue: "abc">
     Escape.html_attr_value("a&b") #=> #<Escape::HTMLAttrValue: "a&amp;b">
     Escape.html_attr_value("ab&<>\"c") #=> #<Escape::HTMLAttrValue: "ab&amp;&lt;&gt;&quot;c">
     Escape.html_attr_value("a'c") #=> #<Escape::HTMLAttrValue: "a'c">

It escapes 4 characters:

- ’&’ to ’&amp;’
- ’<’ to ’&lt;’
- ’>’ to ’&gt;’
- ’"’ to ’&quot;’

html_form(pairs, sep='&')

Escape.html_form composes HTML form key-value pairs as a x-www-form-urlencoded encoded string. It returns an instance of PercentEncoded.

Escape.html_form takes an array of pair of strings or an hash from string to string.

     Escape.html_form([["a","b"], ["c","d"]]) #=> #<Escape::PercentEncoded: a=b&c=d>
     Escape.html_form({"a"=>"b", "c"=>"d"}) #=> #<Escape::PercentEncoded: a=b&c=d>

In the array form, it is possible to use same key more than once. (It is required for a HTML form which contains checkboxes and select element with multiple attribute.)

     Escape.html_form([["k","1"], ["k","2"]]) #=> #<Escape::PercentEncoded: k=1&k=2>

If the strings contains characters which must be escaped in x-www-form-urlencoded, they are escaped using %-encoding.

     Escape.html_form([["k=","&;="]]) #=> #<Escape::PercentEncoded: k%3D=%26%3B%3D>

The separator can be specified by the optional second argument.

     Escape.html_form([["a","b"], ["c","d"]], ";") #=> #<Escape::PercentEncoded: a=b;c=d>

See HTML 4.01 for details.

html_text(str)

Escape.html_text escapes a string appropriate for HTML text using character references. It returns an instance of HTMLEscaped.

It escapes 3 characters:

- ’&’ to ’&amp;’
- ’<’ to ’&lt;’
- ’>’ to ’&gt;’

     Escape.html_text("abc") #=> #<Escape::HTMLEscaped: abc>
     Escape.html_text("a & b < c > d") #=> #<Escape::HTMLEscaped: a &amp; b &lt; c &gt; d>

This function is not appropriate for escaping HTML element attribute because quotes are not escaped.

shell_command(command)

Escape.shell_command composes a sequence of words to a single shell command line. All shell meta characters are quoted and the words are concatenated with interleaving space. It returns an instance of ShellEscaped.

     Escape.shell_command(["ls", "/"]) #=> #<Escape::ShellEscaped: ls />
     Escape.shell_command(["echo", "*"]) #=> #<Escape::ShellEscaped: echo '*'>

Note that system(*command) and system(Escape.shell_command(command)) is roughly same. There are two exception as follows.

- The first is that the later may invokes /bin/sh.
- The second is an interpretation of an array with only one element: the element is parsed by the shell with the former but it is recognized as single word with the later. For example, system(*["echo foo"]) invokes echo command with an argument "foo". But system(Escape.shell_command(["echo foo"])) invokes "echo foo" command without arguments (and it probably fails).

shell_single_word(str)

Escape.shell_single_word quotes shell meta characters. It returns an instance of ShellEscaped.

The result string is always single shell word, even if the argument is "". Escape.shell_single_word("") returns #<Escape::ShellEscaped: ’’>.

     Escape.shell_single_word("") #=> #<Escape::ShellEscaped: ''>
     Escape.shell_single_word("foo") #=> #<Escape::ShellEscaped: foo>
     Escape.shell_single_word("*") #=> #<Escape::ShellEscaped: '*'>

uri_path(str)

Escape.uri_path escapes URI path using percent-encoding. The given path should be a sequence of (non-escaped) segments separated by "/". The segments cannot contains "/". It returns an instance of PercentEncoded.

     Escape.uri_path("a/b/c") #=> #<Escape::PercentEncoded: a/b/c>
     Escape.uri_path("a?b/c?d/e?f") #=> #<Escape::PercentEncoded: a%3Fb/c%3Fd/e%3Ff>

The path is the part after authority before query in URI, as follows.

      scheme://authority/path#fragment

See RFC 3986 for details of URI.

Note that this function is not appropriate to convert OS path to URI.

uri_segment(str)

Escape.uri_segment escapes URI segment using percent-encoding. It returns an instance of PercentEncoded.

     Escape.uri_segment("a/b") #=> #<Escape::PercentEncoded: a%2Fb>

The segment is "/"-splitted element after authority before query in URI, as follows.

      scheme://authority/segment1/segment2/.../segmentN?query#fragment

See RFC 3986 for details of URI.

[Validate]