psychgus 1.0.0

data/Rakefile

@@ -0,0 +1,158 @@
+# 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 'bundler/gem_tasks'
+
+require 'yard'
+
+require 'psychgus/version'
+
+require 'rake/clean'
+require 'rake/testtask'
+
+task default: [:test]
+
+CLEAN.exclude('.git/','stock/')
+CLOBBER.include('doc/')
+
+module PsychgusRake
+  # Remove if exists
+  def self.rm_exist(filename,output=true)
+    if File.exist?(filename)
+      puts "Delete [#{filename}]" if output
+      File.delete(filename)
+    end
+  end
+end
+
+# Execute "rake ghp_doc" for a dry run
+# Execute "rake ghp_doc[true]" for actually deploying
+desc %q(Rsync "doc/" to my GitHub Page's repo; not useful for others)
+task :ghp_doc,[:deploy] do |task,args|
+  dry_run = args.deploy ? '' : '--dry-run'
+  rsync_cmd = "rsync -ahv --delete-after --progress #{dry_run} 'doc/' '../esotericpig.github.io/docs/psychgus/yardoc/'"
+  
+  sh rsync_cmd
+  
+  if dry_run
+    puts
+    puts 'Execute "rake ghp_doc[true]" for actually deploying (non-dry-run)'
+  end
+end
+
+Rake::TestTask.new() do |task|
+  task.libs = ['lib','test']
+  task.pattern = 'test/**/*_test.rb'
+  task.description += " ('#{task.pattern}')"
+  #task.options = '--verbose' # Execute "rake test TESTOPT=-v" instead
+  task.verbose = true
+  task.warning = true
+end
+
+desc 'Run all tests (including writing to temp files, etc.)'
+task :test_all do |task|
+  ENV['PSYCHGUS_TEST'] = 'all'
+  
+  test_task = Rake::Task[:test]
+  test_task.reenable()
+  test_task.invoke()
+end
+
+# Execute "rake clobber yard" for pristine docs
+YARD::Rake::YardocTask.new() do |task|
+  task.files = ['lib/**/*.rb']
+  
+  task.options += ['--files','LICENSE.txt']
+  task.options += ['--readme','README.md']
+  
+  task.options << '--protected' # Show protected methods
+  task.options += ['--template-path','yard/templates/']
+  task.options += ['--title',"Psychgus v#{Psychgus::VERSION} Doc"]
+end
+
+desc 'Fix (find & replace) text in the YARD files for GitHub differences'
+task :yard_fix,[:dev] do |task,args|
+  # Delete this file as it's never used (index.html is an exact copy)
+  PsychgusRake.rm_exist('doc/file.README.html')
+  
+  ['doc/index.html'].each do |filename|
+    puts "File [#{filename}]:"
+    
+    lines = []
+    write = false
+    
+    File.open(filename,'r') do |file|
+      file.each_line do |line|
+        out = false
+        
+        # CSS
+        if line =~ /^\s*\<\/head\>\s*$/i
+          line = '<link href="'
+          line << (args.dev ? '../../esotericpig.github.io/' : '../../../')
+          line << 'css/prism.css" rel="stylesheet" /> </head>'
+          
+          out = true
+        end
+        
+        # JS
+        if line =~ /^\s*\<\/body\>\s*$/i
+          line = '<script src="'
+          line << (args.dev ? '../../esotericpig.github.io/' : '../../../')
+          line << 'js/prism.js"></script> </body>'
+          
+          out = true
+        end
+        
+        # Contents relative 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]}"
+          
+          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?()
+        
+        if out
+          puts "  #{line}"
+          write = true
+        end
+        
+        lines << line
+      end
+    end
+    
+    if write
+      File.open(filename,'w') do |file|
+        file.puts lines
+      end
+    end
+  end
+end
+
+desc 'Generate pristine YARDoc'
+task :yard_fresh => [:clobber,:yard,:yard_fix] do |task|
+end

data/lib/psychgus/blueberry.rb

@@ -0,0 +1,110 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+
+#--
+# This file is part of Psychgus.
+# Copyright (c) 2017-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
+  ###
+  # This is the OOP way to style your classes/modules/etc.
+  # 
+  # Even though it's unnecessary to mix in (include) this module, it's recommended because new methods may be
+  # added in the future, so this pseudo-guarantees your class won't break in a new version.
+  # 
+  # A complete example:
+  #   require 'psychgus'
+  #   
+  #   class MyClass
+  #     include Psychgus::Blueberry
+  #     
+  #     attr_reader :my_hash
+  #     
+  #     def initialize()
+  #       @my_hash = {:key1=>'val1',:key2=>'val2'}
+  #     end
+  #     
+  #     def psychgus_stylers(sniffer)
+  #       return MyClassStyler.new(sniffer)
+  #     end
+  #   end
+  #   
+  #   class MyClassStyler
+  #     include Psychgus::Styler
+  #     
+  #     def initialize(sniffer)
+  #       @level = sniffer.level
+  #     end
+  #     
+  #     def style_mapping(sniffer,node)
+  #       node.style = Psychgus::MAPPING_FLOW
+  #       
+  #       relative_level = sniffer.level - @level
+  #     end
+  #   end
+  #   
+  #   my_class = MyClass.new()
+  #   puts my_class.to_yaml()
+  # 
+  # Alternatively, MyClass could have been the {Blueberry} and the {Styler}, without the need for
+  # MyClassStyler:
+  #   class MyClass
+  #     include Psychgus::Blueberry
+  #     include Psychgus::Styler
+  #     
+  #     # ...
+  #     
+  #     def psychgus_stylers(sniffer)
+  #       @level = sniffer.level # This will be included in the output of to_yaml()
+  #       
+  #       return self
+  #     end
+  #     
+  #     def style_mapping(sniffer,node)
+  #       # ...
+  #     end
+  #   end
+  # 
+  # However, it's best to put the styling logic inside of a separate class (or inner class) away from the main
+  # logic. This also prevents extra helper vars, like @level, from showing up in the output.
+  # 
+  # After your class and its children have been processed, the styler(s) will be removed from the logic for
+  # the next sibling object(s). Therefore, you can safely do class-specific checks on level, etc. without it
+  # affecting the sibling object(s). See {Ext::YAMLTreeExt} and {Ext::YAMLTreeExt#accept} for details.
+  # 
+  # "The Blueberry" is the name of Gus's car from the TV show Psych.
+  # 
+  # @author Jonathan Bradley Whited (@esotericpig)
+  # @since  1.0.0
+  # 
+  # @see Ext::YAMLTreeExt
+  # @see Ext::YAMLTreeExt#accept
+  ###
+  module Blueberry
+    # Duck Type this method to return the {Styler}(s) for your class/module/etc.
+    # 
+    # @param sniffer [SuperSniffer] passed in from {StyledTreeBuilder}; use this for storing the level,
+    #                               position, etc. for styling your instance variables later relative to your
+    #                               class/module/etc.
+    # 
+    # @return [Styler,Array<Styler>,nil] {Styler}(s) for this class/module/etc.
+    def psychgus_stylers(sniffer)
+      return nil
+    end
+  end
+end

data/lib/psychgus/ext/core_ext.rb

@@ -0,0 +1,77 @@
+#!/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
+  module Ext
+    ###
+    # Core extensions to Object.
+    # 
+    # @author Jonathan Bradley Whited (@esotericpig)
+    # @since  1.0.0
+    # 
+    # @see https://github.com/ruby/psych/blob/master/lib/psych/core_ext.rb
+    ###
+    module ObjectExt
+      # Convert an Object to YAML.
+      # 
+      # +options+ can also be a Hash, so can be a drop-in-replacement for Psych.
+      # 
+      # @example
+      #   class MyStyler
+      #     include Psychgus::Styler
+      #     
+      #     def style_sequence(sniffer,node)
+      #       node.style = Psychgus::SEQUENCE_FLOW
+      #     end
+      #   end
+      #   
+      #   my_obj = {
+      #     :Foods => {
+      #       :Fruits  => %w(Apple Banana Blueberry Pear),
+      #       :Veggies => %w(Bean Carrot Celery Pea)
+      #   }}
+      #   
+      #   puts my_obj.to_yaml(indentation: 5,stylers: MyStyler.new)
+      #   
+      #   # Or, pass in a Hash:
+      #   #puts my_obj.to_yaml({:indentation=>5,:stylers=>MyStyler.new})
+      #   
+      #   # Output:
+      #   # ---
+      #   # :Foods:
+      #   #      :Fruits: [Apple, Banana, Blueberry, Pear]
+      #   #      :Veggies: [Bean, Carrot, Celery, Pea]
+      # 
+      # @param options [Hash] the options (or keyword args) to pass to {Psychgus.dump}
+      # 
+      # @return [String] the YAML generated from this Object
+      # 
+      # @see Psychgus.dump
+      def to_yaml(**options)
+        # Do not use Psych.dump() if no Stylers, because a class might be a Blueberry
+        return Psychgus.dump(self,**options)
+      end
+    end
+  end
+end
+
+Object.prepend(Psychgus::Ext::ObjectExt)

data/lib/psychgus/ext/node_ext.rb

@@ -0,0 +1,68 @@
+#!/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'
+
+module Psychgus
+  module Ext
+    ###
+    # Extensions to Psych::Nodes::Node.
+    # 
+    # @author Jonathan Bradley Whited (@esotericpig)
+    # @since  1.0.0
+    ###
+    module NodeExt
+      # Check if this Node is of a certain type (Alias, Mapping, Scalar, Sequence, etc.).
+      # 
+      # New versions of Psych have alias?(), mapping?(), etc., so this is for old versions.
+      # 
+      # This is equivalent to the following (with less typing):
+      #   node.is_a?(Psych::Nodes::Alias)
+      #   node.is_a?(Psych::Nodes::Mapping)
+      #   node.is_a?(Psych::Nodes::Scalar)
+      #   node.is_a?(Psych::Nodes::Sequence)
+      # 
+      # @example
+      #   node.node_of?(:alias)
+      #   node.node_of?(:mapping)
+      #   node.node_of?(:scalar)
+      #   node.node_of?(:sequence)
+      #   node.node_of?(:alias,:mapping,:scalar,:sequence) # OR
+      #   node.node_of?(:doc,:map,:seq) # OR
+      # 
+      # @param names [Symbol,String] the type(s) to check using OR
+      # 
+      # @return [true,false] true if this Node is one of the +names+ type, else false
+      # 
+      # @see Psychgus.node_class
+      def node_of?(*names)
+        names.each do |name|
+          return true if is_a?(Psychgus.node_class(name))
+        end
+        
+        return false
+      end
+    end
+  end
+end
+
+Psych::Nodes::Node.prepend(Psychgus::Ext::NodeExt)

data/lib/psychgus/ext/yaml_tree_ext.rb

@@ -0,0 +1,101 @@
+#!/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/styled_tree_builder'
+
+module Psychgus
+  module Ext
+    ###
+    # Extensions to Psych::Visitors::YAMLTree::Registrar.
+    # 
+    # @author Jonathan Bradley Whited (@esotericpig)
+    # @since  1.0.0
+    ###
+    module RegistrarExt
+      # Remove +target+ from this Registrar to prevent it becoming an alias.
+      # 
+      # @param target [Object] the Object to remove from this Registrar
+      def remove_alias(target)
+        @obj_to_node.delete(target.object_id)
+      end
+    end
+    
+    ###
+    # Extensions to Psych::Visitors::YAMLTree.
+    # 
+    # @author Jonathan Bradley Whited (@esotericpig)
+    # @since  1.0.0
+    ###
+    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 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.
+      # 
+      # @param target [Object] the Object to pass to super
+      # 
+      # @return the result of super
+      # 
+      # @see Psych::Visitors::YAMLTree
+      # @see Blueberry
+      # @see Styler
+      # @see StyledTreeBuilder
+      def accept(target)
+        styler_count = 0
+        
+        if @emitter.is_a?(StyledTreeBuilder)
+          # Blueberry?
+          if target.respond_to?(:psychgus_stylers)
+            stylers = target.psychgus_stylers(@emitter.sniffer)
+            stylers_old_len = @emitter.stylers.length
+            
+            @emitter.add_styler(*stylers)
+            
+            styler_count = @emitter.stylers.length - stylers_old_len
+          end
+          
+          # Dereference aliases?
+          if @emitter.deref_aliases?()
+            @st.remove_alias(target) if target.respond_to?(:object_id) && @st.key?(target)
+          end
+        end
+        
+        result = super(target)
+        
+        # Check styler_count because @emitter may not be a StyledTreeBuilder and target may not be a Blueberry
+        @emitter.pop_styler(styler_count) if styler_count > 0
+        
+        return result
+      end
+    end
+  end
+end
+
+Psych::Visitors::YAMLTree.prepend(Psychgus::Ext::YAMLTreeExt)
+Psych::Visitors::YAMLTree::Registrar.prepend(Psychgus::Ext::RegistrarExt)

data/lib/psychgus/ext.rb

@@ -0,0 +1,32 @@
+#!/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
+  ###
+  # Contains all of the extensions (monkey patching) to core/Psych classes/modules.
+  # 
+  # @author Jonathan Bradley Whited (@esotericpig)
+  # @since  1.0.0
+  ###
+  module Ext
+  end
+end

data/lib/psychgus/styled_document_stream.rb

@@ -0,0 +1,66 @@
+#!/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/styled_tree_builder'
+
+module Psychgus
+  ###
+  # Use this wherever Psych::Handlers::DocumentStream would have been used, to enable styling.
+  # 
+  # @author Jonathan Bradley Whited (@esotericpig)
+  # @since  1.0.0
+  # 
+  # @see Psychgus.parse_stream Psychgus.parse_stream
+  # @see Psych::Handlers::DocumentStream
+  ###
+  class StyledDocumentStream < StyledTreeBuilder
+    # Initialize this class with {Styler}(s) and a block.
+    # 
+    # @param stylers [Styler] {Styler}(s) to use for styling this DocumentStream
+    # @param deref_aliases [true,false] whether to dereference aliases; output the actual value
+    #                                   instead of the alias
+    # @param block [Proc] a block to call in {#end_document} to denote a new YAML document
+    def initialize(*stylers,deref_aliases: false,**options,&block)
+      super(*stylers,deref_aliases: deref_aliases,**options)
+      
+      @block = block
+    end
+    
+    # This mimics the behavior of Psych::Handlers::DocumentStream#end_document.
+    # 
+    # @see Psych::Handlers::DocumentStream#end_document
+    def end_document(implicit_end=!streaming?())
+      @last.implicit_end = implicit_end
+      @block.call(pop)
+    end
+    
+    # This mimics the behavior of Psych::Handlers::DocumentStream#start_document.
+    # 
+    # @see Psych::Handlers::DocumentStream#start_document
+    def start_document(version,tag_directives,implicit)
+      node = Psych::Nodes::Document.new(version,tag_directives,implicit)
+      push(node)
+    end
+  end
+end