objective_elements 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c40decb6ef274c91eb3c04c8b88e3fe8cfebf9be34173044faa8541bee7e1a8c
-  data.tar.gz: c89f6d58e729c5a3a60095244fcdbcdb30b1f109214b0faf91b9b3c4fd27cf83
+  metadata.gz: cd77403a8910ff13f0b09d7d6d1a1e258b272f728d210f795d87e4df666309d3
+  data.tar.gz: b937e84cc9071b9f103cc8fa8980b2a3f68ce976c22e6baf79d2cd23c8b16bb6
 SHA512:
-  metadata.gz: 7ba86d122bbacc96b7fa989cb122a63582cb9e6619a5e42777ed7eb69bf80b2837feca836c0f430c870a60c34e0f22906b10e808e1debd1c6ebe7f6b9ab6da56
-  data.tar.gz: 236c0aa5c7768d653ad702b63b66ffc2261416ac0cad3ba9bc404684f7428d41584468f9951b5967125f14b33000c26b5e79f7910dea6081e43f4879d03e65c7
+  metadata.gz: e14e8f6c77cd762a26180d477ce028df2db91bf03309283dcdeb84c63cd0eb540af60f7c041b6c9d24d2a1647ccff47e5fab2037990f44bc4737a92168cd417c
+  data.tar.gz: 07712c2317042d016e37dee5b95e1d411c2788ab2b61399ff3adf790c9282ae73d66dbcaf7a87da1ed8116fd554c836257707f93a158b871f6c8d28a3a044405

data/README.md

@@ -1,23 +1,15 @@
 # Objective Elements
 
-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 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.
 
 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,
+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. Nest tags infinitely.
-
-* Render it with `.to_s`
-
 ## Motivation:
 
 Have you ever tried to build HTML with string concatenation and interpolation? It starts out simply
@@ -51,62 +43,49 @@ or this:
     end
 ```
 
-Which is why I sat down and wrote this gem. It's super simple, you probably could have written it
-too, but hey! Now you don't have to. Here's a demo:
-
 ## Demo
 
 ```ruby
-# gemfile:
-gem 'objective_elements',  '~>1.0.0'
-
-# Anywhyere else:
-require 'objective_elements'
-
 p = DoubleTag.new 'p'
 p.to_s
 # <p>
 # </p>
 
-# Add attributes as a hash. keys can be strings or symbols, values can be arrays or strings:
 p.attributes << { class: 'stumpy grumpy', 'id' => 'the-ugly-one' }
 
-# Add attributes as a string!
+p.id
+# the-ugly-one
+
 p.attributes << 'class="slimy" data-awesomeness="11"'
 
-# Get attributes by calling a method!
-p.data-awesomeness 
+
+# Ruby method names can't have dashes.
+p.attributes['data-awesomeness']
 # '11'
 
-# Set them, too! (Note: This doesn't work for class or method)
 p.id = 'killer'
 
-# Add content. It can be anything, or an array of anythings.
-p.add_content "Icky"
+p << "Icky"
 
 p.to_s
 # <p class="stumpy grumpy slimy" id="killer" data-awesomeness="11">
 #   Icky
 # </p>
 
-# Want a oneliner?
 p.oneline = true
 p.to_s
 # <p class="stumpy grumpy slimy" id="killer" data-awesomeness="11">Icky</p>
 p.oneline = false
 
-# Build a tag all at once:
 p.add_content DoubleTag.new(
   'a',
   content: 'Link!',
-  attributes: {href: 'awesome-possum.com'},
+  attributes: { href: 'awesome-possum.com' },
   oneline: true
 )
 
-# Add a parent tag:
 div = p.add_parent DoubleTag.new 'div'
 
-# Implicit string conversion means cool stuff like this works:
 "#{div}"
 # <div>
 #   <p class="stumpy grumpy slimy" id="killer" data-awesomeness="11">
@@ -117,26 +96,31 @@ div = p.add_parent DoubleTag.new '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).
+## Changes
+
+### 1.1.0
+Add `ShelfTag`, which is useful when you want to create siblings without a parent element.
+
+### 1.0.0
+Attributes syntax has changed pretty significantly. Find `.add_attributes` & replace `.attributes << `
+will get you most of the way there, but you should read over the usage section again.
 
 ## Installation
 
  ```ruby
  # Gemfile
  
- gem 'objective_elements', '~> 0.2.0'
+ gem 'objective_elements', '~> 1.0.0'
  ```
  
  ```ruby
- # Wherever you need to use it:
+ # Anywhere else:
  
  require 'objective_elements'
  ```
+ 
 ## Terminology
 
-So we're on the same page, here's the terminology I'm using:
 ```
 <p class="stumpy">Hello</p>
 |a|       b      |  c  | d |
@@ -150,75 +134,114 @@ So we're on the same page, here's the terminology I'm using:
 
 ## Usage
 
+For Attribute & SingleTag examples, we'll use this image tag:
+```ruby
+
+img = SingleTag.new 'img', attributes: 'src="angry-baby.jpg"'
+
+```
+
 There are 2 classes you care about: `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.
 
 ### Attributes
 Attributes are their own class, and can be accessed by the `.attributes` method on both single and
-double tags. Important methods: 
+double tags. Important methods:
 
-` << (attribute)` - Add new attributes, can accept a hash or a string. Hash keys will be converted
+` << (attribute)` 
+- Example: `p.attributes << 'alt="he does not look happy"'`
+- Example: `p.attributes << { alt: "he does not look happy" }`
+- Add new attributes, can accept a hash or a string. Hash keys will be converted
 to symbols if they are not already, and values will be split on spaces into an array if they are not
 already. Attributes can also be given as a string in the standard HTML syntax (`class="myclass"
 id="my-id"`).  **Every other method which adds attributes in some way, calls this method**. This
 means that any time you are adding attributes, you can use any format which this method understands.
  
-`.delete(attribute)` - Delete one or more attributes. Accepts a string, symbol, or an array of
+`.delete(attribute)` 
+- Example: `img.attributes.delete 'src'`
+- Example: `img.attributes.delete :src`
+- Example: `img.attributes.delete [:src, 'alt']`
+- Delete one or more attributes. Accepts a string, symbol, or an array of
 strings and/or symbols.
 
-`.replace(attribute)` - Replaces one or more attributes and values.
+`.replace(attribute)` 
+- Example: `img.attributes.replace 'src="happy-baby.jpg"'`
+- Replaces one or more attributes and values individually.
+
+`.content[:attribute_name] = ` 
+- Example: `img.attributes.content[:src] = 'dirty-baby.jpg'` < This just broke everything.
+- Don't do it. Use `.replace`, `.(attribute name) = `, or `<<` 
+
+`.content[:attribute_name]` 
+- Example: `img.attributes[:src] # returns 'angry-baby.jpg`
+- Retrieve the content for a given attribute, as an array of strings. Must be a symbol. You'll
+- mostly need this when you don't know which attribute you need ahead of
+  time, or to access class and method attributes because you can't use the methods below:
+
+**There is a shorthand for the next two methods. Keep reading.**
 
-`.content[:attribute_name]` - Retrieve the content for a given attribute, as an array of strings.
-Must be a symbol. You'll mostly need this when you don't know which attribute you need ahead of ti
-me, or to access class and method attributes because you can't use the methods below:
+`.(attribute_name)` 
+- Example: `img.attributes.src # 'angry-baby.jpg'`
+- Convenience method/syntactic sugar: Returns the value of a given attribute name, as a
+- space-separated string. This relies on method_missing, which means that any overlap with
+  already existing methods won't work.  
+- **You can't access `class` or `method` html attributes this way, because
+  basic objects in ruby already have those methods.**
+- **Ruby methods can't have dashes in them.** This means `p.data-awesomeness` won't work.
 
-`.content[:attribute_name] = ` - Don't do it. Use `<<` or `.replace`.
+`.(attribute_name) = value` 
+- Example: `img.attributes.src = 'happy-baby.jpg'`
+- Same as above. Similar to `.replace(attribute)`. Interestingly, `method = ` and `class = ` both
+  work (`.class` is defined on the basic object class, but `.class=` is not.). Still, you
+  probably shouldn't use them.
 
-`.(attribute_name)` - Convenience method/syntactic sugar: Returns the value of a given attribute
-name, as a space-separated string. This relies on method_missing, which means that any overlap with
-already existing methods won't work.  **You can't access `class` or `method` html attributes this
-way, because basic objects in ruby already have those methods.**
+**Missing methods are forwarded from elements to their attributes, so you can do this:**
 
-`.(attribute_name) = value` - Same as above. Equivalent to `.replace(attribute)`. Interestingly,
-`method = ` and `class = ` both work (`.class` is defined on the basic object class, but `.class=`
-is not.). That said, you probably shouldn't use them because it will be confusing to understand
-later.
+- Example: `img.src # returns 'angry-baby.jpg'`
+- Example: `img.src = 'grumpy-baby.jpg'`
 
 ### SingleTag Properties:
 
  #### element
  - String
  - Mandatory
- - Which type of tag it is, such as 'hr' or 'img'
+ - Which type of tag, such as 'hr' or 'img'
+ 
  #### attributes
  - Instance of the class described above.
 
-
 ### SingleTag Methods (that you care about)
 
 `SingleTag.new(element, attributes: nil)`
 
-`.to_s` - The big one. Returns your HTML as a string, nondestructively.
+`.to_s` 
+- Example: `img.to_s`
+- The big one. Returns your HTML as a string, nondestructively.
 
-`.add_parent(DoubleTag)` - returns supplied DoubleTag, with self added as a child.
+`.add_parent(DoubleTag)` 
+- Example: `img.add_parent DoubleTag.new 'picture'`
+- returns supplied DoubleTag, with self added as a child.
 
-`.attributes` - attr_reader for HTML attributes. This is how you can access any attribute method
+`.attributes` 
+- Example: `img.attributes`
+- attr_reader for HTML attributes. This is how you can access any attribute method
 described above.
 
-`.reset_attributes` - Removes all attributes
+`.reset_attributes` 
+- Example: `img.reset_attributes`
+- Removes all attributes.
 
-`.attributes=(attributes)` - Sets attributes to the supplied argument
+`.attributes=(new)` 
+- Example: `img.attributes = 'src="grumpy-baby.jpg" id="muddy"'`
+- Equivalent to `reset_attributes` and `.attributes << new`
 
 `attr_reader :attributes`
 `attr_accessor :element`
 
-`.(attribute_name)` / `.(attribute_name) = ` - Forwarded to attributes object. Allows you to set or
-retrieve the value of attributes other than `class` and `method`, without having to type
-`.attributes` in front of it.
-
 ### DoubleTag Properties:
 
+
 #### `DoubleTag` Inherits all of `SingleTag`'s properties and methods, and adds content and a
 closing tag.
 
@@ -242,23 +265,43 @@ closing tag.
 
 ### DoubleTag Methods (that you care about)
 
-`DoubleTag.new(element, attributes: {}, oneline: false, content: [])` - You can initialize it with
-content.
+For DoubleTag Examples, we're working with a div tag: 
 
-`add_content(anything)` - Smart enough to handle both arrays and not-arrays without getting dorked
-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!)
+```
+div = DoubleTag.new 'div'
+```
+
+`DoubleTag.new(element, attributes: {}, oneline: false, content: [])` 
+- You can initialize it with content.
+
+`add_content(anything)` 
+- Example: `div.add_content 'example text!'`
+- Example: `div.add_content ['splits', 'across', 'lines']`
+- Example: `div.add_content img # image tag from earlier`
+- Smart enough to handle both arrays and not-arrays without getting dorked 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`
 
+`oneline` - Example: `div.oneline = true`
+
 `.to_a` - Mostly used internally, but if you want an array of strings, each element a line with
 appropriate indentation applied, this is how you can get it.
 
+### ShelfTags:
+
+Shelf tags are like invisible double tags. Think of them like a bookshelf.
+They're useful when you want to build siblings without a corresponding parent
+tag.
+
+Convert it into an actual tag with `.add_parent(DoubleTag)`
+
 ## Configuration
  
- Indentation is defined by the `indent` method on the DoubleTag class, which is two markdown-escaped
+ Indentation is defined by the `indent` method on the DoubleTag class, which is two escaped
  spaces by default ("\ \ "). If you'd like to change it:
 
  1. Make a new class, inherit from DoubleTag.

data/lib/objective_elements.rb

@@ -2,4 +2,5 @@ module ObjectiveElements
   require_relative 'objective_elements/single_tag'
   require_relative 'objective_elements/double_tag'
   require_relative 'objective_elements/html_attributes'
+  require_relative 'objective_elements/shelf_tag'
 end

data/lib/objective_elements/double_tag.rb

@@ -40,6 +40,7 @@ class DoubleTag < SingleTag
   private
 
   def build_content_line(element)
+    # Since DoubleTag inherits from SingleTag, it will slurp up those too.
     element.is_a?(SingleTag) ? element.to_a : element.to_s.dup
   end
 

data/lib/objective_elements/html_attributes.rb

@@ -6,6 +6,10 @@ class HTMLAttributes
     self << new
   end
 
+  def [](key)
+    @content[key.to_sym]
+  end
+
   def to_s
     return_string = ''
     @content.each_pair do |k, v|

data/lib/objective_elements/shelf_tag.rb

@@ -0,0 +1,17 @@
+# This is a nonexistent HTML tag, which holds content like a double tag but has
+# no opening or closing tag. This allows us to group siblings without adding an
+# extra parent to the markup.
+class ShelfTag < DoubleTag
+  def initialize(content: nil, oneline: false)
+    self.oneline = oneline
+    self.content = content
+  end
+
+  def to_a
+    content.map { |c| build_content_line c }.flatten
+  end
+
+  def add_parent(parent)
+    parent.add_content content
+  end
+end

data/lib/objective_elements/version.rb

@@ -1,3 +1,3 @@
 module ObjectiveElements
-  VERSION = '1.0.0'.freeze
+  VERSION = '1.1.0'.freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: objective_elements
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Robert Buchberger
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-10-23 00:00:00.000000000 Z
+date: 2019-02-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -84,6 +84,7 @@ files:
 - lib/objective_elements.rb
 - lib/objective_elements/double_tag.rb
 - lib/objective_elements/html_attributes.rb
+- lib/objective_elements/shelf_tag.rb
 - lib/objective_elements/single_tag.rb
 - lib/objective_elements/version.rb
 - objective_elements.gemspec
@@ -106,8 +107,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.7.3
+rubygems_version: 3.0.2
 signing_key: 
 specification_version: 4
 summary: Build HTML without interpolating strings.