Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 137 lines (98 sloc) 4.06 kb
c2f8f66 @jnicklas Convert README to markdown
authored
1 # XPath
a3a4139 @jnicklas Added some basic info to README
authored
2
f375d1d @jnicklas Horrible type, omg
authored
3 XPath is a Ruby DSL around a subset of XPath 1.0. Its primary purpose is to
6f77690 Added License to README
Your Name authored
4 facilitate writing complex XPath queries from Ruby code.
a3a4139 @jnicklas Added some basic info to README
authored
5
c2f8f66 @jnicklas Convert README to markdown
authored
6 [![Build Status](https://secure.travis-ci.org/jnicklas/xpath.png?branch=master)](http://travis-ci.org/jnicklas/xpath)
c6a7c6a @jnicklas added travis status button
authored
7
c2f8f66 @jnicklas Convert README to markdown
authored
8 ## Generating expressions
a3a4139 @jnicklas Added some basic info to README
authored
9
c2f8f66 @jnicklas Convert README to markdown
authored
10 To create quick, one-off expressions, `XPath.generate` can be used:
a3a4139 @jnicklas Added some basic info to README
authored
11
c2f8f66 @jnicklas Convert README to markdown
authored
12 ``` ruby
13 XPath.generate { |x| x.descendant(:ul)[x.attr(:id) == 'foo'] }
14 ```
a3a4139 @jnicklas Added some basic info to README
authored
15
c2f8f66 @jnicklas Convert README to markdown
authored
16 You can also call expression methods directly on the `XPath` module:
934b371 @jnicklas Added more documentation to README
authored
17
c2f8f66 @jnicklas Convert README to markdown
authored
18 ``` ruby
e9590ca @jnicklas Fix unbalanced bracket, closes #45
authored
19 XPath.descendant(:ul)[XPath.attr(:id) == 'foo']
c2f8f66 @jnicklas Convert README to markdown
authored
20 ```
934b371 @jnicklas Added more documentation to README
authored
21
1c0245b @jnicklas typo
authored
22 However for more complex expressions, it is probably more convenient to include
c2f8f66 @jnicklas Convert README to markdown
authored
23 the `XPath` module into your own class or module:
a3a4139 @jnicklas Added some basic info to README
authored
24
c2f8f66 @jnicklas Convert README to markdown
authored
25 ``` ruby
26 module MyXPaths
27 include XPath
a3a4139 @jnicklas Added some basic info to README
authored
28
c2f8f66 @jnicklas Convert README to markdown
authored
29 def foo_ul
30 descendant(:ul)[attr(:id) == 'foo']
31 end
a3a4139 @jnicklas Added some basic info to README
authored
32
c2f8f66 @jnicklas Convert README to markdown
authored
33 def password_field(id)
34 descendant(:input)[attr(:type) == 'password'][attr(:id) == id]
35 end
36 end
37 ```
a3a4139 @jnicklas Added some basic info to README
authored
38
c2f8f66 @jnicklas Convert README to markdown
authored
39 Both ways return an
40 [`XPath::Expression`](http://rdoc.info/github/jnicklas/xpath/XPath/Expression)
41 instance, which can be further modified. To convert the expression to a
42 string, just call `#to_s` on it. All available expressions are defined in
43 [`XPath::DSL`](http://rdoc.info/github/jnicklas/xpath/XPath/DSL).
934b371 @jnicklas Added more documentation to README
authored
44
c2f8f66 @jnicklas Convert README to markdown
authored
45 ## String, Hashes and Symbols
934b371 @jnicklas Added more documentation to README
authored
46
47 When you send a string as an argument to any XPath function, XPath assumes this
48 to be a string literal. On the other hand if you send in Symbol, XPath assumes
49 this to be an XPath literal. Thus the following two statements are not
50 equivalent:
51
c2f8f66 @jnicklas Convert README to markdown
authored
52 ``` ruby
53 XPath.descendant(:p)[XPath.attr(:id) == 'foo']
54 XPath.descendant(:p)[XPath.attr(:id) == :foo]
55 ```
934b371 @jnicklas Added more documentation to README
authored
56
57 These are the XPath expressions that these would be translated to:
58
c2f8f66 @jnicklas Convert README to markdown
authored
59 ```
60 .//p[@id = 'foo']
61 .//p[@id = foo]
62 ```
934b371 @jnicklas Added more documentation to README
authored
63
64 The second expression would match any p tag whose id attribute matches a 'foo'
65 tag it contains. Most likely this is not what you want.
66
67 In fact anything other than a String is treated as a literal. Thus the
68 following works as expected:
69
c2f8f66 @jnicklas Convert README to markdown
authored
70 ``` ruby
71 XPath.descendant(:p)[1]
72 ```
934b371 @jnicklas Added more documentation to README
authored
73
74 Keep in mind that XPath is 1-indexed and not 0-indexed like most other
75 programming languages, including Ruby.
76
77 Hashes are automatically converted to equality expressions, so the above
78 example could be written as:
79
c2f8f66 @jnicklas Convert README to markdown
authored
80 ``` ruby
81 XPath.descendant(:p)[:@id => 'foo']
82 ```
934b371 @jnicklas Added more documentation to README
authored
83
84 Which would generate the same expression:
85
c2f8f66 @jnicklas Convert README to markdown
authored
86 ```
87 .//p[@id = 'foo']
88 ```
934b371 @jnicklas Added more documentation to README
authored
89
90 Note that the same rules apply here, both the keys and values in the hash are
91 treated the same way as any other expression in XPath. Thus the following are
92 not equivalent:
93
c2f8f66 @jnicklas Convert README to markdown
authored
94 ``` ruby
95 XPath.descendant(:p)[:@id => 'foo'] # => .//p[@id = 'foo']
96 XPath.descendant(:p)[:id => 'foo'] # => .//p[id = 'foo']
97 XPath.descendant(:p)['id' => 'foo'] # => .//p['id' = 'foo']
98 ```
a3a4139 @jnicklas Added some basic info to README
authored
99
c2f8f66 @jnicklas Convert README to markdown
authored
100 ## HTML
a3a4139 @jnicklas Added some basic info to README
authored
101
102 XPath comes with a set of premade XPaths for use with HTML documents.
6f77690 Added License to README
Your Name authored
103
934b371 @jnicklas Added more documentation to README
authored
104 You can generate these like this:
105
c2f8f66 @jnicklas Convert README to markdown
authored
106 ``` ruby
107 XPath::HTML.link('Home')
108 XPath::HTML.field('Name')
109 ```
934b371 @jnicklas Added more documentation to README
authored
110
c2f8f66 @jnicklas Convert README to markdown
authored
111 See [`XPath::HTML`](http://rdoc.info/github/jnicklas/xpath/XPath/HTML) for all
112 available matchers.
934b371 @jnicklas Added more documentation to README
authored
113
c2f8f66 @jnicklas Convert README to markdown
authored
114 ## License
6f77690 Added License to README
Your Name authored
115
116 (The MIT License)
117
118 Copyright © 2010 Jonas Nicklas
119
120 Permission is hereby granted, free of charge, to any person obtaining a copy of
121 this software and associated documentation files (the ‘Software’), to deal in
122 the Software without restriction, including without limitation the rights to
123 use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
124 of the Software, and to permit persons to whom the Software is furnished to do
125 so, subject to the following conditions:
126
127 The above copyright notice and this permission notice shall be included in all
128 copies or substantial portions of the Software.
129
130 THE SOFTWARE IS PROVIDED ‘AS IS’, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
131 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
132 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
133 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
134 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
135 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
136 SOFTWARE.
Something went wrong with that request. Please try again.