pdf-labels 1.0.0 → 1.0.1

Sign up to get free protection for your applications and to get access to all the features.
Files changed (60) hide show
  1. data/History.txt +3 -0
  2. data/Manifest.txt +41 -64
  3. data/README.txt +4 -3
  4. data/lib/pdf_labels.rb +1 -4
  5. data/test/test_pdf_label_page.rb +6 -6
  6. data/vendor/transaction/simple.rb +390 -597
  7. data/vendor/transaction/simple/group.rb +13 -0
  8. data/vendor/transaction/simple/threadsafe.rb +18 -2
  9. data/vendor/transaction/simple/threadsafe/group.rb +13 -0
  10. data/vendor/{xml-mapping → xml}/LICENSE +0 -0
  11. data/vendor/{xml-mapping → xml}/README +0 -0
  12. data/vendor/{xml-mapping/lib/xml → xml}/mapping.rb +0 -0
  13. data/vendor/{xml-mapping/lib/xml → xml}/mapping/base.rb +0 -0
  14. data/vendor/{xml-mapping/lib/xml → xml}/mapping/standard_nodes.rb +0 -0
  15. data/vendor/{xml-mapping/lib/xml → xml}/mapping/version.rb +0 -0
  16. data/vendor/{xml-mapping/lib/xml → xml}/xxpath.rb +0 -0
  17. metadata +46 -71
  18. data/vendor/xml-mapping/ChangeLog +0 -128
  19. data/vendor/xml-mapping/README_XPATH +0 -175
  20. data/vendor/xml-mapping/Rakefile +0 -214
  21. data/vendor/xml-mapping/TODO.txt +0 -32
  22. data/vendor/xml-mapping/doc/xpath_impl_notes.txt +0 -119
  23. data/vendor/xml-mapping/examples/company.rb +0 -34
  24. data/vendor/xml-mapping/examples/company.xml +0 -26
  25. data/vendor/xml-mapping/examples/company_usage.intin.rb +0 -19
  26. data/vendor/xml-mapping/examples/company_usage.intout +0 -39
  27. data/vendor/xml-mapping/examples/order.rb +0 -61
  28. data/vendor/xml-mapping/examples/order.xml +0 -54
  29. data/vendor/xml-mapping/examples/order_signature_enhanced.rb +0 -7
  30. data/vendor/xml-mapping/examples/order_signature_enhanced.xml +0 -9
  31. data/vendor/xml-mapping/examples/order_signature_enhanced_usage.intin.rb +0 -12
  32. data/vendor/xml-mapping/examples/order_signature_enhanced_usage.intout +0 -16
  33. data/vendor/xml-mapping/examples/order_usage.intin.rb +0 -73
  34. data/vendor/xml-mapping/examples/order_usage.intout +0 -147
  35. data/vendor/xml-mapping/examples/time_augm.intin.rb +0 -19
  36. data/vendor/xml-mapping/examples/time_augm.intout +0 -23
  37. data/vendor/xml-mapping/examples/time_node.rb +0 -27
  38. data/vendor/xml-mapping/examples/xpath_create_new.intin.rb +0 -85
  39. data/vendor/xml-mapping/examples/xpath_create_new.intout +0 -181
  40. data/vendor/xml-mapping/examples/xpath_docvsroot.intin.rb +0 -30
  41. data/vendor/xml-mapping/examples/xpath_docvsroot.intout +0 -34
  42. data/vendor/xml-mapping/examples/xpath_ensure_created.intin.rb +0 -62
  43. data/vendor/xml-mapping/examples/xpath_ensure_created.intout +0 -114
  44. data/vendor/xml-mapping/examples/xpath_pathological.intin.rb +0 -42
  45. data/vendor/xml-mapping/examples/xpath_pathological.intout +0 -56
  46. data/vendor/xml-mapping/examples/xpath_usage.intin.rb +0 -51
  47. data/vendor/xml-mapping/examples/xpath_usage.intout +0 -57
  48. data/vendor/xml-mapping/install.rb +0 -40
  49. data/vendor/xml-mapping/test/all_tests.rb +0 -6
  50. data/vendor/xml-mapping/test/company.rb +0 -56
  51. data/vendor/xml-mapping/test/documents_folders.rb +0 -33
  52. data/vendor/xml-mapping/test/fixtures/bookmarks1.xml +0 -24
  53. data/vendor/xml-mapping/test/fixtures/company1.xml +0 -85
  54. data/vendor/xml-mapping/test/fixtures/documents_folders.xml +0 -71
  55. data/vendor/xml-mapping/test/fixtures/documents_folders2.xml +0 -30
  56. data/vendor/xml-mapping/test/multiple_mappings.rb +0 -80
  57. data/vendor/xml-mapping/test/tests_init.rb +0 -2
  58. data/vendor/xml-mapping/test/xml_mapping_adv_test.rb +0 -84
  59. data/vendor/xml-mapping/test/xml_mapping_test.rb +0 -201
  60. data/vendor/xml-mapping/test/xpath_test.rb +0 -273
@@ -1,3 +1,16 @@
1
+ #--
2
+ # Transaction::Simple
3
+ # Simple object transaction support for Ruby
4
+ # http://rubyforge.org/projects/trans-simple/
5
+ # Version 1.4.0
6
+ #
7
+ # Licensed under a MIT-style licence. See Licence.txt in the main
8
+ # distribution for full licensing information.
9
+ #
10
+ # Copyright (c) 2003 - 2007 Austin Ziegler
11
+ #
12
+ # $Id: group.rb 47 2007-02-03 15:02:51Z austin $
13
+ #++
1
14
  require 'transaction/simple'
2
15
 
3
16
  # A transaction group is an object wrapper that manages a group of objects
@@ -1,7 +1,23 @@
1
+ #--
2
+ # Transaction::Simple
3
+ # Simple object transaction support for Ruby
4
+ # http://rubyforge.org/projects/trans-simple/
5
+ # Version 1.4.0
6
+ #
7
+ # Licensed under a MIT-style licence. See Licence.txt in the main
8
+ # distribution for full licensing information.
9
+ #
10
+ # Copyright (c) 2003 - 2007 Austin Ziegler
11
+ #
12
+ # $Id: threadsafe.rb 50 2007-02-03 20:26:19Z austin $
13
+ #++
1
14
  require 'transaction/simple'
2
15
  require 'thread'
3
16
 
4
- class Transaction::TransactionThreadError < StandardError
17
+ module Transaction
18
+ # A standard exception for transaction errors involving threadsafe
19
+ # transactions.
20
+ class TransactionThreadError < TransactionError; end
5
21
  end
6
22
 
7
23
  # = Transaction::Simple::ThreadSafe
@@ -14,7 +30,7 @@ end
14
30
  # lock cannot be obtained immediately, a
15
31
  # Transaction::TransactionThreadError will be raised.
16
32
  #
17
- # Thanks to Mauricio Fern�ndez for help with getting this part working.
33
+ # Thanks to Mauricio Fernandez for help with getting this part working.
18
34
  #
19
35
  # Threadsafe transactions can be used in any place that normal
20
36
  # transactions would. The main difference would be in setup:
@@ -1,3 +1,16 @@
1
+ #--
2
+ # Transaction::Simple
3
+ # Simple object transaction support for Ruby
4
+ # http://rubyforge.org/projects/trans-simple/
5
+ # Version 1.4.0
6
+ #
7
+ # Licensed under a MIT-style licence. See Licence.txt in the main
8
+ # distribution for full licensing information.
9
+ #
10
+ # Copyright (c) 2003 - 2007 Austin Ziegler
11
+ #
12
+ # $Id: group.rb 47 2007-02-03 15:02:51Z austin $
13
+ #++
1
14
  require 'transaction/simple/threadsafe'
2
15
 
3
16
  # A transaction group is an object wrapper that manages a group of objects
File without changes
File without changes
File without changes
File without changes
File without changes
metadata CHANGED
@@ -1,17 +1,17 @@
1
1
  --- !ruby/object:Gem::Specification
2
- rubygems_version: 0.9.2
2
+ rubygems_version: 0.9.4
3
3
  specification_version: 1
4
4
  name: pdf-labels
5
5
  version: !ruby/object:Gem::Version
6
- version: 1.0.0
7
- date: 2007-06-23 00:00:00 -07:00
6
+ version: 1.0.1
7
+ date: 2007-10-17 00:00:00 -07:00
8
8
  summary: Easy label creation in Ruby through PDF::Writer and using templates from gLabels. Contains the library pdf_labels, the Rails engine LabelPageEngine and an example application FileClerk.
9
9
  require_paths:
10
10
  - lib
11
11
  email: rgkaufman@gmail.com
12
- homepage: " by Rob Kaufman"
12
+ homepage:
13
13
  rubyforge_project: pdf-labels
14
- description: "== FEATURES/PROBLEMS: * Works with all gLabels supported templates for rectangular labels * Does not yet work for CD labels (circles) == SYNOPSIS: p = PDFLabelPage.new(\"Avery 8160\") # label is 2 x 10 #Some examples of adding labels p.add_label() # should add to col 1, row 1 p.add_label(:position => 1) # should add col 1, row 2 p.add_label(:text => \"Positoin 15\", :position => 15) # should add col 2, row 1 p.add_label(:text => 'No Margin', :position => 5, :use_margin => false) #this doesn't use a margin p.add_label(:position => 9, :text => \"X Offset = 4, Y Offset = -6\", :offset_x => 4, :offset_y => -6) p.add_label(:text => \"Centered\", :position => 26, :justification => :center) # should add col 2, row 15 p.add_label(:text => \"[Right justified]\", :justification => :right, :position => 28)# col 2, row 14, right justified. p.add_label(:position => 29) # should add col 2, row 15 p.add_label(:position => 8, :text => \"This was added last and has a BIG font\", :font_size => 18) #If you want to see the boxes around each label (good for printing alignment samples) p.draw_boxes(false, true)"
14
+ description: "== DESCRIPTION: Welcome to the PDF-Labels project. Our aim is to make creating labels programmatically easy in Ruby. This Library builds on top of \"PDF::Writer\":http://ruby-pdf.rubyforge.org/ and uses the templates from \"gLabels\":http://glabels.sourceforge.org. What this means is easy, clean Ruby code to create many common label types without measuring the labels yourself! All of this in pure Ruby (we use the XML templates from gLabels, we do NOT have a dependancy on gLabels, nor on Gnome) == FEATURES/PROBLEMS: * Works with all gLabels supported templates for rectangular labels * Does not yet work for CD labels (circles) == SYNOPSIS: p = PDFLabelPage.new(\"Avery 8160\") # label is 2 x 10 #Some examples of adding labels p.add_label() # should add to col 1, row 1 p.add_label(:position => 1) # should add col 1, row 2 p.add_label(:text => \"Positoin 15\", :position => 15) # should add col 2, row 1 p.add_label(:text => 'No Margin', :position => 5, :use_margin => false) #this doesn't use a margin p.add_label(:position => 9, :text => \"X Offset = 4, Y Offset = -6\", :offset_x => 4, :offset_y => -6) p.add_label(:text => \"Centered\", :position => 26, :justification => :center) # should add col 2, row 15 p.add_label(:text => \"[Right justified]\", :justification => :right, :position => 28)# col 2, row 14, right justified. p.add_label(:position => 29) # should add col 2, row 15 p.add_label(:position => 8, :text => \"This was added last and has a BIG font\", :font_size => 18)"
15
15
  autorequire:
16
16
  default_executable:
17
17
  bindir: bin
@@ -30,10 +30,7 @@ authors:
30
30
  - Rob Kaufman
31
31
  files:
32
32
  - History.txt
33
- - LICENCE
34
- - Manifest.txt
35
- - README.txt
36
- - Rakefile
33
+ - lib
37
34
  - lib/alias.rb
38
35
  - lib/glabel_template.rb
39
36
  - lib/label.rb
@@ -43,6 +40,11 @@ files:
43
40
  - lib/pdf_label_page.rb
44
41
  - lib/pdf_labels.rb
45
42
  - lib/template.rb
43
+ - LICENCE
44
+ - Manifest.txt
45
+ - Rakefile
46
+ - README.txt
47
+ - templates
46
48
  - templates/avery-iso-templates.xml
47
49
  - templates/avery-other-templates.xml
48
50
  - templates/avery-us-templates.xml
@@ -52,30 +54,39 @@ files:
52
54
  - templates/misc-us-templates.xml
53
55
  - templates/paper-sizes.xml
54
56
  - templates/zweckform-iso-templates.xml
57
+ - test
55
58
  - test/test_pdf_label_page.rb
56
- - vendor/color.rb
59
+ - vendor
60
+ - vendor/color
57
61
  - vendor/color/cmyk.rb
58
62
  - vendor/color/css.rb
59
63
  - vendor/color/grayscale.rb
60
64
  - vendor/color/hsl.rb
61
- - vendor/color/palette.rb
65
+ - vendor/color/palette
62
66
  - vendor/color/palette/gimp.rb
63
67
  - vendor/color/palette/monocontrast.rb
68
+ - vendor/color/palette.rb
69
+ - vendor/color/rgb
70
+ - vendor/color/rgb/metallic.rb
64
71
  - vendor/color/rgb-colors.rb
65
72
  - vendor/color/rgb.rb
66
- - vendor/color/rgb/metallic.rb
67
73
  - vendor/color/yiq.rb
68
- - vendor/pdf/charts.rb
74
+ - vendor/color.rb
75
+ - vendor/pdf
76
+ - vendor/pdf/charts
69
77
  - vendor/pdf/charts/stddev.rb
78
+ - vendor/pdf/charts.rb
79
+ - vendor/pdf/fonts
70
80
  - vendor/pdf/grid.rb
71
81
  - vendor/pdf/math.rb
72
82
  - vendor/pdf/pagenumbers.rb
73
83
  - vendor/pdf/quickref.rb
74
84
  - vendor/pdf/simpletable.rb
75
85
  - vendor/pdf/techbook.rb
76
- - vendor/pdf/writer.rb
86
+ - vendor/pdf/writer
77
87
  - vendor/pdf/writer/arc4.rb
78
88
  - vendor/pdf/writer/fontmetrics.rb
89
+ - vendor/pdf/writer/fonts
79
90
  - vendor/pdf/writer/fonts/Courier-Bold.afm
80
91
  - vendor/pdf/writer/fonts/Courier-BoldOblique.afm
81
92
  - vendor/pdf/writer/fonts/Courier-Oblique.afm
@@ -90,11 +101,13 @@ files:
90
101
  - vendor/pdf/writer/fonts/Times-Italic.afm
91
102
  - vendor/pdf/writer/fonts/Times-Roman.afm
92
103
  - vendor/pdf/writer/fonts/ZapfDingbats.afm
93
- - vendor/pdf/writer/graphics.rb
104
+ - vendor/pdf/writer/graphics
94
105
  - vendor/pdf/writer/graphics/imageinfo.rb
95
- - vendor/pdf/writer/lang.rb
106
+ - vendor/pdf/writer/graphics.rb
107
+ - vendor/pdf/writer/lang
96
108
  - vendor/pdf/writer/lang/en.rb
97
- - vendor/pdf/writer/object.rb
109
+ - vendor/pdf/writer/lang.rb
110
+ - vendor/pdf/writer/object
98
111
  - vendor/pdf/writer/object/action.rb
99
112
  - vendor/pdf/writer/object/annotation.rb
100
113
  - vendor/pdf/writer/object/catalog.rb
@@ -112,64 +125,28 @@ files:
112
125
  - vendor/pdf/writer/object/pages.rb
113
126
  - vendor/pdf/writer/object/procset.rb
114
127
  - vendor/pdf/writer/object/viewerpreferences.rb
128
+ - vendor/pdf/writer/object.rb
115
129
  - vendor/pdf/writer/ohash.rb
116
130
  - vendor/pdf/writer/oreader.rb
117
131
  - vendor/pdf/writer/state.rb
118
132
  - vendor/pdf/writer/strokestyle.rb
119
- - vendor/transaction/simple.rb
133
+ - vendor/pdf/writer.rb
134
+ - vendor/transaction
135
+ - vendor/transaction/simple
120
136
  - vendor/transaction/simple/group.rb
121
- - vendor/transaction/simple/threadsafe.rb
137
+ - vendor/transaction/simple/threadsafe
122
138
  - vendor/transaction/simple/threadsafe/group.rb
123
- - vendor/xml-mapping/ChangeLog
124
- - vendor/xml-mapping/LICENSE
125
- - vendor/xml-mapping/README
126
- - vendor/xml-mapping/README_XPATH
127
- - vendor/xml-mapping/Rakefile
128
- - vendor/xml-mapping/TODO.txt
129
- - vendor/xml-mapping/doc/xpath_impl_notes.txt
130
- - vendor/xml-mapping/examples/company.rb
131
- - vendor/xml-mapping/examples/company.xml
132
- - vendor/xml-mapping/examples/company_usage.intin.rb
133
- - vendor/xml-mapping/examples/company_usage.intout
134
- - vendor/xml-mapping/examples/order.rb
135
- - vendor/xml-mapping/examples/order.xml
136
- - vendor/xml-mapping/examples/order_signature_enhanced.rb
137
- - vendor/xml-mapping/examples/order_signature_enhanced.xml
138
- - vendor/xml-mapping/examples/order_signature_enhanced_usage.intin.rb
139
- - vendor/xml-mapping/examples/order_signature_enhanced_usage.intout
140
- - vendor/xml-mapping/examples/order_usage.intin.rb
141
- - vendor/xml-mapping/examples/order_usage.intout
142
- - vendor/xml-mapping/examples/time_augm.intin.rb
143
- - vendor/xml-mapping/examples/time_augm.intout
144
- - vendor/xml-mapping/examples/time_node.rb
145
- - vendor/xml-mapping/examples/xpath_create_new.intin.rb
146
- - vendor/xml-mapping/examples/xpath_create_new.intout
147
- - vendor/xml-mapping/examples/xpath_docvsroot.intin.rb
148
- - vendor/xml-mapping/examples/xpath_docvsroot.intout
149
- - vendor/xml-mapping/examples/xpath_ensure_created.intin.rb
150
- - vendor/xml-mapping/examples/xpath_ensure_created.intout
151
- - vendor/xml-mapping/examples/xpath_pathological.intin.rb
152
- - vendor/xml-mapping/examples/xpath_pathological.intout
153
- - vendor/xml-mapping/examples/xpath_usage.intin.rb
154
- - vendor/xml-mapping/examples/xpath_usage.intout
155
- - vendor/xml-mapping/install.rb
156
- - vendor/xml-mapping/lib/xml/mapping.rb
157
- - vendor/xml-mapping/lib/xml/mapping/base.rb
158
- - vendor/xml-mapping/lib/xml/mapping/standard_nodes.rb
159
- - vendor/xml-mapping/lib/xml/mapping/version.rb
160
- - vendor/xml-mapping/lib/xml/xxpath.rb
161
- - vendor/xml-mapping/test/all_tests.rb
162
- - vendor/xml-mapping/test/company.rb
163
- - vendor/xml-mapping/test/documents_folders.rb
164
- - vendor/xml-mapping/test/fixtures/bookmarks1.xml
165
- - vendor/xml-mapping/test/fixtures/company1.xml
166
- - vendor/xml-mapping/test/fixtures/documents_folders.xml
167
- - vendor/xml-mapping/test/fixtures/documents_folders2.xml
168
- - vendor/xml-mapping/test/multiple_mappings.rb
169
- - vendor/xml-mapping/test/tests_init.rb
170
- - vendor/xml-mapping/test/xml_mapping_adv_test.rb
171
- - vendor/xml-mapping/test/xml_mapping_test.rb
172
- - vendor/xml-mapping/test/xpath_test.rb
139
+ - vendor/transaction/simple/threadsafe.rb
140
+ - vendor/transaction/simple.rb
141
+ - vendor/xml
142
+ - vendor/xml/LICENSE
143
+ - vendor/xml/mapping
144
+ - vendor/xml/mapping/base.rb
145
+ - vendor/xml/mapping/standard_nodes.rb
146
+ - vendor/xml/mapping/version.rb
147
+ - vendor/xml/mapping.rb
148
+ - vendor/xml/xxpath.rb
149
+ - vendor/xml/README
173
150
  test_files:
174
151
  - test/test_pdf_label_page.rb
175
152
  rdoc_options:
@@ -179,8 +156,6 @@ extra_rdoc_files:
179
156
  - History.txt
180
157
  - Manifest.txt
181
158
  - README.txt
182
- - vendor/xml-mapping/TODO.txt
183
- - vendor/xml-mapping/doc/xpath_impl_notes.txt
184
159
  executables: []
185
160
 
186
161
  extensions: []
@@ -1,128 +0,0 @@
1
- 2005-12-07 Olaf Klischat
2
-
3
- * release 0.8.1
4
-
5
- 2005-12-07 Olaf Klischat
6
-
7
- * ChangeLog file
8
-
9
- 2005/11/30 Olaf Klischat
10
-
11
- * bugfix: clone default values to avoid external modifications
12
-
13
- 2005/07/07 Olaf Klischat
14
-
15
- * release 0.8
16
-
17
- 2005/07/04 Olaf Klischat
18
-
19
- * xml/xpath / XML::XPath -> xml/xxpath / XML::XXPath, license ->
20
- Ruby's
21
-
22
- 2005/06/29 Olaf Klischat
23
-
24
- * when creating elt[@attr='value'] path elements, add a new
25
- element if one with @attr='value' already existed
26
-
27
- 2005/03/30 Olaf Klischat
28
-
29
- * add_accessor: check for existing accessors.
30
-
31
- 2005/03/05 Olaf Klischat
32
-
33
- * better support for inheritance among mapping
34
- classes
35
-
36
- 2005/03/03 Olaf Klischat
37
-
38
- * "polymorphic" nodes via root element
39
- name. SubObjectBaseNode-based nodes es use node polymorphy when
40
- no explicit node marshaller/unmarshaller has been sp ecified.
41
-
42
- 2005/02/28 Olaf Klischat
43
-
44
- * mapping root elt name => mapping class;
45
- XML::Mapping::load_object_from_* implemented
46
-
47
- 2005/02/13 Olaf Klischat
48
-
49
- * IntNode renamed & generalized to NumericNode
50
-
51
- 2005/02/12 Olaf Klischat
52
-
53
- * renaming *_rexml => *_xml
54
-
55
- 2005/01/27 Olaf Klischat
56
-
57
- * special exception NoAttrValueSet for indicating absence of a
58
- specific attribute in an XML source
59
-
60
- 2005/01/23 Olaf Klischat
61
-
62
- * some more documentation, Node.obj_initializing, setting node
63
- values to defaults on initialization
64
-
65
- 2005/01/10 Olaf Klischat
66
-
67
- * root_element_name
68
-
69
- 2005/01/07 Olaf Klischat
70
-
71
- * refactoring:
72
-
73
- Made node types (classes) dynamically addable via
74
- XML::Mapping.add_node_class, xml/mapping.rb moved to
75
- xml/mapping/base.rb, node types moved to
76
- xml/mapping/standard_nodes.rb, xml/mapping.rb now requires base
77
- and standard_nodes and adds all standard node types to
78
- XML::Mapping.
79
-
80
- * additional node class SingleAttributeNode < Node for nodes that
81
- map to a single attribute in their class (that's true for all
82
- nodes we have so far). Call to add_attribute moved from "core"
83
- to SingleAttributeNode.initialize.
84
-
85
- * XML::Mapping: @nodes renamed to @xml_mapping_nodes to minimize
86
- chance of name clashes.
87
-
88
- 2004/12/30 Olaf Klischat
89
-
90
- * array node writing, hash node writing
91
-
92
-
93
- 2004/12/30 Olaf Klischat
94
-
95
- * xpath: create_new flag, + convenience method
96
-
97
- 2004/12/21 Olaf Klischat
98
-
99
- * node classes
100
-
101
- 2004/12/20 Olaf Klischat
102
-
103
- * hash_node
104
-
105
- 2004/12/08 Olaf Klischat
106
-
107
- * xpath: attribute nodes
108
-
109
- * xml_mapping: retargeted from REXML::XPath to XML::XPath
110
-
111
- 2004/12/02 Olaf Klischat
112
-
113
- * xpath: write accessors
114
-
115
- 2004/11/27 Olaf Klischat
116
-
117
- * xpath: read access seems to work
118
-
119
- 2004/11/25 Olaf Klischat
120
-
121
- * array_node
122
-
123
- stone age Olaf Klischat
124
-
125
- * see http://rubygarden.org/ruby?XmlMapping
126
-
127
-
128
-
@@ -1,175 +0,0 @@
1
- = XML-XXPATH
2
-
3
- == Overview, Motivation
4
-
5
- Xml-xxpath is an (incomplete) XPath interpreter that is at the moment
6
- bundled with xml-mapping. It is built on top of REXML. xml-mapping
7
- uses xml-xxpath extensively for implementing its node types -- see the
8
- README file and the reference documentation (and the source code) for
9
- details. xml-xxpath, however, does not depend on xml-mapping at all,
10
- and is useful in its own right -- maybe I'll later distribute it as a
11
- seperate library instead of bundling it. xml-xxpath's XPath support is
12
- vastly incomplete (see below), but, in addition to the normal
13
- reading/matching functionality found in other XPath implementations
14
- (i.e. "find all elements in a given XML document matching a given
15
- XPath expression"), xml-xxpath supports <i>write access</i>. For
16
- example, when writing the XPath expression
17
- "/foo/bar[3]/baz[@key='hiho']" to the XML document
18
-
19
- <foo>
20
- <bar>
21
- <baz key='ab'>hello</baz>
22
- <baz key='xy'>goodbye</baz>
23
- </bar>
24
- </foo>
25
-
26
- , you'll get:
27
-
28
- <foo>
29
- <bar>
30
- <baz key='ab'>hello</baz>
31
- <baz key='xy'>goodbye</baz>
32
- </bar>
33
- <bar/>
34
- <bar><baz key='hiho'/></bar>
35
- </foo>
36
-
37
- This feature is used by xml-mapping when writing (marshalling) Ruby
38
- objects to XML, and is actually the reason why I couldn't just use any
39
- of the existing XPath implementations, e.g. the one that comes with
40
- REXML. Also, the whole xml-xxpath implementation is just 300 lines of
41
- Ruby code, it is quite fast (paths are precompiled), and xml-xxpath
42
- returns matched elements in the order they appeared in the source
43
- document -- I've heard REXML::XXPath doesn't do that :)
44
-
45
- Some basic knowledge of XPath is helpful for reading this document (I
46
- don't know very much either).
47
-
48
- At the moment, xml-xxpath understands XPath expressions of the form
49
- [<tt>/</tt>]_pathelement_<tt>/</tt>_pathelement_<tt>/</tt>..., where
50
- each _pathelement_ must be one of these:
51
-
52
- - a simple element name _name_, e.g. +signature+
53
-
54
- - an attribute name, @_attr_name_, e.g. <tt>@key</tt>
55
-
56
- - a combination of an element name and an attribute name and
57
- -value, in the form _elt_name_[@_attr_name_='_attr_value_']
58
-
59
- - an element name and an index, _elt_name_[_index_]
60
-
61
- - the "match-all" path element, <tt>*</tt>
62
-
63
-
64
- == Usage
65
-
66
- Xml-xxpath defines the class XML::XXPath. An instance of that class
67
- wraps an XPath expression, the string representation of which must be
68
- supplied when constructing the instance. You then call instance
69
- methods like _first_, _all_ or <i>create_new</i> on the instance,
70
- supplying the REXML Element the XPath expression should be applied to,
71
- and get the results, or, in the case of write access, the element is
72
- updated in-place.
73
-
74
-
75
- === Read Access
76
-
77
- :include: xpath_usage.intout
78
-
79
- The objects supplied to the <tt>all()</tt>, <tt>first()</tt>, and
80
- <tt>each()</tt> calls must be REXML element nodes, i.e. they must
81
- support messages like <tt>elements</tt>, <tt>attributes</tt> etc
82
- (instances of REXML::Element and its subclasses do this). The calls
83
- return the found elements as instances of REXML::Element or
84
- XML::XXPath::Accessors::Attribute. The latter is a wrapper around
85
- attribute nodes that is largely call-compatible to
86
- REXML::Element. This is so you can write things like
87
- <tt>path.each{|node|puts node.text}</tt> without having to
88
- special-case anything even if the path matches attributes, not just
89
- elements.
90
-
91
- As you can see, you can re-use path objects, applying them to
92
- different XML elements at will. You should do this because the XPath
93
- pattern is stored inside the XPath object in a pre-compiled form,
94
- which makes it more efficient.
95
-
96
- The path elements of the XPath pattern are applied to the
97
- <tt>.elements</tt> collection of the passed XML element and its
98
- sub-elements, starting with the first one. This is shown by the
99
- following code:
100
-
101
- :include: xpath_docvsroot.intout
102
-
103
- A REXML +Document+ object is a REXML +Element+ object whose +elements+
104
- collection consists only of a single member -- the document's root
105
- node. The first path element of the XPath -- "foo" in the example --
106
- is matched against that. That is why the path "/bar" in the example
107
- doesn't match anything when matched against the document +d+ itself.
108
-
109
- An ordinary REXML +Element+ object that represents a node somewhere
110
- inside an XML tree has an +elements+ collection that consists of all
111
- the element's direct sub-elements. That is why XPath patterns matched
112
- against the +firstelt+ element in the example *must not* start with
113
- "/first" (unless there is a child node that is also named "first").
114
-
115
-
116
- === Write Access
117
-
118
- You may pass a <tt>:ensure_created=>true</tt> option argument to
119
- _path_.first(_elt_)/_path_.all(_elt_) calls to make sure that _path_
120
- exists inside the passed XML element _elt_. If it existed before,
121
- nothing changes, and the call behaves just as it would without the
122
- option argument. If the path didn't exist before, the XML element is
123
- modified such that
124
-
125
- - the path exists afterwards
126
-
127
- - all paths that existed before still exist afterwards
128
-
129
- - the modification is as small as possible (i.e. as few elements as
130
- possible are added, additional attributes are added to existing
131
- elements if possible etc.)
132
-
133
- The created resp. previously existing, matching elements are returned.
134
-
135
-
136
- Examples:
137
-
138
- :include: xpath_ensure_created.intout
139
-
140
-
141
- Alternatively, you may pass a <tt>:create_new=>true</tt> option
142
- argument or call <tt>create_new</tt> (_path_.create_new(_elt_) is
143
- equivalent to _path_.first(_elt_,:create_new=>true)). In that case, a
144
- new node in created in _elt_ for each path element of _path_ (or an
145
- exception raised if that wasn't possible for any path element).
146
-
147
- Examples:
148
-
149
- :include: xpath_create_new.intout
150
-
151
-
152
- === Pathological Cases
153
-
154
- What is created when the Path "*" is to be created inside an empty XML
155
- element? The name of the element to be created isn't known, but still
156
- some element must be created. The answer is that xml-xxpath creates a
157
- special "unspecified" element whose name must be set by the caller
158
- afterwards:
159
-
160
- :include: xpath_pathological.intout
161
-
162
- The "newelt" object in the last example is an ordinary
163
- REXML::Element. xml-xxpath mixes the "unspecified" attribute into that
164
- class, as well as into the XML::XXPath::Accessors::Attribute class
165
- mentioned above.
166
-
167
-
168
- == Implentation notes
169
-
170
- <tt>doc/xpath_impl_notes.txt</tt> contains some documentation on the
171
- implementation of xml-xxpath.
172
-
173
- == License
174
-
175
- Ruby's.