psychgus 1.0.0

data/lib/psychgus/styled_tree_builder.rb

@@ -0,0 +1,294 @@
+#!/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 'psych'
+
+require 'psychgus/styler'
+require 'psychgus/super_sniffer'
+
+module Psychgus
+  ###
+  # Use this wherever Psych::TreeBuilder would have been used, to enable styling.
+  # 
+  # @author Jonathan Bradley Whited (@esotericpig)
+  # @since  1.0.0
+  # 
+  # @see Psychgus.parser Psychgus.parser
+  # @see Psychgus.dump_stream Psychgus.dump_stream
+  # @see Psych::TreeBuilder
+  ###
+  class StyledTreeBuilder < Psych::TreeBuilder
+    # @return [true,false] whether to dereference aliases; output the actual value instead of the alias
+    attr_accessor :deref_aliases
+    alias_method :deref_aliases?,:deref_aliases
+    
+    # @return [SuperSniffer] the {SuperSniffer} being used to sniff the YAML nodes, level, etc.
+    attr_reader :sniffer
+    
+    # @return [Array<Stylers>] the {Styler}(s) being used to style the YAML nodes
+    attr_reader :stylers
+    
+    # Initialize this class with {Styler}(s).
+    # 
+    # @param stylers [Styler] {Styler}(s) to use for styling this TreeBuilder
+    # @param deref_aliases [true,false] whether to dereference aliases; output the actual value
+    #                                   instead of the alias
+    def initialize(*stylers,deref_aliases: false,**options)
+      super()
+      
+      @deref_aliases = deref_aliases
+      @sniffer = SuperSniffer.new()
+      @stylers = []
+      
+      add_styler(*stylers)
+    end
+    
+    # Add {Styler}(s) onto the end of the data structure.
+    # 
+    # @param stylers [Styler] {Styler}(s) to add
+    # 
+    # @return [self] this class
+    def add_styler(*stylers)
+      @stylers.push(*stylers)
+      
+      return self
+    end
+    
+    # Calls super, styler(s), and sniffer.
+    # 
+    # @see Psych::TreeBuilder#alias
+    # @see Styler#style
+    # @see Styler#style_alias
+    # @see SuperSniffer#add_alias
+    # 
+    # @return [Psych::Nodes::Alias] the alias node created
+    def alias(*)
+      node = super
+      
+      @stylers.each do |styler|
+        styler.style(sniffer,node)
+        styler.style_alias(sniffer,node)
+      end
+      
+      @sniffer.add_alias(node)
+      
+      return node
+    end
+    
+    # Calls super and sniffer.
+    # 
+    # @see Psych::TreeBuilder#end_document
+    # @see SuperSniffer#end_document
+    def end_document(*)
+      result = super
+      
+      @sniffer.end_document()
+      
+      return result
+    end
+    
+    # Calls super and sniffer.
+    # 
+    # @see Psych::TreeBuilder#end_mapping
+    # @see SuperSniffer#end_mapping
+    def end_mapping(*)
+      result = super
+      
+      @sniffer.end_mapping()
+      
+      return result
+    end
+    
+    # Calls super and sniffer.
+    # 
+    # @see Psych::TreeBuilder#end_sequence
+    # @see SuperSniffer#end_sequence
+    def end_sequence(*)
+      result = super
+      
+      @sniffer.end_sequence()
+      
+      return result
+    end
+    
+    # Calls super and sniffer.
+    # 
+    # @see Psych::TreeBuilder#end_stream
+    # @see SuperSniffer#end_stream
+    def end_stream(*)
+      result = super
+      
+      @sniffer.end_stream()
+      
+      return result
+    end
+    
+    # Insert {Styler}(s) at +index+ into the data structure.
+    # 
+    # @param stylers [Styler] {Styler}(s) to insert
+    # 
+    # @return [self] this class
+    def insert_styler(index,*stylers)
+      @stylers.insert(index,*stylers)
+      
+      return self
+    end
+    
+    # Remove the last {Styler}(s) from the data structure.
+    # 
+    # @param count [Integer] the optional amount of tail elements to pop
+    # 
+    # @return [Styler,Array<Styler>,nil] the last {Styler}(s), or if empty or count==0, nil
+    def pop_styler(count=1)
+      return nil if count == 0
+      return @stylers.pop() if count == 1
+      
+      return @stylers.pop(count)
+    end
+    
+    # Remove the {Styler} that matches +styler+ from the data structure.
+    # 
+    # An optional +block+ can return a default value if not found.
+    # 
+    # @param styler [Styler] the {Styler} to find and remove
+    # @param block [Proc] an optional block to call when +styler+ is not found
+    # 
+    # @return [Styler,nil] the last {Styler}, or if not found, nil or the result of +block+
+    def remove_styler(styler,&block)
+      return @stylers.delete(styler,&block)
+    end
+    
+    # Remove the {Styler} at +index+ from the data structure.
+    # 
+    # @param index [Integer] the index of the {Styler} to remove
+    # 
+    # @return [Styler,nil] the {Styler} removed or nil if empty
+    def remove_styler_at(index)
+      return @stylers.delete_at(index)
+    end
+    
+    # Calls super, styler(s), and sniffer.
+    # 
+    # @see Psych::TreeBuilder#scalar
+    # @see Styler#style
+    # @see Styler#style_scalar
+    # @see SuperSniffer#add_scalar
+    # 
+    # @return [Psych::Nodes::Scalar] the scalar node created
+    def scalar(*)
+      node = super
+      
+      @stylers.each do |styler|
+        styler.style(sniffer,node)
+        styler.style_scalar(sniffer,node)
+      end
+      
+      @sniffer.add_scalar(node)
+      
+      return node
+    end
+    
+    # Calls super, styler(s), and sniffer.
+    # 
+    # @see Psych::TreeBuilder#start_document
+    # @see Styler#style
+    # @see Styler#style_document
+    # @see SuperSniffer#start_document
+    # 
+    # @return [Psych::Nodes::Document] the document node created
+    def start_document(*)
+      node = super
+      
+      @stylers.each do |styler|
+        styler.style(sniffer,node)
+        styler.style_document(sniffer,node)
+      end
+      
+      @sniffer.start_document(node)
+      
+      return node
+    end
+    
+    # Calls super, styler(s), and sniffer.
+    # 
+    # @see Psych::TreeBuilder#start_mapping
+    # @see Styler#style
+    # @see Styler#style_mapping
+    # @see SuperSniffer#start_mapping
+    # 
+    # @return [Psych::Nodes::Mapping] the mapping node created
+    def start_mapping(*)
+      node = super
+      
+      @stylers.each do |styler|
+        styler.style(sniffer,node)
+        styler.style_mapping(sniffer,node)
+      end
+      
+      @sniffer.start_mapping(node)
+      
+      return node
+    end
+    
+    # Calls super, styler(s), and sniffer.
+    # 
+    # @see Psych::TreeBuilder#start_sequence
+    # @see Styler#style
+    # @see Styler#style_sequence
+    # @see SuperSniffer#start_sequence
+    # 
+    # @return [Psych::Nodes::Sequence] the sequence node created
+    def start_sequence(*)
+      node = super
+      
+      @stylers.each do |styler|
+        styler.style(sniffer,node)
+        styler.style_sequence(sniffer,node)
+      end
+      
+      @sniffer.start_sequence(node)
+      
+      return node
+    end
+    
+    # Calls super, styler(s), and sniffer.
+    # 
+    # @see Psych::TreeBuilder#start_stream
+    # @see Styler#style
+    # @see Styler#style_stream
+    # @see SuperSniffer#start_stream
+    # 
+    # @return [Psych::Nodes::Stream] the stream node created
+    def start_stream(*)
+      node = super
+      
+      @stylers.each do |styler|
+        styler.style(sniffer,node)
+        styler.style_stream(sniffer,node)
+      end
+      
+      @sniffer.start_stream(node)
+      
+      return node
+    end
+  end
+end

data/lib/psychgus/styler.rb

@@ -0,0 +1,127 @@
+#!/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/super_sniffer'
+
+module Psychgus
+  module Styler
+    ###
+    # An empty {Styler} as a class.
+    # 
+    # @author Jonathan Bradley Whited (@esotericpig)
+    # @since  1.0.0
+    ###
+    class Empty
+      include Styler
+    end
+  end
+  
+  ###
+  # Mix in (include) this module to make a class/module/etc. a styler for YAML.
+  # 
+  # Although it's unnecessary (because of Duck Typing), it's the recommended practice in case a new method is
+  # added in the future, and also so you don't have to define methods that you don't use.
+  # 
+  # You can either use this as is (see example) or inside of a class (see {Blueberry}).
+  # 
+  # @example
+  #   class MyStyler
+  #     include Psychgus::Styler
+  #     
+  #     def style_sequence(sniffer,node)
+  #       node.style = Psychgus::SEQUENCE_FLOW if sniffer.level == 3
+  #     end
+  #   end
+  #   
+  #   hash = {'Coffee'=>{
+  #             'Roast'=>['Light','Medium','Dark','Extra Dark'],
+  #             'Style'=>['Cappuccino','Espresso','Latte','Mocha']
+  #          }}
+  #   puts hash.to_yaml(stylers: MyStyler.new())
+  #   
+  #   # Output:
+  #   # ---
+  #   # Coffee:
+  #   #   Roast: [Light, Medium, Dark, Extra Dark]
+  #   #   Style: [Cappuccino, Espresso, Latte, Mocha]
+  # 
+  # @author Jonathan Bradley Whited (@esotericpig)
+  # @since  1.0.0
+  # 
+  # @see Psychgus
+  # @see Ext::ObjectExt#to_yaml
+  # @see Blueberry
+  # @see StyledTreeBuilder#initialize
+  # @see StyledDocumentStream#initialize
+  # @see Ext::YAMLTreeExt#accept
+  ###
+  module Styler
+    EMPTY = Empty.new().freeze()
+    
+    # Style a node of any type.
+    # 
+    # You can use {Ext::NodeExt#node_of?} to determine its type:
+    #   puts node.value if node.node_of?(:scalar)
+    # 
+    # @param sniffer [SuperSniffer] passed in from {StyledTreeBuilder}
+    # @param node [Psych::Nodes::Node] passed in from {StyledTreeBuilder}
+    # 
+    # @see Ext::NodeExt#node_of?
+    def style(sniffer,node) end
+    
+    # Style a node guaranteed to be of type Psych::Nodes::Alias, to avoid if statements.
+    # 
+    # @param sniffer [SuperSniffer] passed in from {StyledTreeBuilder}
+    # @param node [Psych::Nodes::Alias] of type Alias passed in from {StyledTreeBuilder}
+    def style_alias(sniffer,node) end
+    
+    # Style a node guaranteed to be of type Psych::Nodes::Document, to avoid if statements.
+    # 
+    # @param sniffer [SuperSniffer] passed in from {StyledTreeBuilder}
+    # @param node [Psych::Nodes::Document] of type Document passed in from {StyledTreeBuilder}
+    def style_document(sniffer,node) end
+    
+    # Style a node guaranteed to be of type Psych::Nodes::Mapping, to avoid if statements.
+    # 
+    # @param sniffer [SuperSniffer] passed in from {StyledTreeBuilder}
+    # @param node [Psych::Nodes::Mapping] of type Mapping passed in from {StyledTreeBuilder}
+    def style_mapping(sniffer,node) end
+    
+    # Style a node guaranteed to be of type Psych::Nodes::Scalar, to avoid if statements.
+    # 
+    # @param sniffer [SuperSniffer] passed in from {StyledTreeBuilder}
+    # @param node [Psych::Nodes::Scalar] of type Scalar passed in from {StyledTreeBuilder}
+    def style_scalar(sniffer,node) end
+    
+    # Style a node guaranteed to be of type Psych::Nodes::Sequence, to avoid if statements.
+    # 
+    # @param sniffer [SuperSniffer] passed in from {StyledTreeBuilder}
+    # @param node [Psych::Nodes::Sequence] of type Sequence passed in from {StyledTreeBuilder}
+    def style_sequence(sniffer,node) end
+    
+    # Style a node guaranteed to be of type Psych::Nodes::Stream, to avoid if statements.
+    # 
+    # @param sniffer [SuperSniffer] passed in from {StyledTreeBuilder}
+    # @param node [Psych::Nodes::Stream] of type Stream passed in from {StyledTreeBuilder}
+    def style_stream(sniffer,node) end
+  end
+end

data/lib/psychgus/super_sniffer/parent.rb

@@ -0,0 +1,218 @@
+#!/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/>.
+#++
+
+
+module Psychgus
+  class SuperSniffer
+    ###
+    # A container for the parent of a Psych::Nodes::Node.
+    # 
+    # A parent is a Mapping, Sequence, or a Key (Scalar) of a Mapping.
+    # 
+    # You can use the getters in this class in {Styler} to filter what to change.
+    # 
+    # If a Node method has not been exposed, you can use {#node}:
+    #   if parent.node_of?(:scalar)
+    #     parent.value = 'FUBAR'
+    #     parent.node.value = 'FUBAR' # Same as above
+    #     
+    #     parent.fubar = true      # NoMethodError
+    #     parent.node.fubar = true # Use some new Psych::Nodes::Node method not in this version
+    #                              #   of Psychgus or that is not exposed by Parent
+    #   end
+    # 
+    # @author Jonathan Bradley Whited (@esotericpig)
+    # @since  1.0.0
+    # 
+    # @see SuperSniffer
+    # @see SuperSniffer#start_parent SuperSniffer#start_parent
+    # @see SuperSniffer#end_parent SuperSniffer#end_parent
+    # @see Styler
+    ###
+    class Parent
+      # Calling the getter is fine; calling the setter is *not* and could cause weird results.
+      # 
+      # @return [Integer] the next child's position
+      attr_accessor :child_position
+      
+      # Calling the getter is fine; calling the setter is *not* and could cause weird results.
+      # 
+      # @return [nil,:key,:value] the next child's Mapping type, if {#node} is a Mapping
+      attr_accessor :child_type
+      
+      # @return [:noface,Symbol,String] a tag (class name, value) for debugging; also used in {#to_s}
+      attr_reader :debug_tag
+      
+      attr_reader :level # @return [Integer] the level of this Node in the YAML
+      attr_reader :node # @return [Psych::Nodes::Node] the Node of this parent
+      attr_reader :position # @return [Integer] the position of this Node in the YAML
+      
+      # Initialize this class with parent data.
+      # 
+      # @param sniffer [SuperSniffer] the sniffer that contains this parent (not stored; used for data)
+      # @param node [Psych::Nodes::Node] the node of this parent
+      # @param debug_tag [:noface,Symbol,String] the tag (class name, value) used for debugging and in {#to_s}
+      # @param child_type [nil,:key,:value] the next child's Mapping type, if +node+ is a Mapping
+      def initialize(sniffer,node,debug_tag: nil,child_type: nil)
+        @child_position = 1
+        @child_type = child_type
+        @debug_tag = debug_tag
+        @level = sniffer.level
+        @node = node
+        @position = sniffer.position
+      end
+      
+      # @see Psych::Nodes::Alias#anchor=
+      # @see Psych::Nodes::Mapping#anchor=
+      # @see Psych::Nodes::Scalar#anchor=
+      # @see Psych::Nodes::Sequence#anchor=
+      def anchor=(anchor)
+        node.anchor = anchor
+      end
+      
+      # @see Psych::Nodes::Scalar#plain=
+      def plain=(plain)
+        node.plain = plain
+      end
+      
+      # @see Psych::Nodes::Scalar#quoted=
+      def quoted=(quoted)
+        node.quoted = quoted
+      end
+      
+      # @see Psych::Nodes::Mapping#style=
+      # @see Psych::Nodes::Scalar#style=
+      # @see Psych::Nodes::Sequence#style=
+      def style=(style)
+        node.style = style
+      end
+      
+      # @see Psych::Nodes::Node#tag=
+      def tag=(tag)
+        node.tag = tag
+      end
+      
+      # @see Psych::Nodes::Scalar#value=
+      def value=(value)
+        node.value = value
+      end
+      
+      # @see Psych::Nodes::Alias#anchor
+      # @see Psych::Nodes::Mapping#anchor
+      # @see Psych::Nodes::Scalar#anchor
+      # @see Psych::Nodes::Sequence#anchor
+      def anchor()
+        return node.anchor
+      end
+      
+      # @see Psych::Nodes::Stream#encoding
+      def encoding()
+        return node.encoding
+      end
+      
+      # @see Psych::Nodes::Node#end_column
+      def end_column()
+        return node.end_column
+      end
+      
+      # @see Psych::Nodes::Node#end_line
+      def end_line()
+        return node.end_line
+      end
+      
+      # @see Psych::Nodes::Document#implicit
+      # @see Psych::Nodes::Mapping#implicit
+      # @see Psych::Nodes::Sequence#implicit
+      def implicit?()
+        return node.implicit
+      end
+      
+      # @see Psych::Nodes::Document#implicit_end
+      def implicit_end?()
+        return node.implicit_end
+      end
+      
+      # (see Ext::NodeExt#node_of?)
+      def node_of?(*names)
+        return node.node_of?(*names)
+      end
+      
+      # @see Psych::Nodes::Scalar#plain
+      def plain?()
+        return node.plain
+      end
+      
+      # @see Psych::Nodes::Scalar#quoted
+      def quoted?()
+        return node.quoted
+      end
+      
+      # @see Psych::Nodes::Node#start_column
+      def start_column()
+        return node.start_column
+      end
+      
+      # @see Psych::Nodes::Node#start_line
+      def start_line()
+        return node.start_line
+      end
+      
+      # @see Psych::Nodes::Mapping#style
+      # @see Psych::Nodes::Scalar#style
+      # @see Psych::Nodes::Sequence#style
+      def style()
+        return node.style
+      end
+      
+      # @see Psych::Nodes::Node#tag
+      def tag()
+        return node.tag
+      end
+      
+      # @see Psych::Nodes::Document#tag_directives
+      def tag_directives()
+        return node.tag_directives
+      end
+      
+      # @see Psych::Nodes::Scalar#value
+      def value()
+        return node.value
+      end
+      
+      # @see Psych::Nodes::Document#version
+      def version()
+        return node.version
+      end
+      
+      # @note If this method is modified, then tests will fail
+      # 
+      # @return [String] a String representation of this class for debugging and testing
+      def to_s()
+        return "<#{@debug_tag}:(#{@level}:#{@position}):#{@child_type}:(:#{@child_position})>"
+      end
+      
+      alias_method :implicit,:implicit?
+      alias_method :implicit_end,:implicit_end?
+      alias_method :plain,:plain?
+      alias_method :quoted,:quoted?
+    end
+  end
+end