psychgus 1.0.1 → 1.2.0

data/lib/psychgus/ext/yaml_tree_ext.rb

@@ -50,13 +50,14 @@ module Psychgus
     module YAMLTreeExt
       # Accepts a new Object to convert to YAML.
       # 
-      # This is roughly the same place where Psych checks if +target+ responds to :encode_with.
+      # This is roughly the same place where Psych checks if +target+ responds to +:encode_with+.
       # 
-      # This will check if @emitter is a {StyledTreeBuilder} and if +target+ is a {Blueberry}.
-      # 1. If the above is true, get the {Styler}(s) and add them to @emitter.
-      # 2. Call super.
-      # 3. If the above is true, remove the {Styler}(s) from @emitter.
-      # 4. Return the result of super.
+      # 1. Check if +@emitter+ is a {StyledTreeBuilder}.
+      # 2. If #1 and +target+ is a {Blueberry}, get the {Styler}(s) from +target+ and add them to +@emitter+.
+      # 3. If #1 and +@emitter.deref_aliases?+, prevent +target+ from becoming an alias.
+      # 4. Call +super+ and store the result.
+      # 5. If #2, remove the {Styler}(s) from +@emitter+.
+      # 6. Return the result of +super+.
       # 
       # @param target [Object] the Object to pass to super
       # 
@@ -64,6 +65,7 @@ module Psychgus
       # 
       # @see Psych::Visitors::YAMLTree
       # @see Blueberry
+      # @see Blueberry#psychgus_stylers
       # @see Styler
       # @see StyledTreeBuilder
       def accept(target)

data/lib/psychgus/stylables.rb

@@ -0,0 +1,273 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+
+#--
+# This file is part of Psychgus.
+# Copyright (c) 2019 Jonathan Bradley Whited (@esotericpig)
+# 
+# Psychgus is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+# 
+# Psychgus is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+# 
+# You should have received a copy of the GNU Lesser General Public License
+# along with Psychgus.  If not, see <http://www.gnu.org/licenses/>.
+#++
+
+
+require 'psychgus/styler'
+require 'psychgus/super_sniffer'
+
+require 'stringio'
+
+module Psychgus
+  ###
+  # A collection of commonly-used {Styler} mixins
+  # that can be included in a class instead of {Styler}.
+  # 
+  # @author Jonathan Bradley Whited (@esotericpig)
+  # @since  1.2.0
+  # 
+  # @see Stylers
+  # @see Styler
+  ###
+  module Stylables
+    ###
+    # A helper mixin for Stylables that change a node's style.
+    # 
+    # There is no max level, because a parent's style will override all of its children.
+    ###
+    module StyleStylable
+      include Styler
+      
+      attr_accessor :min_level # @return [Integer] the minimum level (inclusive) to style
+      attr_accessor :new_style # @return [Integer] the new style to set the nodes to
+      
+      # +max_level+ is not defined because a parent's style will override all of its children.
+      # 
+      # @param min_level [Integer] the minimum level (inclusive) to style
+      # @param new_style [Integer] the new style to set the nodes to
+      # @param kargs [Hash] capture extra keyword args, so no error for undefined args
+      def initialize(min_level=0,new_style: nil,**kargs)
+        @min_level = min_level
+        @new_style = new_style
+      end
+      
+      # Change the style of +node+ to {new_style} if it is >= {min_level}.
+      def change_style(sniffer,node)
+        return unless node.respond_to?(:style=)
+        
+        node.style = @new_style if sniffer.level >= @min_level
+      end
+    end
+  end
+  
+  module Stylables
+    ###
+    # (see Stylers::CapStyler)
+    ###
+    module CapStylable
+      include Styler
+      
+      attr_reader :delim # @return [String,Regexp] the delimiter to split on
+      attr_accessor :each_word # @return [true,false] whether to capitalize each word separated by {delim}
+      attr_accessor :new_delim # @return [nil,String] the replacement for each {delim} if not nil
+      
+      # @param each_word [true,false] whether to capitalize each word separated by +delim+
+      # @param new_delim [nil,String] the replacement for each +delim+ if not nil
+      # @param delim [String,Regexp] the delimiter to split on
+      # @param kargs [Hash] capture extra keyword args, so no error for undefined args
+      def initialize(each_word: true,new_delim: nil,delim: /[\s_\-]/,**kargs)
+        delim = Regexp.quote(delim.to_s()) unless delim.is_a?(Regexp)
+        
+        @delim = Regexp.new("(#{delim.to_s()})")
+        @each_word = each_word
+        @new_delim = new_delim
+      end
+      
+      # Capitalize an individual word (not words).
+      # 
+      # This method can safely be overridden with a new implementation.
+      # 
+      # @param word [nil,String] the word to capitalize
+      # 
+      # @return [String] the capitalized word
+      def cap_word(word)
+        return word if word.nil?() || word.empty?()
+        
+        # Already capitalized, good for all-capitalized words, like 'BBQ'
+        return word if word[0] == word[0].upcase()
+        
+        return word.capitalize()
+      end
+      
+      # Capitalize +node.value+.
+      # 
+      # @see cap_word
+      # @see Styler#style_scalar
+      def style_scalar(sniffer,node)
+        if !@each_word || node.value.nil?() || node.value.empty?()
+          node.value = cap_word(node.value)
+          return
+        end
+        
+        is_delim = false
+        
+        node.value = node.value.split(@delim).map() do |v|
+          if is_delim
+            v = @new_delim unless @new_delim.nil?()
+          else
+            v = cap_word(v)
+          end
+          
+          is_delim = !is_delim
+          v
+        end.join()
+      end
+    end
+    
+    ###
+    # (see Stylers::HierarchyStyler)
+    ###
+    module HierarchyStylable
+      include Styler
+      
+      attr_accessor :io # @return [IO] the IO to write to; defaults to StringIO
+      attr_accessor :verbose # @return [true,false] whether to be more verbose (e.g., write child info)
+      
+      # @param io [IO] the IO to write to
+      # @param verbose [true,false] whether to be more verbose (e.g., write child info)
+      # @param kargs [Hash] capture extra keyword args, so no error for undefined args
+      def initialize(io: StringIO.new(),verbose: false,**kargs)
+        @io = io
+        @verbose = verbose
+      end
+      
+      # Write the hierarchy of +node+ to {io}.
+      # 
+      # @see Styler#style
+      def style(sniffer,node)
+        @io.print (' ' * (sniffer.level - 1))
+        
+        name = node.respond_to?(:value) ? node.value : node.class.name
+        parent = sniffer.parent
+        
+        @io.print "(#{sniffer.level}:#{sniffer.position}):#{name} - "
+        
+        if @verbose
+          @io.print parent
+        else
+          @io.print "<#{parent.debug_tag}:(#{parent.level}:#{parent.position})>"
+        end
+        
+        @io.puts
+      end
+      
+      # Convert {io} to a String if possible (e.g., StringIO).
+      # 
+      # @return [String] the IO String result or just {io} as a String
+      def to_s()
+        return @io.respond_to?(:string) ? @io.string : @io.to_s()
+      end
+    end
+    
+    ###
+    # (see Stylers::MapFlowStyler)
+    ###
+    module MapFlowStylable
+      include StyleStylable
+      
+      # (see StyleStylable#initialize)
+      # @!method initialize(min_level=0,new_style: nil,**kargs)
+      # 
+      # If +new_style+ is nil (the default), then {MAPPING_FLOW} will be used.
+      def initialize(*)
+        super
+        
+        @new_style = MAPPING_FLOW if @new_style.nil?()
+      end
+      
+      # Change the style of a Mapping to FLOW (or to the value of {new_style})
+      # if it is >= {min_level}.
+      # 
+      # @see change_style
+      # @see Styler#style_mapping
+      def style_mapping(sniffer,node)
+        change_style(sniffer,node)
+      end
+    end
+    
+    ###
+    # (see Stylers::NoSymStyler)
+    ###
+    module NoSymStylable
+      include Styler
+      
+      attr_accessor :cap # @return [true,false] whether to capitalize the symbol
+      
+      alias_method :cap?,:cap
+      
+      # @param cap [true,false] whether to capitalize the symbol
+      # @param kargs [Hash] capture extra keyword args, so no error for undefined args
+      def initialize(cap: true,**kargs)
+        @cap = cap
+      end
+      
+      # If +node.value+ is a symbol, change it into a string and capitalize it.
+      # 
+      # @see Styler#style_scalar
+      def style_scalar(sniffer,node)
+        return if node.value.nil?() || node.value.empty?()
+        return if node.value[0] != ':'
+        
+        node.value = node.value[1..-1]
+        node.value = node.value.capitalize() if @cap
+      end
+    end
+    
+    ###
+    # (see Stylers::NoTagStyler)
+    ###
+    module NoTagStylable
+      include Styler
+      
+      # If +node.tag+ is settable, set it to nil.
+      # 
+      # @see Styler#style
+      def style(sniffer,node)
+        node.tag = nil if node.respond_to?(:tag=)
+      end
+    end
+    
+    ###
+    # (see Stylers::SeqFlowStyler)
+    ###
+    module SeqFlowStylable
+      include StyleStylable
+      
+      # (see StyleStylable#initialize)
+      # @!method initialize(min_level=0,new_style: nil,**kargs)
+      # 
+      # If +new_style+ is nil (the default), then {SEQUENCE_FLOW} will be used.
+      def initialize(*)
+        super
+        
+        @new_style = SEQUENCE_FLOW if @new_style.nil?()
+      end
+      
+      # Change the style of a Sequence to FLOW (or to the value of {new_style})
+      # if it is >= {min_level}.
+      # 
+      # @see change_style
+      # @see Styler#style_sequence
+      def style_sequence(sniffer,node)
+        change_style(sniffer,node)
+      end
+    end
+  end
+end

data/lib/psychgus/stylers.rb

@@ -0,0 +1,308 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+
+#--
+# This file is part of Psychgus.
+# Copyright (c) 2019 Jonathan Bradley Whited (@esotericpig)
+# 
+# Psychgus is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+# 
+# Psychgus is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+# 
+# You should have received a copy of the GNU Lesser General Public License
+# along with Psychgus.  If not, see <http://www.gnu.org/licenses/>.
+#++
+
+
+require 'psychgus/stylables'
+
+module Psychgus
+  ###
+  # A collection of commonly-used {Styler} classes.
+  # 
+  # @example
+  #   require 'psychgus'
+  #   
+  #   class EggCarton
+  #     def initialize
+  #       @eggs = {
+  #         :styles => ['fried', 'scrambled', ['BBQ', 'ketchup & mustard']],
+  #         :colors => ['brown', 'white', ['blue', 'green']]
+  #       }
+  #     end
+  #   end
+  #   
+  #   hierarchy = Psychgus::HierarchyStyler.new(io: $stdout)
+  #   
+  #   puts EggCarton.new.to_yaml(stylers: [
+  #     Psychgus::NoSymStyler.new,
+  #     Psychgus::NoTagStyler.new,
+  #     Psychgus::CapStyler.new,
+  #     Psychgus::FlowStyler.new(4),
+  #     hierarchy
+  #   ])
+  #   
+  #   # Output:
+  #   # ---
+  #   # Eggs:
+  #   #   Styles: [Fried, Scrambled, [BBQ, Ketchup & Mustard]]
+  #   #   Colors: [Brown, White, [Blue, Green]]
+  #   
+  #   # (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):Eggs - <map:(1:1)>
+  #   #   (3:1):Psych::Nodes::Mapping - <Eggs:(2:1)>
+  #   #    (4:1):Styles - <map:(3:1)>
+  #   #     (5:1):Psych::Nodes::Sequence - <Styles:(4:1)>
+  #   #      (6:1):Fried - <seq:(5:1)>
+  #   #      (6:2):Scrambled - <seq:(5:1)>
+  #   #      (6:3):Psych::Nodes::Sequence - <seq:(5:1)>
+  #   #       (7:1):BBQ - <seq:(6:3)>
+  #   #       (7:2):Ketchup & Mustard - <seq:(6:3)>
+  #   #    (4:2):Colors - <map:(3:1)>
+  #   #     (5:1):Psych::Nodes::Sequence - <Colors:(4:2)>
+  #   #      (6:1):Brown - <seq:(5:1)>
+  #   #      (6:2):White - <seq:(5:1)>
+  #   #      (6:3):Psych::Nodes::Sequence - <seq:(5:1)>
+  #   #       (7:1):Blue - <seq:(6:3)>
+  #   #       (7:2):Green - <seq:(6:3)>
+  # 
+  # @author Jonathan Bradley Whited (@esotericpig)
+  # @since  1.2.0
+  # 
+  # @see Stylables
+  # @see Styler
+  ###
+  module Stylers
+    ###
+    # A Capitalizer for Scalars.
+    # 
+    # @example
+    #   require 'psychgus'
+    #   
+    #   data = {
+    #     'eggs' => [
+    #       'omelette',
+    #       'BBQ eggs',
+    #       'hard-boiled eggs',
+    #       'soft_boiled eggs',
+    #       'fried@eggs'
+    #   ]}
+    #   
+    #   seq_flow = Psychgus::SeqFlowStyler.new
+    #   
+    #   puts data.to_yaml(stylers: [Psychgus::CapStyler.new,seq_flow])
+    #   
+    #   # Output:
+    #   # ---
+    #   # Eggs: [Omelette, BBQ Eggs, Hard-Boiled Eggs, Soft_Boiled Eggs, Fried@eggs]
+    #   
+    #   puts data.to_yaml(stylers: [Psychgus::CapStyler.new(each_word: false),seq_flow])
+    #   
+    #   # Output:
+    #   # ---
+    #   # Eggs: [Omelette, BBQ eggs, Hard-boiled eggs, Soft_boiled eggs, Fried@eggs]
+    #   
+    #   puts data.to_yaml(stylers: [Psychgus::CapStyler.new(new_delim: '(o)'),seq_flow])
+    #   
+    #   # Output:
+    #   # ---
+    #   # Eggs: [Omelette, BBQ(o)Eggs, Hard(o)Boiled(o)Eggs, Soft(o)Boiled(o)Eggs, Fried@eggs]
+    #   
+    #   class Cappie
+    #     include Psychgus::CapStylable
+    #     
+    #     def cap_word(word)
+    #       return 'bbq' if word.casecmp('BBQ') == 0
+    #       
+    #       super(word)
+    #     end
+    #   end
+    #   
+    #   puts data.to_yaml(stylers: [Cappie.new(new_delim: '*',delim: /[\s@]/),seq_flow])
+    #   
+    #   # Output:
+    #   # ---
+    #   # Eggs: [Omelette, bbq*Eggs, Hard-boiled*Eggs, Soft_boiled*Eggs, Fried*Eggs]
+    # 
+    # @see Stylables::CapStylable
+    ###
+    class CapStyler
+      include Stylables::CapStylable
+    end
+    
+    ###
+    # A FLOW style changer for Mappings & Sequences.
+    # 
+    # @example
+    #   require 'psychgus'
+    #   
+    #   data = {
+    #     'Eggs' => {
+    #       'Styles' => ['Fried', 'Scrambled', ['BBQ', 'Ketchup']],
+    #       'Colors' => ['Brown', 'White', ['Blue', 'Green']]
+    #   }}
+    #   
+    #   puts data.to_yaml(stylers: Psychgus::FlowStyler.new)
+    #   
+    #   # Output:
+    #   # --- {Eggs: {Styles: [Fried, Scrambled, [BBQ, Ketchup]], Colors: [Brown, White, [Blue, Green]]}}
+    #   
+    #   # >= level 4 (see Psychgus.hierarchy)
+    #   puts data.to_yaml(stylers: Psychgus::FlowStyler.new(4))
+    #   
+    #   # Output:
+    #   # ---
+    #   # Eggs:
+    #   #   Styles: [Fried, Scrambled, [BBQ, Ketchup]]
+    #   #   Colors: [Brown, White, [Blue, Green]]
+    #   
+    #   # >= level 6 (see Psychgus.hierarchy)
+    #   puts data.to_yaml(stylers: Psychgus::FlowStyler.new(6))
+    #   
+    #   # Output:
+    #   # ---
+    #   # Eggs:
+    #   #   Styles:
+    #   #   - Fried
+    #   #   - Scrambled
+    #   #   - [BBQ, Ketchup]
+    #   #   Colors:
+    #   #   - Brown
+    #   #   - White
+    #   #   - [Blue, Green]
+    # 
+    # @see Stylables::MapFlowStylable
+    # @see Stylables::SeqFlowStylable
+    ###
+    class FlowStyler
+      include Stylables::MapFlowStylable
+      include Stylables::SeqFlowStylable
+    end
+    
+    ###
+    # A visual hierarchy writer of the levels.
+    # 
+    # This is useful for determining the correct level/position when writing a {Styler}.
+    # 
+    # The default IO is StringIO, but can specify a different one.
+    # 
+    # See {Psychgus.hierarchy} for more details.
+    # 
+    # @see Psychgus.hierarchy
+    # @see Stylables::HierarchyStylable
+    ###
+    class HierarchyStyler
+      include Stylables::HierarchyStylable
+    end
+    
+    ###
+    # A FLOW style changer for Mappings only.
+    # 
+    # @see FlowStyler
+    # @see Stylables::MapFlowStylable
+    ###
+    class MapFlowStyler
+      include Stylables::MapFlowStylable
+    end
+    
+    ###
+    # A Symbol remover for Scalars.
+    # 
+    # @example
+    #   require 'psychgus'
+    #   
+    #   data = {
+    #     :eggs => {
+    #       :styles => ['Fried', 'Scrambled', ['BBQ', 'Ketchup']],
+    #       :colors => ['Brown', 'White', ['Blue', 'Green']]
+    #   }}
+    #   
+    #   flow = Psychgus::FlowStyler.new(4)
+    #   
+    #   puts data.to_yaml(stylers: [Psychgus::NoSymStyler.new,flow])
+    #   
+    #   # Output:
+    #   # ---
+    #   # Eggs:
+    #   #   Styles: [Fried, Scrambled, [BBQ, Ketchup]]
+    #   #   Colors: [Brown, White, [Blue, Green]]
+    #   
+    #   puts data.to_yaml(stylers: [Psychgus::NoSymStyler.new(cap: false),flow])
+    #   
+    #   # ---
+    #   # eggs:
+    #   #   styles: [Fried, Scrambled, [BBQ, Ketchup]]
+    #   #   colors: [Brown, White, [Blue, Green]]
+    # 
+    # @see Stylables::NoSymStylable
+    ###
+    class NoSymStyler
+      include Stylables::NoSymStylable
+    end
+    
+    ###
+    # A Tag remover for classes.
+    # 
+    # @example
+    #   require 'psychgus'
+    #   
+    #   class Eggs
+    #     def initialize
+    #       @styles = ['Fried', 'Scrambled', ['BBQ', 'Ketchup']]
+    #       @colors = ['Brown', 'White', ['Blue', 'Green']]
+    #     end
+    #   end
+    #   
+    #   class EggCarton
+    #     include Psychgus::Blueberry
+    #     
+    #     def initialize
+    #       @eggs = Eggs.new
+    #     end
+    #     
+    #     def psychgus_stylers(sniffer)
+    #       Psychgus::FlowStyler.new(4)
+    #     end
+    #   end
+    #   
+    #   puts EggCarton.new.to_yaml
+    #   
+    #   # Output:
+    #   # --- !ruby/object:EggCarton
+    #   # eggs: !ruby/object:Eggs
+    #   #   styles: [Fried, Scrambled, [BBQ, Ketchup]]
+    #   #   colors: [Brown, White, [Blue, Green]]
+    #   
+    #   puts EggCarton.new.to_yaml(stylers: Psychgus::NoTagStyler.new)
+    #   
+    #   # Output:
+    #   # ---
+    #   # eggs:
+    #   #   styles: [Fried, Scrambled, [BBQ, Ketchup]]
+    #   #   colors: [Brown, White, [Blue, Green]]
+    # 
+    # @see Stylables::NoTagStylable
+    ###
+    class NoTagStyler
+      include Stylables::NoTagStylable
+    end
+    
+    ###
+    # A FLOW style changer for Sequences only.
+    # 
+    # @see FlowStyler
+    # @see Stylables::SeqFlowStylable
+    ###
+    class SeqFlowStyler
+      include Stylables::SeqFlowStylable
+    end
+  end
+end