activefacts-api 1.6.0 → 1.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: e0575368e36de9bcdb5ccec88a51326b01714ba3
-  data.tar.gz: 429c0170ab64f042f7e5ea0a2f14cd2ef5695965
+  metadata.gz: a80ac6cfb494e2b05728351858aa283a569caa5b
+  data.tar.gz: d5abea27b67b2501f16819de68c5716350423940
 SHA512:
-  metadata.gz: e763cc4c8dee02074532ecd91289267d07e1b8f6c42e1eb5daa59b0dbbfdf1c9814673dac6fe05c0ca37f9b339755a68391cedd80939b844b3797589cb02818a
-  data.tar.gz: 11e8b5774f723d2d0817cc37fd4510bbb04248b41697d39a745314f7cec83cea2dfc3945e7a5def7846aa6e1a172555b8ceeae33c1ec529c9869bc172d3cd94f
+  metadata.gz: 63bcb8b0e4b562ed566ea33f286469d11ba5ddce18f59cb58b66e45d5b78d94bc0643c171b8375d6d6a5d10d19aec7a5678cd42d15ab657aa53519fe05c13005
+  data.tar.gz: 8a0768e8cfe086e62ada27b327e1b9a049c4825efd0fdb925a9f6ccc85ef3873ba06a79a757ee27014bb13a86adfe6e9c4ec2374d3395f56988193523bd2f5ee

data/VERSION

@@ -1 +1 @@
-1.6.0
+1.7.0

data/activefacts-api.gemspec

@@ -2,16 +2,16 @@
 # DO NOT EDIT THIS FILE DIRECTLY
 # Instead, edit Jeweler::Tasks in Rakefile, and run 'rake gemspec'
 # -*- encoding: utf-8 -*-
-# stub: activefacts-api 1.6.0 ruby lib
+# stub: activefacts-api 1.7.0 ruby lib
 
 Gem::Specification.new do |s|
   s.name = "activefacts-api"
-  s.version = "1.6.0"
+  s.version = "1.7.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.require_paths = ["lib"]
   s.authors = ["Clifford Heath"]
-  s.date = "2015-02-24"
+  s.date = "2015-03-06"
   s.description = "\nThe ActiveFacts API is a Ruby DSL for managing constellations of elementary facts.\nEach fact is either existential (a value or an entity), characteristic (boolean) or\nbinary relational (A rel B). Relational facts are consistently co-referenced, so you\ncan traverse them efficiently in any direction. Each constellation maintains constraints\nover the fact population.\n"
   s.email = "clifford.heath@gmail.com"
   s.extra_rdoc_files = [

data/lib/activefacts/tracer.rb

@@ -1,9 +1,39 @@
 #
-#       ActiveFacts Support code.
-#       The trace method supports indented tracing.
-#       Set the TRACE environment variable to enable it. Search the code to find the TRACE keywords, or use "all".
+# ActiveFacts Tracer.
 #
-# Copyright (c) 2009 Clifford Heath. Read the LICENSE file.
+# The trace() method supports indented tracing.
+#
+# The first argument is normally a symbol which is the key for related trace calls.
+# Set the TRACE environment variable to enable it, or add trace.enable(:key) to a CLI.
+#
+# Each subsequent argument is either
+#  - a String (or anything that can be join()ed), or
+#  - a Proc (or anything that can be called) that returns such a string.
+# Proc arguments will be called only if the trace key is enabled.
+# If the key is enabled (or not present) the Trace strings will be joined and emitted.
+#
+# A block passed to the trace method will always be called, and trace will always return its value.
+# Any trace emitted from within such a block will be indented if the current trace key is enabled.
+#
+# As a special case, a call to trace with a key ending in _ is enabled if the base key is
+# enabled, but enabled all nested calls to trace whether or not their key is enabled.
+# 
+# A call to trace with a key but without a block will return true if the key is enabled
+#
+# A call to trace with no arguments returns the Tracer object itself.
+#
+# Built-in trace key behaviour:
+#   help - list (at exit) all trace keys that became available during the run
+#   all - enable all trace keys
+#   keys - display trace keys on every trace message (automatically enabled by :all)
+#   debug - prepare a Ruby debugger at the start of the run, so it has the full context available
+#   firstaid - stop inside the constructor for any exception so you can inspect the local context of the cause
+#   trap - trap SIGINT (^C) in a block that allows inspecting or continuing execution (not all debuggers support this)
+#   flame - use ruby-prof-flamegraph to display the performance profile as a flame graph using SVG
+#
+# The debugger is chosen from ENV['DEBUG_PREFERENCE'] or the first to load of: byebug, pry. debugger, ruby-trace
+#
+# Copyright (c) 2009-2015 Clifford Heath. Read the LICENSE file.
 #
 module ActiveFacts
   (class << self; self; end).class_eval do
@@ -12,130 +42,193 @@ module ActiveFacts
 
   class Tracer
     def initialize
+      @indent = 0	# Current nesting level of enabled trace blocks
       @nested = false   # Set when a block enables all enclosed tracing
-      @available = {}
+      @available = {}	# Hash of available trace keys, accumulated during the run
 
-      # First time, initialise the tracing environment
-      @indent = 0
       @keys = {}
-      if (e = ENV[@@trace_name ||= "TRACE"])
-        e.split(/[^_a-zA-Z0-9]/).each{|k| enable(k) }
-        if @keys[:help]
-          at_exit {
-            @stderr.puts "---\nDebugging keys available: #{@available.keys.map{|s| s.to_s}.sort*", "}"
-          }
-        end
-        if @keys[:debug]
-          errors = []
-          success = false
-          (
-	    [ENV["DEBUG_PREFERENCE"]].compact +
-	    [
-	      'byebug',
-	      'pry',
-	      'debugger',
-	      'ruby-debug'
-	    ]
-	  ).each do |debugger|
-            begin
-              require debugger
-              puts "Loaded "+debugger
-	      if debugger == 'byebug'
-		Kernel.class_eval do
-		  alias_method :byebug, :debugger
-		end
-	      end
-              success = true
-              break
-            rescue LoadError => e
-              errors << e
-            end
-          end
-          unless success
-            puts "Can't load any debugger, failed on:\n#{errors.inspect}"
-          end
-          ::Debugger.start rescue nil
-        end
+      if (e = ENV["TRACE"])
+	e.split(/[^_a-zA-Z0-9]/).each{|k| enable(k) }
       end
     end
 
-    def keys
+    def trace(*args, &block)
+      begin
+	old_indent, old_nested, enabled = @indent, @nested, show(*args)
+	# Apologies for this monstrosity, but it reduces the steps when single-stepping:
+	block ? yield : (args.size == 0 ? self : (enabled == 1 ? true : false))
+      ensure
+	@indent, @nested = old_indent, old_nested
+      end
+    end
+
+    def available_keys
       @available.keys
     end
 
-    def enabled key
+    def enabled? key
       !key.empty? && @keys[key.to_sym]
     end
 
     def enable key
-      !key.to_s.empty? && @keys[key.to_sym] = true
+      if !key.empty? && !@keys[s = key.to_sym]
+	@keys[s] = true
+	setup_help if s == :help
+	setup_flame if s == :flame
+      else
+	true
+      end
     end
 
     def disable key
-      !key.to_s.empty? && @keys.delete(key.to_sym)
+      !key.empty? and @keys.delete(key.to_sym)
     end
 
     def toggle key
-      !key.to_s.empty? and enabled(key) ? (disable(key); false) : (enable(key); true)
+      if !key.empty?
+	if enabled?(key)
+	  disable(key)
+	  false
+	else
+	  enable(key)
+	  true
+	end
+      end
     end
 
-    def selected(args)
-      # Figure out whether this trace is enabled (itself or by :all), if it nests, and if we should print the key:
-      key =
-        if Symbol === args[0]
-          control = args.shift
-          if (s = control.to_s) =~ /_\Z/
-            nested = true
-            s.sub(/_\Z/, '').to_sym     # Avoid creating new strings willy-nilly
-          else
-            control
-          end
-        else
-          :all
-        end
+    def setup_help
+      at_exit {
+	$stderr.puts "---\nTracing keys available: #{@available.keys.map{|s| s.to_s}.sort*", "}"
+      }
+    end
 
-      @available[key] ||= key   # Remember that this trace was requested, for help
-      enabled = @nested ||      # This trace is enabled because it's in a nested block
-                @keys[key] ||   # This trace is enabled in its own right
-                @keys[:all]     # This trace is enabled because all are
-      @nested = nested
-      [
-        (enabled ? 1 : 0),
-        @keys[:all] ? " %-15s"%control : nil
-      ]
+    def setup_flame
+      require 'ruby-prof'
+      require 'ruby-prof-flamegraph'
+      profile_result = RubyProf.start
+      at_exit {
+	profile_result2 = RubyProf.stop
+	printer = RubyProf::FlameGraphPrinter.new(profile_result2)
+	data_file = "/tmp/flamedata_#{Process.pid}.txt"
+	svg_file = "/tmp/flamedata_#{Process.pid}.svg"
+	flamegraph = File.dirname(__FILE__)+"/flamegraph.pl"
+	File.popen("tee #{data_file} | perl #{flamegraph} --countname=ms --width=4800 > #{svg_file}", "w") { |f|
+	  printer.print(f, {})
+	}
+	STDERR.puts("Flame graph dumped to file:///#{svg_file}")
+      }
+    end
+
+    def setup_debugger
+      begin
+	require 'ruby-trace '
+	Debugger.start # (:post_mortem => true)  # Some Ruby versions crash on post-mortem debugging
+      rescue LoadError
+	# Ok, no debugger, tough luck.
+      end
+
+      (
+	[ENV["DEBUG_PREFERENCE"]].compact +
+	[
+	  'byebug',
+	  'pry',
+	  'debugger',
+	  'ruby-trace '
+	]
+      ).each do |debugger|
+	begin
+	  require debugger
+	  if debugger == 'byebug'
+	    Kernel.class_eval do
+	      alias_method :byebug, :debugger
+	    end
+	  end
+	  ::Debugger.start if (const_get(::Debugger) rescue nil)
+	  break
+	rescue LoadError => e
+	  errors << e
+	end
+      end
+
+      if trace :trap
+	trap('SIGINT') do
+	  puts "Stopped at:\n\t"+caller*"\n\t"
+	  debugger
+	  true	# Stopped on SIGINT
+	end
+      end
     end
 
+    def setup_firstaid
+      if trace :firstaid
+	puts "Preparing first aid kit"
+	::Exception.class_eval do
+	  alias_method :firstaid_initialize, :initialize
+
+	  def initialize *args, &b
+	    send(:firstaid_initialize, *args, &b)
+	    puts "Stopped due to #{self.class}: #{message} at "+caller*"\n\t"
+	    debugger
+	    true # Stopped in Exception constructor
+	  end
+	end
+      end
+    end
+
+  private
     def show(*args)
-      enabled, key_to_show = selected(args)
+      enabled, key_to_show = selected?(args)
 
       # Emit the message if enabled or a parent is:
       if args.size > 0 && enabled == 1
-        puts "\##{key_to_show} " +
-          '  '*@indent +
-          args.
-#            A laudable aim, certainly, but in practise the Procs leak and slow things down:
-#            map{|a| a.respond_to?(:call) ? a.call : a}.
-            join(' ')
+	puts "\##{key_to_show} " +
+	  '  '*@indent +
+	  args.
+            map{|a| a.respond_to?(:call) ? a.call : a}.
+	    join(' ')
       end
       @indent += enabled
       enabled
     end
 
-    def trace(*args, &block)
-      begin
-        old_indent, old_nested, enabled  = @indent, @nested, show(*args)
-        return (block || proc { enabled == 1 }).call
-      ensure
-        @indent, @nested = old_indent, old_nested
-      end
+    def selected?(args)
+      # Figure out whether this trace is enabled (itself or by :all), if it nests, and if we should print the key:
+      key =
+	if Symbol === args[0]
+	  control = args.shift
+	  if (s = control.to_s) =~ /_\Z/
+	    nested = true
+	    s.sub(/_\Z/, '').to_sym     # Avoid creating new strings willy-nilly
+	  else
+	    control
+	  end
+	else
+	  :all
+	end
+
+      @available[key] ||= key   # Remember that this trace was requested, for help
+      enabled = @nested ||      # This trace is enabled because it's in a nested block
+		@keys[key] ||   # This trace is enabled in its own right
+		@keys[:all]     # This trace is enabled because all are
+      @nested = nested
+      [
+	(enabled ? 1 : 0),
+	@keys[:keys] || @keys[:all] ? " %-15s"%control : nil
+      ]
     end
+
   end
 end
 
+# Make the trace method globally available:
 class Object
   def trace *args, &block
     (ActiveFacts.tracer ||= ActiveFacts::Tracer.new).trace(*args, &block)
   end
 end
 
-trace ''
+# Load the ruby debugger before everything else, if requested
+if trace(:debug) or trace(:firstaid) or trace(:trap)
+  trace.setup_debugger
+  trace.setup_firstaid
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: activefacts-api
 version: !ruby/object:Gem::Version
-  version: 1.6.0
+  version: 1.7.0
 platform: ruby
 authors:
 - Clifford Heath
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-02-24 00:00:00.000000000 Z
+date: 2015-03-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rbtree-pure