objective_elements 0.2.0 → 0.3.0

Sign up to get free protection for your applications and to get access to all the features.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: e11c40fa73e065603e77081aef6c8df5e0a097a2ac47e0a5c2a69b04633aebbb
4
- data.tar.gz: 7d9568d439b669be90cd8158d1078d339c0215720fee13c6a5e10561516881c9
3
+ metadata.gz: 57bc0f1dbe710d5d20390881d1eb5fdedf7fbb09efc74f445905ddc3428158e2
4
+ data.tar.gz: 83f0691aad60a3f0c24d1faf270938449ddd8d2af90e2ebbc508bb32e18447ed
5
5
  SHA512:
6
- metadata.gz: ead034c3e4fb8ba2c72b5417386163467c856c7bd43aa3367fad91c22b63f1332c358e6b806bf3b48742c7a11d9bdd65f35de9751375efb9e655d682bd3872b4
7
- data.tar.gz: 9c6f3afc6646ea72608a30034ca6f87de8f2590ffac58b6b83c68a3c154cc6c00d06de8bcd82d68159a0078267860b1b7f17728f59c0b4eb01a40885774b2f12
6
+ metadata.gz: 5e3a65c6eaa857398f5318f45fc37e871c4507830e40aa339cf2e00bd79a9d6979c3c350f7be92f096f21d5c2ef297853b7efd005b252522e5aaa562fe4f743e
7
+ data.tar.gz: 8e9d6e50e800803981430f7aaafe7914850024a79a90452aed6f6fe5f3ed45e5f617062d85b2a2f22094469af197ab2e3568a2292b99affeb3b34474b3401d97
data/README.md CHANGED
@@ -3,13 +3,18 @@
3
3
  This is a tiny gem that builds nicely formatted HTML using sane, readable Ruby. I use it for jekyll
4
4
  plugins, but you can use it anywhere. It's ~100 lines, tested with rspec, and has no dependencies.
5
5
 
6
- This gem doesn't actually know any HTML. It just knows how to format it.
6
+ It doesn't actually know any HTML, just how to format it.
7
+
8
+ This is meant to be less involved and more flexible than nokogiri's XML/HTML generator. There's no
9
+ DSL to learn, and no cleverness to wrap your mind around. Its specialty is taking fragmented,
10
+ disjointed information and condensing it into a string of properly formatted HTML. It's as agnostic
11
+ as possible on the input, while being extremely consistent with its output.
7
12
 
8
13
  ## How it works:
9
14
 
10
15
  * Instantiate a `SingleTag` or `DoubleTag`
11
16
 
12
- * Add attributes & content in one of a few ways. Nest tags infinitely.
17
+ * Add attributes & content. Nest tags infinitely.
13
18
 
14
19
  * Render it with `.to_s`
15
20
 
@@ -21,14 +26,15 @@ you only need sometimes, it turns into a horrible mess.
21
26
 
22
27
  The problem, of course, is that building long, complex, varying blocks of text with string
23
28
  concatenation and interpolation is fragile, unreadable, and painful. You know this, but you're not
24
- going to write an entirely new class or pull in some big new dependency just for 10 lines of HTML.
25
- Instead, you hammer through it and end up with code like this:
29
+ going to write an entirely new class or pull in some big new dependency just for 10 lines of HTML,
30
+ so instead you hammer through it and end up with code like this:
26
31
 
27
32
  ```ruby
28
33
  picture_tag = "<picture>\n"\
29
- "#{source_tags}"\
30
- "#{markdown_escape * 4}<img src=\"#{url}#{instance['source_default'][:generated_src]}\" #{html_attr_string}>\n"\
31
- "#{markdown_escape * 2}</picture>\n"
34
+ "#{source_tags}"\
35
+ "#{markdown_escape * 4}"\
36
+ "<img src=\"#{url}#{instance['source_default'][:generated_src]}\" "\
37
+ "#{html_attr_string}>\n"\"#{markdown_escape * 2}</picture>\n"
32
38
  ```
33
39
 
34
40
  or this:
@@ -56,11 +62,15 @@ p.to_s
56
62
  # <p>
57
63
  # </p>
58
64
 
59
- # Add attributes as a hash, values can be strings or symbols:
65
+ # Add attributes as a hash. keys can be strings or symbols, values can be arrays or strings:
60
66
  p.add_attributes class: 'stumpy grumpy', 'id' => 'the-ugly-one'
61
- # Add them as a string!
67
+
68
+ # Add attributes as a string!
62
69
  p.add_attributes 'class="slimy" data-awesomeness="11"'
70
+
71
+ # Add content. It can be anything, or an array of anythings.
63
72
  p.add_content "Icky"
73
+
64
74
  p.to_s
65
75
  # <p class="stumpy grumpy slimy" id="the-ugly-one" data-awesomeness="11">
66
76
  # Icky
@@ -69,21 +79,22 @@ p.to_s
69
79
  # Want a oneliner?
70
80
  p.oneline = true
71
81
  p.to_s
72
- # <p class="stumpy mopey grumpy slimy" id="the-ugly-one" data-awesomeness="11">Icky</p>
82
+ # <p class="stumpy grumpy slimy" id="the-ugly-one" data-awesomeness="11">Icky</p>
73
83
  p.oneline = false
74
84
 
75
- # Build it up step by step, or all at once:
85
+ # Build a tag all at once:
76
86
  p.add_content DoubleTag.new(
77
87
  'a',
78
88
  content: 'Link!',
79
89
  attributes: {href: 'awesome-possum.com'},
80
90
  oneline: true
81
91
  )
82
- # Add a parent tag!
92
+
93
+ # Add a parent tag:
83
94
  div = p.add_parent DoubleTag.new 'div'
84
95
 
85
96
  # Ruby implicitly calls .to_s on things when you try to perform string functions with them, so
86
- # things like this work:
97
+ # this works:
87
98
  "#{div}"
88
99
  # <div>
89
100
  # <p class="stumpy mopey grumpy slimy" id="the-ugly-one" data-awesomeness="11">
@@ -93,6 +104,11 @@ div = p.add_parent DoubleTag.new 'div'
93
104
  # </div>
94
105
 
95
106
  ```
107
+
108
+ For complete example usage, see [jekyll_icon_list](https://github.com/rbuchberger/jekyll_icon_list), or
109
+ this [pull request](https://github.com/robwierzbowski/jekyll-picture-tag/pull/87/commits/d6b2deca0f19f173251a2984037e5e5f8d7c21d1)
110
+ to [jekyll-picture-tag](https://github.com/robwierzbowski/jekyll-picture-tag).
111
+
96
112
  ## Installation
97
113
 
98
114
  ```ruby
@@ -119,24 +135,24 @@ So we're on the same page, here's the terminology I'm using:
119
135
  - c - content
120
136
  - d - closing tag
121
137
 
138
+
139
+ ## Usage
140
+
122
141
  There are 2 classes: `SingleTag` is the base class, and `DoubleTag` inherits from it. A `SingleTag`
123
142
  is a self-closing tag, meaning it has no content and no closing tag. A `DoubleTag` is the other
124
143
  kind.
125
144
 
126
- ## Usage
127
-
128
145
  ### SingleTag Properties:
129
146
 
130
147
  #### element
131
148
  - String
132
149
  - Mandatory
133
150
  - Which type of tag it is, such as 'hr' or 'img'
134
- - Defined on initialization, cannot be changed afterwards. (Should it be? I'm on the fence about it.)
135
151
 
136
152
  #### attributes
137
153
  - Hash
138
154
  - Optional
139
- - Keys are symbols, values are arrays of strings. `{class: ['stumpy', 'slimy']}`
155
+ - Keys are stored as symbols, values are stored as arrays of strings: `{class: ['stumpy', 'slimy']}`
140
156
  - add them with `.add_attributes`, which can accept a few different formats.
141
157
 
142
158
  ### SingleTag Methods (that you care about)
@@ -145,20 +161,29 @@ kind.
145
161
 
146
162
  `.to_s` - The big one. Returns your HTML as a string, nondestructively.
147
163
 
164
+ `.add_attributes(new)` - The strongly recommended way to add new attributes. Can accept a hash (keys
165
+ can be either symbols or strings, values can be either arrays or strings), or a string in the
166
+ standard HTML syntax (`attribute="value" attribute2="value2 value3"`). Returns self.
167
+
148
168
  `.reset_attributes(new)` - Deletes all attributes, calls add_attributes on supplied argument if
149
169
  given.
150
170
 
151
- `.add_attributes(new)` - The only way we add new attributes. Can accept a hash (keys can be either
152
- symbols or strings), or a string in the standard HTML syntax (`attribute="value" attribute2="value2
153
- value3"`). Returns self.
171
+ `.delete_attributes(keys)` - Accepts a single attribute, or an array of attributes (keys or
172
+ strings), and deletes it.
173
+
174
+ `.rewrite_attributes` - Accepts anything add_attributes understands, but replaces existing
175
+ attributes instead of appending to them.
154
176
 
155
177
  `.add_parent(DoubleTag)` - returns supplied DoubleTag, with self added as a child.
156
178
 
157
- `attr_reader :attributes, :element`
179
+
180
+
181
+ `attr_reader :attributes`
182
+ `attr_accessor :element`
158
183
 
159
184
  ### DoubleTag Properties:
160
185
 
161
- #### `DoubleTag` Inherits all of `SingleTag`'s properties and methods, but adds content and a closing tag.
186
+ #### `DoubleTag` Inherits all of `SingleTag`'s properties and methods, and adds content and a closing tag.
162
187
 
163
188
  #### content
164
189
 
@@ -184,7 +209,9 @@ value3"`). Returns self.
184
209
  content.
185
210
 
186
211
  `add_content(anything)` - Smart enough to handle both arrays and not-arrays without getting dorked
187
- up.
212
+ up. When given an array, its elements will be appended to the content array. When given a single
213
+ item, that item will be inserted at the end of the array. (Remember each element in the content
214
+ array gets at least one line!)
188
215
 
189
216
  `attr_accessor: content` - You can modify the content array directly if you like. If you're just
190
217
  adding items, you should use `.add_content`
@@ -194,8 +221,8 @@ appropriate indentation applied, this is how you can get it.
194
221
 
195
222
  ## Configuration
196
223
 
197
- Indentation is defined by the `indent` method on the DoubleTag class. If you'd like to change
198
- it:
224
+ Indentation is defined by the `indent` method on the DoubleTag class, which is two markdown-escaped
225
+ spaces by default ("\ \ "). If you'd like to change it:
199
226
 
200
227
  1. Make a new class, inherit from DoubleTag.
201
228
  2. Override `indent` with whatever you want.
@@ -223,11 +250,10 @@ MyDoubleTag.new('p', content: 'hello').to_s
223
250
 
224
251
  ## Limitations
225
252
 
226
- * It doesn't know a single HTML element on its own, so it does nothing to ensure your
227
- HTML is valid. Garbage in, garbage out.
253
+ * It doesn't know a single HTML element on its own, so it does nothing to ensure your HTML is valid.
228
254
 
229
- * A parent tag can't put siblings on the same line. You can either
230
- do this (with `oneline: true` on the strong tag):
255
+ * A parent tag can't put siblings on the same line. You can either do this (with `oneline: true` on
256
+ the strong tag):
231
257
 
232
258
  ```html
233
259
 
@@ -247,7 +273,7 @@ MyDoubleTag.new('p', content: 'hello').to_s
247
273
  text.
248
274
 
249
275
  ```
250
- But you can't do this without string interpolation:
276
+ But you can't do this without string interpolation or something:
251
277
 
252
278
  ```html
253
279
 
@@ -258,7 +284,7 @@ MyDoubleTag.new('p', content: 'hello').to_s
258
284
  source code layout.
259
285
 
260
286
  * If you set 'oneline: true' on a parent DoubleTag, but not all its children DoubleTags, the output
261
- will not be pretty. I advise against it.
287
+ will not be pretty. I advise against it. Handling this situation is on the TODO list.
262
288
 
263
289
  * It doesn't wrap long lines of text, and it doesn't indent text with newlines embedded. It's on the
264
290
  TODO list.
@@ -18,6 +18,8 @@ class SingleTag
18
18
  def reset_attributes(new = nil)
19
19
  @attributes = {}
20
20
  add_attributes(new) if new
21
+
22
+ self
21
23
  end
22
24
 
23
25
  # This is the only way we add new attributes. Flexible about what you give
@@ -30,8 +32,36 @@ class SingleTag
30
32
  else
31
33
  add_hash_attributes(new)
32
34
  end
35
+
36
+ self
37
+ end
38
+ alias add_attribute add_attributes
39
+
40
+ def delete_attributes(keys)
41
+ # accepts an array or a single element
42
+ to_delete = if keys.is_a? Array
43
+ keys.map(&:to_sym)
44
+ else
45
+ [keys.to_sym]
46
+ end
47
+
48
+ to_delete.each { |k| @attributes.delete k }
49
+
50
+ self
51
+ end
52
+ alias delete_attribute delete_attributes
53
+
54
+ def rewrite_attribute(new)
55
+ formatted_new = if new.is_a? String
56
+ hashify_attributes(new)
57
+ else
58
+ new.transform_keys(&:to_sym)
59
+ end
60
+
61
+ delete_attributes formatted_new.keys
62
+
63
+ add_hash_attributes formatted_new
33
64
  end
34
- alias_method :add_attribute, :add_attributes
35
65
 
36
66
  # Turns attributes into a string we can insert.
37
67
  def render_attributes
@@ -64,16 +94,19 @@ class SingleTag
64
94
 
65
95
  private
66
96
 
67
- def add_string_attributes(new)
97
+ def add_string_attributes(new_string)
98
+ add_hash_attributes hashify_attributes new_string
99
+ end
100
+
101
+ def hashify_attributes(new_string)
68
102
  # looking for something like:
69
103
  # 'class="something something-else" id="my-id"'
70
104
  new_hash = {}
71
- new.scan(/ ?([^="]+)="([^"]+)"/).each do |m|
105
+ new_string.scan(/ ?([^="]+)="([^"]+)"/).each do |m|
72
106
  # [['class','something something-else'],['id','my-id']]
73
107
  new_hash[m.shift] = m.pop
74
108
  end
75
-
76
- add_hash_attributes(new_hash)
109
+ new_hash
77
110
  end
78
111
 
79
112
  def add_hash_attributes(new)
@@ -88,5 +121,4 @@ class SingleTag
88
121
  end
89
122
  self
90
123
  end
91
-
92
124
  end
@@ -1,3 +1,3 @@
1
1
  module ObjectiveElements
2
- VERSION = "0.2.0"
2
+ VERSION = '0.3.0'.freeze
3
3
  end
metadata CHANGED
@@ -1,14 +1,14 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: objective_elements
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.2.0
4
+ version: 0.3.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - Robert Buchberger
8
8
  autorequire:
9
9
  bindir: exe
10
10
  cert_chain: []
11
- date: 2018-10-02 00:00:00.000000000 Z
11
+ date: 2018-10-12 00:00:00.000000000 Z
12
12
  dependencies:
13
13
  - !ruby/object:Gem::Dependency
14
14
  name: bundler