objective_elements 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e11c40fa73e065603e77081aef6c8df5e0a097a2ac47e0a5c2a69b04633aebbb
-  data.tar.gz: 7d9568d439b669be90cd8158d1078d339c0215720fee13c6a5e10561516881c9
+  metadata.gz: 57bc0f1dbe710d5d20390881d1eb5fdedf7fbb09efc74f445905ddc3428158e2
+  data.tar.gz: 83f0691aad60a3f0c24d1faf270938449ddd8d2af90e2ebbc508bb32e18447ed
 SHA512:
-  metadata.gz: ead034c3e4fb8ba2c72b5417386163467c856c7bd43aa3367fad91c22b63f1332c358e6b806bf3b48742c7a11d9bdd65f35de9751375efb9e655d682bd3872b4
-  data.tar.gz: 9c6f3afc6646ea72608a30034ca6f87de8f2590ffac58b6b83c68a3c154cc6c00d06de8bcd82d68159a0078267860b1b7f17728f59c0b4eb01a40885774b2f12
+  metadata.gz: 5e3a65c6eaa857398f5318f45fc37e871c4507830e40aa339cf2e00bd79a9d6979c3c350f7be92f096f21d5c2ef297853b7efd005b252522e5aaa562fe4f743e
+  data.tar.gz: 8e9d6e50e800803981430f7aaafe7914850024a79a90452aed6f6fe5f3ed45e5f617062d85b2a2f22094469af197ab2e3568a2292b99affeb3b34474b3401d97

data/README.md

@@ -3,13 +3,18 @@
 This is a tiny gem that builds nicely formatted HTML using sane, readable Ruby. I use it for jekyll
 plugins, but you can use it anywhere. It's ~100 lines, tested with rspec, and has no dependencies.
 
-This gem doesn't actually know any HTML. It just knows how to format it.
+It doesn't actually know any HTML, just how to format it.
+
+This is meant to be less involved and more flexible than nokogiri's XML/HTML generator. There's no
+DSL to learn, and no cleverness to wrap your mind around. Its specialty is taking fragmented,
+disjointed information and condensing it into a string of properly formatted HTML. It's as agnostic
+as possible on the input, while being extremely consistent with its output.
 
 ## How it works:
 
 * Instantiate a `SingleTag` or `DoubleTag`
 
-* Add attributes & content in one of a few ways. Nest tags infinitely.
+* Add attributes & content. Nest tags infinitely.
 
 * Render it with `.to_s`
 
@@ -21,14 +26,15 @@ you only need sometimes, it turns into a horrible mess.
 
 The problem, of course, is that building long, complex, varying blocks of text with string
 concatenation and interpolation is fragile, unreadable, and painful. You know this, but you're not
-going to write an entirely new class or pull in some big new dependency just for 10 lines of HTML.
-Instead, you hammer through it and end up with code like this:
+going to write an entirely new class or pull in some big new dependency just for 10 lines of HTML, 
+so instead you hammer through it and end up with code like this:
 
 ```ruby
 picture_tag = "<picture>\n"\
-                      "#{source_tags}"\
-                      "#{markdown_escape * 4}<img src=\"#{url}#{instance['source_default'][:generated_src]}\" #{html_attr_string}>\n"\
-"#{markdown_escape * 2}</picture>\n"
+              "#{source_tags}"\
+              "#{markdown_escape * 4}"\
+              "<img src=\"#{url}#{instance['source_default'][:generated_src]}\" "\
+              "#{html_attr_string}>\n"\"#{markdown_escape * 2}</picture>\n"
 ```
 
 or this: 
@@ -56,11 +62,15 @@ p.to_s
 # <p>
 # </p>
 
-# Add attributes as a hash, values can be strings or symbols:
+# Add attributes as a hash. keys can be strings or symbols, values can be arrays or strings:
 p.add_attributes class: 'stumpy grumpy', 'id' => 'the-ugly-one'
-# Add them as a string!
+
+# Add attributes as a string!
 p.add_attributes 'class="slimy" data-awesomeness="11"'
+
+# Add content. It can be anything, or an array of anythings.
 p.add_content "Icky"
+
 p.to_s
 # <p class="stumpy grumpy slimy" id="the-ugly-one" data-awesomeness="11">
 #   Icky
@@ -69,21 +79,22 @@ p.to_s
 # Want a oneliner?
 p.oneline = true
 p.to_s
-# <p class="stumpy mopey grumpy slimy" id="the-ugly-one" data-awesomeness="11">Icky</p>
+# <p class="stumpy grumpy slimy" id="the-ugly-one" data-awesomeness="11">Icky</p>
 p.oneline = false
 
-# Build it up step by step, or all at once:
+# Build a tag all at once:
 p.add_content DoubleTag.new(
   'a',
   content: 'Link!',
   attributes: {href: 'awesome-possum.com'},
   oneline: true
 )
-# Add a parent tag!
+
+# Add a parent tag:
 div = p.add_parent DoubleTag.new 'div'
 
 # Ruby implicitly calls .to_s on things when you try to perform string functions with them, so
-# things like this work:
+# this works:
 "#{div}"
 # <div>
 #   <p class="stumpy mopey grumpy slimy" id="the-ugly-one" data-awesomeness="11">
@@ -93,6 +104,11 @@ div = p.add_parent DoubleTag.new 'div'
 # </div>
 
 ```
+
+For complete example usage, see [jekyll_icon_list](https://github.com/rbuchberger/jekyll_icon_list), or
+this [pull request](https://github.com/robwierzbowski/jekyll-picture-tag/pull/87/commits/d6b2deca0f19f173251a2984037e5e5f8d7c21d1)
+to [jekyll-picture-tag](https://github.com/robwierzbowski/jekyll-picture-tag).
+
 ## Installation
 
  ```ruby
@@ -119,24 +135,24 @@ So we're on the same page, here's the terminology I'm using:
 - c    -  content
 - d    -  closing tag
 
+
+## Usage
+
 There are 2 classes: `SingleTag` is the base class, and `DoubleTag` inherits from it. A `SingleTag`
 is a self-closing tag, meaning it has no content and no closing tag. A `DoubleTag` is the other
 kind.
 
-## Usage
-
 ### SingleTag Properties:
 
  #### element
  - String
  - Mandatory
  - Which type of tag it is, such as 'hr' or 'img'
- - Defined on initialization, cannot be changed afterwards. (Should it be? I'm on the fence about it.)
      
  #### attributes
   - Hash 
   - Optional
-  - Keys are symbols, values are arrays of strings. `{class: ['stumpy', 'slimy']}`
+  - Keys are stored as symbols, values are stored as arrays of strings: `{class: ['stumpy', 'slimy']}`
   - add them with `.add_attributes`, which can accept a few different formats.
 
 ### SingleTag Methods (that you care about)
@@ -145,20 +161,29 @@ kind.
 
 `.to_s` - The big one. Returns your HTML as a string, nondestructively.
 
+`.add_attributes(new)` - The strongly recommended way to add new attributes. Can accept a hash (keys
+can be either symbols or strings, values can be either arrays or strings), or a string in the
+standard HTML syntax (`attribute="value" attribute2="value2 value3"`). Returns self. 
+
 `.reset_attributes(new)` - Deletes all attributes, calls add_attributes on supplied argument if
 given.
 
-`.add_attributes(new)` - The only way we add new attributes. Can accept a hash (keys can be either
-symbols or strings), or a string in the standard HTML syntax (`attribute="value" attribute2="value2
-value3"`). Returns self. 
+`.delete_attributes(keys)` - Accepts a single attribute, or an array of attributes (keys or
+strings), and deletes it.
+
+`.rewrite_attributes` - Accepts anything add_attributes understands, but replaces existing
+attributes instead of appending to them.
 
 `.add_parent(DoubleTag)` - returns supplied DoubleTag, with self added as a child.
 
-`attr_reader :attributes, :element`
+
+
+`attr_reader :attributes`
+`attr_accessor :element`
 
 ### DoubleTag Properties:
 
-#### `DoubleTag` Inherits all of `SingleTag`'s properties and methods, but adds content and a closing tag.
+#### `DoubleTag` Inherits all of `SingleTag`'s properties and methods, and adds content and a closing tag.
 
  #### content
 
@@ -184,7 +209,9 @@ value3"`). Returns self.
 content.
 
 `add_content(anything)` - Smart enough to handle both arrays and not-arrays without getting dorked
-up.
+up. When given an array, its elements will be appended to the content array. When given a single
+item, that item will be inserted at the end of the array. (Remember each element in the content
+array gets at least one line!)
 
 `attr_accessor: content` - You can modify the content array directly if you like. If you're just
 adding items, you should use `.add_content`
@@ -194,8 +221,8 @@ appropriate indentation applied, this is how you can get it.
 
 ## Configuration
  
- Indentation is defined by the `indent` method on the DoubleTag class. If you'd like to change
- it:
+ Indentation is defined by the `indent` method on the DoubleTag class, which is two markdown-escaped
+ spaces by default ("\ \ "). If you'd like to change it:
 
  1. Make a new class, inherit from DoubleTag.
  2. Override `indent` with whatever you want.
@@ -223,11 +250,10 @@ MyDoubleTag.new('p', content: 'hello').to_s
 
  ## Limitations
 
-* It doesn't know a single HTML element on its own, so it does nothing to ensure your 
-  HTML is valid. Garbage in, garbage out.
+* It doesn't know a single HTML element on its own, so it does nothing to ensure your HTML is valid.
 
-* A parent tag can't put siblings on the same line. You can either
-  do this (with `oneline: true` on the strong tag):
+* A parent tag can't put siblings on the same line. You can either do this (with `oneline: true` on
+   the strong tag):
 
     ```html
 
@@ -247,7 +273,7 @@ MyDoubleTag.new('p', content: 'hello').to_s
       text.
 
     ```
-    But you can't do this without string interpolation:
+    But you can't do this without string interpolation or something:
 
     ```html
 
@@ -258,7 +284,7 @@ MyDoubleTag.new('p', content: 'hello').to_s
     source code layout.
 
 * If you set 'oneline: true' on a parent DoubleTag, but not all its children DoubleTags, the output
-  will not be pretty. I advise against it.
+  will not be pretty. I advise against it. Handling this situation is on the TODO list.
 
 * It doesn't wrap long lines of text, and it doesn't indent text with newlines embedded. It's on the
   TODO list.

data/lib/objective_elements/single_tag.rb

@@ -18,6 +18,8 @@ class SingleTag
   def reset_attributes(new = nil)
     @attributes = {}
     add_attributes(new) if new
+
+    self
   end
 
   # This is the only way we add new attributes. Flexible about what you give
@@ -30,8 +32,36 @@ class SingleTag
     else
       add_hash_attributes(new)
     end
+
+    self
+  end
+  alias add_attribute add_attributes
+
+  def delete_attributes(keys)
+    # accepts an array or a single element
+    to_delete = if keys.is_a? Array
+                  keys.map(&:to_sym)
+                else
+                  [keys.to_sym]
+                end
+
+    to_delete.each { |k| @attributes.delete k }
+
+    self
+  end
+  alias delete_attribute delete_attributes
+
+  def rewrite_attribute(new)
+    formatted_new = if new.is_a? String
+                      hashify_attributes(new)
+                    else
+                      new.transform_keys(&:to_sym)
+                    end
+
+    delete_attributes formatted_new.keys
+
+    add_hash_attributes formatted_new
   end
-  alias_method :add_attribute, :add_attributes
 
   # Turns attributes into a string we can insert.
   def render_attributes
@@ -64,16 +94,19 @@ class SingleTag
 
   private
 
-  def add_string_attributes(new)
+  def add_string_attributes(new_string)
+    add_hash_attributes hashify_attributes new_string
+  end
+
+  def hashify_attributes(new_string)
     # looking for something like:
     # 'class="something something-else" id="my-id"'
     new_hash = {}
-    new.scan(/ ?([^="]+)="([^"]+)"/).each do |m|
+    new_string.scan(/ ?([^="]+)="([^"]+)"/).each do |m|
       # [['class','something something-else'],['id','my-id']]
       new_hash[m.shift] = m.pop
     end
-
-    add_hash_attributes(new_hash)
+    new_hash
   end
 
   def add_hash_attributes(new)
@@ -88,5 +121,4 @@ class SingleTag
     end
     self
   end
-
 end

data/lib/objective_elements/version.rb

@@ -1,3 +1,3 @@
 module ObjectiveElements
-  VERSION = "0.2.0"
+  VERSION = '0.3.0'.freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: objective_elements
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Robert Buchberger
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-10-02 00:00:00.000000000 Z
+date: 2018-10-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler