Overview
Capybara::Selector::CSS provides utility methods for escaping CSS identifiers and splitting compound CSS selector strings into individual selectors.
Description
The CSS class lives within the Capybara::Selector namespace and serves two primary purposes: escaping arbitrary strings into valid CSS identifiers, and splitting comma-separated CSS selector lists into their individual components while respecting quoted strings, brackets, and parentheses.
The class defines several constants for Unicode-aware CSS lexical analysis (S, H, UNICODE, NONASCII, ESCAPE, NMSTART) and contains a nested Splitter class that implements a character-by-character state machine to correctly parse and split compound selectors.
CSS.escape handles leading hyphens/underscores, validates the first character against NMSTART, and encodes non-alphanumeric characters via CSS.escape_char. The escape_char method uses backslash notation for printable ASCII special characters and zero-padded hex notation for everything else.
Usage
Use CSS.escape when you need to safely embed dynamic values (e.g., element IDs containing special characters) into CSS selector strings. Use CSS.split when you have a comma-separated CSS selector list and need to process each selector independently, such as when adapting combined selectors for XPath translation or individual matching.
Code Reference
Source Location
Signature
module Capybara
class Selector
class CSS
def self.escape(str) -> String
def self.escape_char(char) -> String
def self.split(css) -> Array<String>
end
end
end
# Nested class
class Capybara::Selector::CSS::Splitter
def split(css) -> Array<String>
end
Import
require 'capybara/selector/css'
I/O Contract
CSS.escape
| Parameter |
Type |
Description
|
| str |
String |
The raw string to escape into a valid CSS identifier
|
| Returns |
Type |
Description
|
| escaped |
String |
A properly escaped CSS identifier string
|
CSS.escape_char
| Parameter |
Type |
Description
|
| char |
String |
A single character to escape
|
| Returns |
Type |
Description
|
| escaped |
String |
Backslash-escaped character for printable ASCII (e.g., \.), or zero-padded hex escape (e.g., \0000e9) for non-printable/Unicode characters
|
CSS.split / Splitter#split
| Parameter |
Type |
Description
|
| css |
String |
A comma-separated CSS selector list
|
| Returns |
Type |
Description
|
| selectors |
Array<String> |
An array of individual stripped CSS selectors
|
Errors
| Exception |
Condition
|
| ArgumentError |
Raised when a block end character (] or )) is not found during splitting
|
| ArgumentError |
Raised when a quoted string is not properly terminated
|
Usage Examples
Escaping a CSS Identifier
# Escape a string with special characters for use in a CSS selector
Capybara::Selector::CSS.escape("my.element#id")
# => "my\\.element\\#id"
Capybara::Selector::CSS.escape("name[brackets]")
# => "name\\[brackets\\]"
Splitting a Compound Selector
# Split a comma-separated selector list into individual selectors
Capybara::Selector::CSS.split("div.class, span#id, a[href='x,y']")
# => ["div.class", "span#id", "a[href='x,y']"]
# Commas inside brackets or quotes are preserved
Capybara::Selector::CSS.split("input[value='a,b'], .foo")
# => ["input[value='a,b']", ".foo"]
Escaping Individual Characters
Capybara::Selector::CSS.escape_char(".")
# => "\\."
Capybara::Selector::CSS.escape_char("\u00e9")
# => "\\0000e9"
Related Pages
