psychgus 1.0.1 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3cfde7f03f882111004ff6803bccf54482e0fe87096339e9c2978dafbe75e886
-  data.tar.gz: 5d2e3b11f94fe6272032cd94657f1918106b29446a72c90762a9c8ea04058405
+  metadata.gz: 8b9e7e5d21e498f39d61b2b83765879dd6c564cc2742b121dfdeb9f5b8051578
+  data.tar.gz: 13ef8c78dc13bcce6596534e2b94557033438289a86e459834b4d7acf0afb9c1
 SHA512:
-  metadata.gz: cc8920579914bda512cfa5b347ecb5af3221843634e7b019e368be93ff2160a353e833aa631c388f5a3118ba5247fcb469cc7b23f4802c46837d839ab7331ce4
-  data.tar.gz: f6cb6210f97e2178c8ce95c16ec7eb276115376c11ad200aec6540a2e98fe2a03721f7674407fa056aabec8f62a83643ca13358dbf6989ef0969ba8dcaf018c4
+  metadata.gz: abfc0427ed29d4e3d811476a2c957f7961a85fbb0445b558d3b1356f018b12b52026a6b268b9f23384aa0a9fd20e3c720a30091448ea1659c8ddb8298e5c3b74
+  data.tar.gz: ef2db56b9b41bc3aa3f81f3a033e5aaf9508578d9aa63e5de10e978950fa9c860f77ca39ffa8c0077409149f87059faa515b51080290bf59f8e9a53dc74d366a

data/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog | Psychgus
+
+Format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
+
+## [[Unreleased]](https://github.com/esotericpig/psychgus/compare/v1.2.0...master)
+
+## [v1.2.0] - 2019-07-11
+
+### Added
+- Commonly-used Stylers and Stylables
+- Changelog
+- Psychgus.hierarchy()
+- SuperSniffer::Parent#child_key?() & #child_value?()
+
+### Changed
+- SuperSniffer's parent will never be nil, so don't have to check for nil in Stylers
+- Some doc comments & README
+- Gemspec's included files to be more specific (to prevent accidentally adding non-gem-related files)
+
+### Fixed
+- Psychgus.dump_stream() if you only pass in a Hash w/ symbols as keys (options would be set to it, instead of objects)
+
+## [v1.0.0] - 2019-07-03
+### Added
+### Changed
+### Deprecated
+### Removed
+### Fixed
+### Security

data/README.md

@@ -2,8 +2,41 @@
 
 [![Gem Version](https://badge.fury.io/rb/psychgus.svg)](https://badge.fury.io/rb/psychgus)
 
+[![Documentation](https://img.shields.io/badge/doc-yard-%23A0522D.svg?style=for-the-badge)](https://esotericpig.github.io/docs/psychgus/yardoc/index.html)
+[![Changelog](https://img.shields.io/badge/changelog-md-%23A0522D.svg?style=for-the-badge)](CHANGELOG.md)
+[![License](https://img.shields.io/github/license/esotericpig/psychgus.svg?color=%23A0522D&style=for-the-badge)](LICENSE.txt)
+
 Psychgus uses the core standard library [Psych](https://github.com/ruby/psych) for working with [YAML](https://yaml.org) and extends it so that developers can easily style the YAML according to their needs.
 
+Turn this YAML...
+
+```YAML
+---
+Psych Gus:
+  Aliases:
+  - Longbranch Pennywhistle
+  - Squirts Macintosh
+  - Clementine Woolysocks
+  - Lavender Gooms
+  - Big Baby Burton
+  - Chocolate Einstein
+  - MC Clap Yo Handz
+  Skills:
+  - The Blueberry
+  - The Super Sniffer
+  - Positive Work Attitude
+```
+
+Into this:
+
+```YAML
+---
+Psych Gus:
+  Aliases: [Longbranch Pennywhistle, Squirts Macintosh, Clementine Woolysocks, Lavender
+      Gooms, Big Baby Burton, Chocolate Einstein, MC Clap Yo Handz]
+  Skills: [The Blueberry, The Super Sniffer, Positive Work Attitude]
+```
+
 Thank you to the people that worked and continue to work hard on the Psych project.
 
 The Psychgus name comes from the well-styled character Gus from the TV show Psych.
@@ -16,6 +49,8 @@ The Psychgus name comes from the well-styled character Gus from the TV show Psyc
     - [Hash Example](#hash-example)
     - [Class Example](#class-example)
     - [Advanced Usage](#advanced-usage)
+    - [Common Stylers](#common-stylers)
+        - [Stylers Example](#stylers-example)
 - [Hacking](#hacking)
     - [Testing](#testing)
     - [Generating Doc](#generating-doc)
@@ -25,21 +60,35 @@ The Psychgus name comes from the well-styled character Gus from the TV show Psyc
 
 Pick your poison...
 
-- With the RubyGems CLI package manager:
-    - `$ gem install psychgus`
-- In your *Gemspec* (*<project>.gemspec*):
-    - `spec.add_runtime_dependency 'psychgus','~> x.x.x'`
-    - Or, if you only need Psychgus in development (e.g., tests, rake, documentation):
-        - `spec.add_development_dependency 'psychgus','~> x.x.x'`
-- In your *Gemfile*:
-    - `gem 'psychgus','~> x.x.x'`
-    - Or, with GitHub:
-        - `gem 'psychgus',:git=>'https://github.com/esotericpig/psychgus.git'`
-- Manually:
-    - `$ git clone 'https://github.com/esotericpig/psychgus.git'`
-    - `$ cd psychgus`
-    - `$ bundle install`
-    - `$ bundle exec rake install:local`
+With the RubyGems CLI package manager:
+
+`$ gem install psychgus`
+
+In your *Gemspec* (*<project>.gemspec*):
+
+```Ruby
+# Pick one...
+spec.add_runtime_dependency 'psychgus', '~> X.X.X'
+spec.add_development_dependency 'psychgus', '~> X.X.X'
+```
+
+In your *Gemfile*:
+
+```Ruby
+# Pick one...
+gem 'psychgus', '~> X.X.X'
+gem 'psychgus', '~> X.X.X', :group => :development
+gem 'psychgus', :git => 'https://github.com/esotericpig/psychgus.git', :tag => 'vX.X.X'
+```
+
+Manually:
+
+```
+$ git clone 'https://github.com/esotericpig/psychgus.git'
+$ cd psychgus
+$ bundle install
+$ bundle exec rake install:local
+```
 
 ## [Using](#contents)
 
@@ -49,7 +98,17 @@ To begin styling, create a class and mix in (include) `Psychgus::Styler`. Then p
 
 For classes, you can optionally include `Psychgus::Blueberry` and return the styler(s) for the class by defining the `psychgus_stylers(sniffer)` method.
 
-### [Simple Example](#contents)
+Instead of making your own styler, you can also use one of the [pre-defined stylers](#common-stylers).
+
+### Contents | Using
+
+[Simple Example](#simple-example)
+| [Hash Example](#hash-example)
+| [Class Example](#class-example)
+| [Advanced Usage](#advanced-usage)
+| [Common Stylers](#common-stylers)
+
+### [Simple Example](#using)
 
 ```Ruby
 require 'psychgus'
@@ -95,7 +154,7 @@ puts Coffee.new.to_yaml
 # style: [Cappuccino, Espresso, Latte, Mocha]
 ```
 
-### [Hash Example](#contents)
+### [Hash Example](#using)
 
 ```Ruby
 require 'psychgus'
@@ -190,7 +249,7 @@ puts burgers.to_yaml({:indent => 3,:stylers => BurgerStyler.new,:deref_aliases =
 #    Bun: Kaiser
 ```
 
-### [Class Example](#contents)
+### [Class Example](#using)
 
 ```Ruby
 require 'psychgus'
@@ -231,8 +290,8 @@ class BurgerStyler
     parent = sniffer.parent
     
     # Single quote scalars that are not keys to a map
-    node.style = Psychgus::SCALAR_SINGLE_QUOTED if !parent.nil?() &&
-                                                   parent.child_type != :key
+    # - "child_key?" is the same as "child_type == :key"
+    node.style = Psychgus::SCALAR_SINGLE_QUOTED unless parent.child_key?()
   end
   
   # Style sequences (Psych::Nodes::Sequence)
@@ -361,7 +420,7 @@ puts burgers.to_yaml({:indent => 3,:deref_aliases => true})
 #    Sauce: 'Honey BBQ'
 ```
 
-### [Advanced Usage](#contents)
+### [Advanced Usage](#using)
 
 ```Ruby
 require 'psychgus'
@@ -452,6 +511,63 @@ puts parser.handler.root.to_ruby
 puts
 ```
 
+### [Common Stylers](#using)
+
+A collection of commonly-used [Stylers](https://esotericpig.github.io/docs/psychgus/yardoc/Psychgus/Stylers.html) and [Stylables](https://esotericpig.github.io/docs/psychgus/yardoc/Psychgus/Stylables.html) are included with Psychgus.
+
+| Styler | Description |
+| --- | --- |
+| [CapStyler](https://esotericpig.github.io/docs/psychgus/yardoc/Psychgus/Stylers/CapStyler.html) | Capitalizer for Scalars |
+| [FlowStyler](https://esotericpig.github.io/docs/psychgus/yardoc/Psychgus/Stylers/FlowStyler.html) | FLOW style changer for Mappings & Sequences |
+| [MapFlowStyler](https://esotericpig.github.io/docs/psychgus/yardoc/Psychgus/Stylers/MapFlowStyler.html) | FLOW style changer for Mappings only |
+| [NoSymStyler](https://esotericpig.github.io/docs/psychgus/yardoc/Psychgus/Stylers/NoSymStyler.html) | Symbol remover for Scalars |
+| [NoTagStyler](https://esotericpig.github.io/docs/psychgus/yardoc/Psychgus/Stylers/NoTagStyler.html) | Tag remover for classes |
+| [SeqFlowStyler](https://esotericpig.github.io/docs/psychgus/yardoc/Psychgus/Stylers/SeqFlowStyler.html) | FLOW style changer for Sequences only |
+
+#### [Stylers Example](#common-stylers)
+
+```Ruby
+require 'psychgus'
+
+class EggCarton
+  def initialize
+    @eggs = {
+      :styles => ['fried', 'scrambled', ['BBQ', 'ketchup & mustard']],
+      :colors => ['brown', 'white', ['blue', 'green']]
+    }
+  end
+end
+
+puts EggCarton.new.to_yaml(stylers: [
+  Psychgus::NoSymStyler.new,
+  Psychgus::NoTagStyler.new,
+  Psychgus::CapStyler.new,
+  Psychgus::FlowStyler.new(4)
+])
+
+# Output:
+# ---
+# Eggs:
+#   Styles: [Fried, Scrambled, [BBQ, Ketchup & Mustard]]
+#   Colors: [Brown, White, [Blue, Green]]
+
+puts EggCarton.new.to_yaml
+
+# Output (without Stylers):
+# --- !ruby/object:EggCarton
+# eggs:
+#   :styles:
+#   - fried
+#   - scrambled
+#   - - BBQ
+#     - ketchup & mustard
+#   :colors:
+#   - brown
+#   - white
+#   - - blue
+#     - green
+```
+
 ## [Hacking](#contents)
 
 ```
@@ -460,7 +576,7 @@ $ bundle install
 $ bundle exec rake -T
 ```
 
-### [Testing](#contents)
+### [Testing](#hacking)
 
 Run tests, excluding tests that create temp files:
 
@@ -470,7 +586,7 @@ Run all tests:
 
 `$ bundle exec rake test_all`
 
-### [Generating Doc](#contents)
+### [Generating Doc](#hacking)
 
 Generate basic doc:
 

data/Rakefile

@@ -52,7 +52,7 @@ task :ghp_doc,[:deploy] do |task,args|
   
   sh rsync_cmd
   
-  if dry_run
+  if !args.deploy
     puts
     puts 'Execute "rake ghp_doc[true]" for actually deploying (non-dry-run)'
   end
@@ -80,7 +80,7 @@ end
 YARD::Rake::YardocTask.new() do |task|
   task.files = ['lib/**/*.rb']
   
-  task.options += ['--files','LICENSE.txt']
+  task.options += ['--files','CHANGELOG.md,LICENSE.txt']
   task.options += ['--readme','README.md']
   
   task.options << '--protected' # Show protected methods
@@ -121,20 +121,25 @@ task :yard_fix,[:dev] do |task,args|
           out = true
         end
         
-        # Contents relative links
+        # Anchor links
         tag = 'href="#'
-        if !(i = line.index(Regexp.new(Regexp.quote(tag) + '[a-z]'))).nil?()
-          i += tag.length
-          j = line.index('"',i)
-          
-          href = line[i...j].split('-').map(&:capitalize).join('_')
-          line = "#{line[0...i]}#{href}#{line[j..-1]}"
+        quoted_tag = Regexp.quote(tag)
+        
+        if !(i = line.index(Regexp.new(quoted_tag + '[a-z]'))).nil?()
+          line = line.gsub(Regexp.new(quoted_tag + '[a-z][^"]*"')) do |href|
+            link = href[tag.length..-2]
+            link = link.split('-').map(&:capitalize).join('_')
+            
+            %Q(#{tag}#{link}")
+          end
           
           out = true
         end
         
-        out ||= !line.gsub!('href="LICENSE.txt"','href="file.LICENSE.html"').nil?()
-        out ||= !line.gsub!('code class="Ruby"','code class="language-ruby"').nil?()
+        out = !line.gsub!('href="CHANGELOG.md"','href="file.CHANGELOG.html"').nil?() || out
+        out = !line.gsub!('href="LICENSE.txt"','href="file.LICENSE.html"').nil?() || out
+        out = !line.gsub!('code class="Ruby"','code class="language-ruby"').nil?() || out
+        out = !line.gsub!('code class="YAML"','code class="language-yaml"').nil?() || out
         
         if out
           puts "  #{line}"

data/lib/psychgus.rb

@@ -24,9 +24,11 @@ require 'psych'
 
 require 'psychgus/blueberry'
 require 'psychgus/ext'
+require 'psychgus/stylables'
 require 'psychgus/styled_document_stream'
 require 'psychgus/styled_tree_builder'
 require 'psychgus/styler'
+require 'psychgus/stylers'
 require 'psychgus/super_sniffer'
 require 'psychgus/version'
 
@@ -99,8 +101,8 @@ require 'psychgus/super_sniffer/parent'
 #       parent = sniffer.parent
 #       
 #       # Single quote scalars that are not keys to a map
-#       node.style = Psychgus::SCALAR_SINGLE_QUOTED if !parent.nil?() && 
-#                                                      parent.child_type != :key
+#       # - "child_key?" is the same as "child_type == :key"
+#       node.style = Psychgus::SCALAR_SINGLE_QUOTED unless parent.child_key?()
 #       
 #       # Remove colon (change symbols into strings)
 #       node.value = node.value.sub(':','')
@@ -308,6 +310,12 @@ require 'psychgus/super_sniffer/parent'
 # @since  1.0.0
 ###
 module Psychgus
+  # Include these in the top namespace for convenience (i.e., less typing).
+  # 
+  # @since 1.2.0
+  include Stylables
+  include Stylers
+  
   NODE_CLASS_ALIASES = {:Doc => :Document,:Map => :Mapping,:Seq => :Sequence}
   OPTIONS_ALIASES = {:canon => :canonical,:indent => :indentation}
   
@@ -327,8 +335,8 @@ module Psychgus
   def self.node_class(name)
     name = name.to_sym().capitalize()
     
-    name_alias = NODE_CLASS_ALIASES[name]
-    name = name_alias unless name_alias.nil?()
+    actual_name = NODE_CLASS_ALIASES[name]
+    name = actual_name unless actual_name.nil?()
     
     return Psych::Nodes.const_get(name)
   end
@@ -448,15 +456,30 @@ module Psychgus
   # @see Psych.dump_stream
   # @see OPTIONS_ALIASES
   def self.dump_stream(*objects,io: nil,stylers: nil,deref_aliases: false,**options)
+    # If you call this method with only a Hash that uses symbols as keys,
+    # then options will be set to the Hash, instead of objects.
+    # 
+    # For example, the below will be stored in options, not objects:
+    # - dump_stream({:coffee => {:roast => [],:style => []}})
+    # 
+    # This if-statement is guaranteed because dump_stream([]) and dump_stream(nil)
+    # will produce [[]] and [nil], which are not empty.
+    # 
+    # dump_stream() w/o any args is the only problem, but resolved w/ [nil].
+    if objects.empty?()
+      objects = options.empty?() ? [nil] : [options]
+      options = {}
+    end
+    
     if Hash === io
       options = io
       io = nil
     end
     
-    if !options.nil?()
-      OPTIONS_ALIASES.each do |option_alias,option|
-        if options.key?(option_alias) && !options.key?(option)
-          options[option] = options[option_alias]
+    if !options.empty?()
+      OPTIONS_ALIASES.each do |option_alias,actual_option|
+        if options.key?(option_alias) && !options.key?(actual_option)
+          options[actual_option] = options[option_alias]
         end
       end
     end
@@ -464,13 +487,117 @@ module Psychgus
     visitor = Psych::Visitors::YAMLTree.create(options,StyledTreeBuilder.new(*stylers,
       deref_aliases: deref_aliases))
     
-    objects.each do |object|
-      visitor << object
+    if objects.empty?()
+      # Else, will throw a cryptic NoMethodError:
+      # - "psych/tree_builder.rb:in `set_end_location': undefined method `end_line=' for nil:NilClass (NoMethodError)"
+      # 
+      # This should never occur because of the if-statement at the top of this method.
+      visitor << nil
+    else
+      objects.each do |object|
+        visitor << object
+      end
     end
     
     return visitor.tree.yaml(io,options)
   end
   
+  # Get a visual hierarchy of the levels as a String.
+  # 
+  # This is useful for determining the correct level/position when writing a {Styler}.
+  # 
+  # @example
+  #   require 'psychgus'
+  #   
+  #   burgers = {
+  #     :burgers => {
+  #       :classic => {:sauce  => %w(Ketchup Mustard),
+  #                    :cheese => 'American',
+  #                    :bun    => 'Sesame Seed'},
+  #       :bbq     => {:sauce  => 'Honey BBQ',
+  #                    :cheese => 'Cheddar',
+  #                    :bun    => 'Kaiser'},
+  #       :fancy   => {:sauce  => 'Spicy Wasabi',
+  #                    :cheese => 'Smoked Gouda',
+  #                    :bun    => 'Hawaiian'}
+  #     },
+  #     :toppings => [
+  #       'Mushrooms',
+  #       %w(Lettuce Onions Pickles Tomatoes),
+  #       [%w(Ketchup Mustard), %w(Salt Pepper)]
+  #     ]
+  #   }
+  #   
+  #   puts Psychgus.hierarchy(burgers)
+  #   
+  #   # Output:
+  #   # ---
+  #   # (level:position):current_node - <parent:(parent_level:parent_position)>
+  #   # ---
+  #   # (1:1):Psych::Nodes::Stream - <root:(0:0)>
+  #   # (1:1):Psych::Nodes::Document - <stream:(1:1)>
+  #   # (1:1):Psych::Nodes::Mapping - <doc:(1:1)>
+  #   #  (2:1)::burgers - <map:(1:1)>
+  #   #   (3:1):Psych::Nodes::Mapping - <:burgers:(2:1)>
+  #   #    (4:1)::classic - <map:(3:1)>
+  #   #     (5:1):Psych::Nodes::Mapping - <:classic:(4:1)>
+  #   #      (6:1)::sauce - <map:(5:1)>
+  #   #       (7:1):Psych::Nodes::Sequence - <:sauce:(6:1)>
+  #   #        (8:1):Ketchup - <seq:(7:1)>
+  #   #        (8:2):Mustard - <seq:(7:1)>
+  #   #      (6:2)::cheese - <map:(5:1)>
+  #   #       (7:1):American - <:cheese:(6:2)>
+  #   #      (6:3)::bun - <map:(5:1)>
+  #   #       (7:1):Sesame Seed - <:bun:(6:3)>
+  #   #    (4:2)::bbq - <map:(3:1)>
+  #   #     (5:1):Psych::Nodes::Mapping - <:bbq:(4:2)>
+  #   #      (6:1)::sauce - <map:(5:1)>
+  #   #       (7:1):Honey BBQ - <:sauce:(6:1)>
+  #   #      (6:2)::cheese - <map:(5:1)>
+  #   #       (7:1):Cheddar - <:cheese:(6:2)>
+  #   #      (6:3)::bun - <map:(5:1)>
+  #   #       (7:1):Kaiser - <:bun:(6:3)>
+  #   #    (4:3)::fancy - <map:(3:1)>
+  #   #     (5:1):Psych::Nodes::Mapping - <:fancy:(4:3)>
+  #   #      (6:1)::sauce - <map:(5:1)>
+  #   #       (7:1):Spicy Wasabi - <:sauce:(6:1)>
+  #   #      (6:2)::cheese - <map:(5:1)>
+  #   #       (7:1):Smoked Gouda - <:cheese:(6:2)>
+  #   #      (6:3)::bun - <map:(5:1)>
+  #   #       (7:1):Hawaiian - <:bun:(6:3)>
+  #   #  (2:2)::toppings - <map:(1:1)>
+  #   #   (3:1):Psych::Nodes::Sequence - <:toppings:(2:2)>
+  #   #    (4:1):Mushrooms - <seq:(3:1)>
+  #   #    (4:2):Psych::Nodes::Sequence - <seq:(3:1)>
+  #   #     (5:1):Lettuce - <seq:(4:2)>
+  #   #     (5:2):Onions - <seq:(4:2)>
+  #   #     (5:3):Pickles - <seq:(4:2)>
+  #   #     (5:4):Tomatoes - <seq:(4:2)>
+  #   #    (4:3):Psych::Nodes::Sequence - <seq:(3:1)>
+  #   #     (5:1):Psych::Nodes::Sequence - <seq:(4:3)>
+  #   #      (6:1):Ketchup - <seq:(5:1)>
+  #   #      (6:2):Mustard - <seq:(5:1)>
+  #   #     (5:2):Psych::Nodes::Sequence - <seq:(4:3)>
+  #   #      (6:1):Salt - <seq:(5:2)>
+  #   #      (6:2):Pepper - <seq:(5:2)>
+  # 
+  # @param objects [Object,Array<Object>] the Object(s) to get a visual hierarchy of
+  # @param kargs [Hash] the keyword args to pass to {Stylers::HierarchyStyler} and to {dump_stream}
+  # 
+  # @return [String] the visual hierarchy of levels
+  # 
+  # @see Stylers::HierarchyStyler
+  # @see dump_stream
+  # 
+  # @since 1.2.0
+  def self.hierarchy(*objects,**kargs)
+    styler = Stylers::HierarchyStyler.new(**kargs)
+    
+    dump_stream(*objects,stylers: styler,**kargs)
+    
+    return styler.to_s()
+  end
+  
   # Parse +yaml+ into a Psych::Nodes::Document.
   # 
   # If you're just going to call to_ruby(), then using this method is unnecessary,
@@ -637,7 +764,7 @@ module Psychgus
   # 
   # Private methods of Psych are not defined.
   # 
-  # Because extend is used, do not prefix methods with "self."
+  # @note For devs/hacking: because extend is used, do not prefix methods with "self."
   # 
   # @author Jonathan Bradley Whited (@esotericpig)
   # @since  1.0.0