tkri 0.9.0 → 0.9.1

data/bin/tkri

@@ -1,9 +1,22 @@
 #!/usr/bin/env ruby
 
-require 'tkri'
+begin
+  # If we were installed using the Gem system:
+  require 'tkri'
+rescue LoadError => load_error
+  # No, we weren't installed as a Gem. We need to make Ruby aware
+  # of our library folder.
+  lib = File.join(File.dirname(__FILE__), '..', 'lib')
+  $: << lib
+  require 'tkri'
+end
 
 app = Tkri::App.new
 ARGV.each do |topic|
-  app.go topic, true
+  if topic == '--dump-rc'
+    Tkri::DefaultSettings.dump
+  else
+    app.go topic, true
+  end
 end
 app.run

data/lib/tkri.rb

@@ -10,28 +10,117 @@ require 'tk'
 
 module Tkri
 
-COMMAND = {
-  # Each platform may use a different command. The commands are indexed by any
-  # substring in RUBY_PLATFORM. If none matches the platform, the 'default' key
-  # is used.
-  'default' => 'qri -f ansi "%s"',
-  /linux/   => 'qri -f ansi "%s" 2>&1',
-  /darwin/  => 'qri -f ansi "%s" 2>&1',
-}
-  
-TAGS = {
-  'bold'    => { :foreground => 'blue' },
-  'italic'  => { :foreground => '#6b8e23' }, # greenish
-  'code'    => { :foreground => '#1874cd' }, # blueish
-  'header2' => { :background => '#ffe4b5' },
-  'header3' => { :background => '#ffe4b5' },
-  'keyword' => { :foreground => 'red' },
-  'search'  => { :background => 'yellow' },
-  'hidden'  => { :elide => true },
-}
+  # Returns the pathname of the 'rc' file.
+  def self.get_rc_file_path
+    basename = RUBY_PLATFORM.index('mswin') ? '_tkrirc' : '.tkrirc'
+    if ENV['HOME']
+      File.join(ENV['HOME'], basename)
+    else
+      # Probably Windows with no $HOME set. Dir.pwd sucks but is there
+      # anything better to do?  At least the "Help :: About the RC file"
+      # screen displays this value, so the user won't be completely clueless...
+      File.join(Dir.pwd, basename)
+    end
+  end
+
+  module DefaultSettings
+
+    COMMAND = {
+      # Each platform may use a different command. The commands are indexed by any
+      # substring in RUBY_PLATFORM. If none matches the platform, the '__default__' key
+      # is used.
+      '__default__' => 'qri -f ansi "%s"',
+
+      # The "2>&1" thingy tells UNIX shells to print any error messages to the standard output.
+      # This makes it possible to see, inside Tkri, the errors `qri' (or 'ri') happens to emmit
+      # (this happens seldom, due to bugs in `qri', so it's not a very critical feature).
+      'linux'       => 'qri -f ansi "%s" 2>&1',
+      'darwin'      => 'qri -f ansi "%s" 2>&1',
+
+      # And here's the command for MS-Windows.
+      # It turns out Windows' CMD.EXE too supports "2>&1". This shell is used on NT-based
+      # systems. (In other words, if you're using the good old Windows 98, you'll have to remove
+      # this "2>&1").
+      'mswin'       => 'qri.bat -f ansi "%s" 2>&1',
+    }
+
+    TAGS = {
+      # The '__base__' attibutes are applied for every textfield and textarea.
+      # Set the background color and font to whatever you like.
+      #
+      # Font families are designated by an ordered array of names. The first
+      # found on the system will be used. So make sure to put a generic family
+      # name (i.e., one of: 'courier', 'times', 'helvetica') at the end to serve
+      # as a fallback.
+      '__base__' => { :background => '#ffeeff', :font => { :family => ['Bitstream Vera Sans Mono', 'courier'], :size => 10 } },
+      'bold'     => { :foreground => 'blue' },
+      'italic'   => { :foreground => '#6b8e23' }, # greenish
+      'code'     => { :foreground => '#1874cd' }, # blueish
+      'header2'  => { :background => '#ffe4b5', :font => { :family => ['helvetica'], :size => 16 } },
+      'header3'  => { :background => '#ffe4b5', :font => { :family => ['helvetica'], :size => 16 } },
+      'keyword'  => { :foreground => 'red' },
+      'search'   => { :background => 'yellow' },
+      'hidden'   => { :elide => true },
+    }
+ 
+    # Dump these settings into an 'rc' file.
+    def self.dump
+      require 'yaml'
+      open(Tkri.get_rc_file_path, 'w') do |f|
+        f.puts "#"
+        f.puts "# The documentation for these settings can be found in this file:"
+        f.puts "#   " + File.expand_path(__FILE__)
+        f.puts "# Also, see the 'About the `rc` file' under the 'Help' menu."
+        f.puts "#"
+        f.puts "# You may erase any setting in this file for which you want to use"
+        f.puts "# the default value."
+        f.puts "#"
+        f.puts({ 'command' => COMMAND, 'tags' => TAGS }.to_yaml)
+      end
+    end
+
+  end # module DefaultSettings
+
+  module Settings
+    COMMAND = DefaultSettings::COMMAND.dup
+    TAGS = DefaultSettings::TAGS.dup
+
+    # Load the settings from the 'rc' file. We merge them into the existing settings.
+    def self.load
+      if File.exist? Tkri.get_rc_file_path
+        require 'yaml'
+        settings = YAML.load_file(Tkri.get_rc_file_path)
+        if settings.instance_of? Hash
+          COMMAND.merge!(settings['command']) if settings['command']
+          TAGS.merge!(settings['tags']) if settings['tags']
+        end
+      end
+    end
+  end
 
 HistoryEntry = Struct.new(:topic, :cursor, :yview)
 
+# hash_to_configuration() converts any of the TAG hashes, above, to a hash suitable
+# for use in Tk. Corrently, it only converts the :font attribute to a TkFont instance.
+def self.hash_to_configuration(hash)
+  ret = hash.dup
+  if ret[:font].instance_of? Hash
+    if ret[:font][:family]
+      ret[:font] = ret[:font].dup
+      availables = TkFont.families.map { |s| s.downcase }
+      # Select the first family available on this system.
+      Array(ret[:font][:family]).each { |family|
+        if availables.include? family.downcase
+          ret[:font][:family] = family
+          break
+        end
+      }
+    end
+    ret[:font] = TkFont.new(ret[:font])
+  end
+  return ret
+end
+
 # A Tab encapsulates an @address box, where you type the topic to go to; a "Go"
 # button; and an @info box in which to show the topic.
 class Tab < TkFrame
@@ -54,7 +143,8 @@ class Tab < TkFrame
       }
     }
     @address = TkEntry.new(addressbar) {
-      configure :font => 'courier', :width => 30
+      configure Tkri::hash_to_configuration(Settings::TAGS['__base__'])
+      configure :width => 30
       pack :side => 'left', :expand => true, :fill => 'both'
     }
 
@@ -63,6 +153,7 @@ class Tab < TkFrame
     #
     _frame = self
     @info = TkText.new(self) { |t|
+      configure Tkri::hash_to_configuration(Settings::TAGS['__base__'])
       pack :side => 'left', :fill => 'both', :expand => true
       TkScrollbar.new(_frame) { |s|
         pack :side => 'right', :fill => 'y'
@@ -71,7 +162,7 @@ class Tab < TkFrame
       }
     }
 
-    TAGS.each do |name, conf|
+    Settings::TAGS.each do |name, conf|
       @info.tag_configure(name, conf)
     end
 
@@ -82,6 +173,8 @@ class Tab < TkFrame
     # If I make the following "ButtonRelease-2" instead, the <PasteSelection>
     # cancellation that follows won't work. Strange.
     @info.bind('Button-2')        { |e| go_xy_word(e.x, e.y, true) }
+    @info.bind('Key-Return')      { go_caret_word(); break }
+    @info.bind('Key-KP_Enter')    { go_caret_word(); break }
     @info.bind('ButtonRelease-3') { |e| back }
     @info.bind('Key-BackSpace')   { |e| back; break }
   
@@ -165,7 +258,16 @@ class Tab < TkFrame
       # upon releasing the mouse button.)
       return
     end
-    if (word = get_xy_word(x, y))
+    go_word('@' + x.to_s + ',' + y.to_s, newtab)
+  end
+
+  # Navigate to the topic mentioned under the caret.
+  def go_caret_word(newtab=false)
+    go_word('insert', newtab)
+  end
+
+  def go_word(position, newtab=false)
+    if (word = get_word(position))
       @app.go word, newtab
     end
   end
@@ -184,15 +286,22 @@ class Tab < TkFrame
     return ret[0].empty? ? nil : ret[2]
   end
 
-  # Get the "topic" under the mouse cursor.
-  def get_xy_word(x,y)
-    cursor = '@' + x.to_s + ',' + y.to_s
-    line = @info.get(cursor + ' linestart', cursor + ' lineend')
-    pos  = @info.get(cursor + ' linestart', cursor).length
+  # Get the "topic" at a certain postion.
+  #
+  # The 'position' paramter is an expression that can be, e.g., "insert"
+  # for the current caret position; or "@x,y" for the mouse poisition.
+  def get_word(position)
+    line = @info.get(position + ' linestart', position + ' lineend')
+    pos  = @info.get(position + ' linestart', position).length
 
     line = ' ' + line + '  '
     pos += 1
     
+    if line[pos,1] == ' '
+      # If the user clicks a space between words, or after end of line, abort.
+      return nil
+    end
+    
     a = pos
     a -= 1 while line[a-1,1] !~ /[ (]/
     z = pos
@@ -209,20 +318,20 @@ class Tab < TkFrame
     end
 
     a -= 1 # Undo the `line = ' ' + line` we did previously.
-    @info.tag_add('keyword', '%s linestart + %d chars' % [ cursor, a ],
-                             '%s linestart + %d chars' % [ cursor, a+word.length ])
+    @info.tag_add('keyword', '%s linestart + %d chars' % [ position, a ],
+                             '%s linestart + %d chars' % [ position, a+word.length ])
     word.strip!
     
     return nil if word.empty?
     return nil if word =~ /^-+$/ # A special case: a line of '-----'
 
-    case get_previous_header(cursor)
+    case get_previous_header(position)
     when 'Instance methods:'
       word = topic + '#' + word
     when 'Class methods:'
       word = topic + '::' + word
     when 'Includes:'
-      word = get_previous_class(cursor) + '#' + word if not word =~ /^[A-Z]/
+      word = get_previous_class(position) + '#' + word if not word =~ /^[A-Z]/
     end
 
     return word
@@ -429,6 +538,8 @@ class App
   def initialize
     @root = root = TkRoot.new { title 'Tkri' }
     @search_word = nil
+    
+    Settings.load
    
     menu_spec = [
       [['File', 0],
@@ -442,8 +553,10 @@ class App
       # The following :menu_name=>'help' has no effect, but it should have...
       # probably a bug in RubyTK.
       [['Help', 0, { :menu_name => 'help' }],
-        ['General', proc { help_general }, 0],
-        ['Key bindings', proc { help_key_bindings }, 0]],
+        ['Overview', proc { help_overview }, 0],
+        ['Key bindings', proc { help_key_bindings }, 0],
+        ['Tips and tricks', proc { help_tips_and_tricks }, 0],
+        ['About the $HOME/.tkrirc file', proc { help_rc }, 0]],
     ]
     TkMenubar.new(root, menu_spec).pack(:side => 'top', :fill => 'x')
 
@@ -507,12 +620,14 @@ class App
   def search
     self.status = 'Type the string to search'
     entry = TkEntry.new(@root).pack(:fill => 'x').focus
-    entry.bind('Key-Return') {
-      self.status = ''
-      @search_word = entry.get
-      @tabs.current.search_next_word entry.get
-      entry.destroy
-    }
+    ['Key-Return', 'Key-KP_Enter'].each do |event|
+      entry.bind(event) {
+        self.status = ''
+        @search_word = entry.get
+        @tabs.current.search_next_word entry.get
+        entry.destroy
+      }
+    end
     ['Key-Escape', 'FocusOut'].each do |event|
       entry.bind(event) {
         self.status = ''
@@ -533,41 +648,62 @@ class App
 
     return @ri_cache[topic] if @ri_cache[topic]
 
-    command = COMMAND.select { |k,v| RUBY_PLATFORM.index(k) }.first.to_a[1] || COMMAND['default']
-    ri = Kernel.`(command % topic)  # `
+    command = Settings::COMMAND.select { |k,v| RUBY_PLATFORM.index(k) }.first.to_a[1] || Settings::COMMAND['__default__']
+    text = Kernel.`(command % topic)  # `
     if $? != 0
-      ri += "\n" + "ERROR: Failed to run the command '%s' (exit code: %d). Please make sure you have this command in your PATH.\n\nYou may wish to modify this program's source (%s) to update the command to something that works on your system." % [command % topic, $?, $0]
+      text += "\n" + "ERROR: Failed to run the command '%s' (exit code: %d). Please make sure you have this command in your PATH.\n\nYou may wish to modify this program's source (%s) to update the command to something that works on your system." % [command % topic, $?, $0]
     else
-      if ri == "nil\n"
-        ri = 'Topic "%s" not found.' % topic
+      if text == "nil\n"
+        text = 'Topic "%s" not found.' % topic
       end
-      @ri_cache[topic] = ri
+      @ri_cache[topic] = text
       @cached_topics << topic
     end
 
+    # Make the "Multiple choices" output easier to read.
+    if text.match /Multiple choices/
+      text.gsub! /,\s+/, "\n"
+      text.gsub! /^ */,  ""
+      text.gsub! /\n/,   "\n     "
+    end
+
     # Remove the oldest topic from the cache
-    if @cached_topics.length > 10
+    if @cached_topics.length > 20
       @ri_cache.delete @cached_topics.shift
     end
     
-    return ri
+    return text
   end
 
   def helpbox(title, text)
     w = TkToplevel.new(:title => title)
-    TkText.new(w, :height => text.count("\n"), :width => 80).pack.insert('1.0', text)
+    t = TkText.new(w, :height => text.count("\n"), :width => 80).pack.insert('1.0', text)
+    t.configure Tkri::hash_to_configuration(Settings::TAGS['__base__'])
     TkButton.new(w, :text => 'Close', :command => proc { w.destroy }).pack
   end
-  
-  def help_general
-    helpbox('Help: General', <<EOS)
-Tkri (pronounce TIK-ri) is a GUI fron-end to RI (actually, by default,
-to FastRI).
+
+  def help_overview
+    helpbox('Help: Overview', <<EOS)
+ABOUT
+
+Tkri (pronounce TIK-ri) is a GUI front-end to the 'ri', or
+'qri', executables. By default it uses 'qri', which is part
+of the Fast-RI package.
+
+Tkri displays the output of that program in a window where
+each work is "hyperlinked".
+
+USAGE
+
+Launch tkri by typing 'tkri' at the operating system prompt. You
+can provide a starting topic as an argument on the command line.
+Inside the application, type the topic you wish to go to at the
+address bar, or click on a word in the main text.
 EOS
   end
 
   def help_key_bindings
-    helpbox('Help: key bindings', <<EOS)
+    helpbox('Help: Key bindings', <<EOS)
 Left mouse button
     Navigate to the topic under the cursor.
 Middle mouse button
@@ -578,6 +714,57 @@ Ctrl+W. Or right mouse button, on a tab button
     Close the tab (unless this is the only tab).
 Ctrl+L
     Move the keyboard focus to the "address" box, where you can type a topic.
+/
+    Find string in page.
+EOS
+  end
+
+  def help_tips_and_tricks
+    helpbox('Help: Tips and tricks', <<EOS)
+Some random tips:
+
+Type '/' to quickly highlight a string in the page. (If the
+string happens to be off-screen, hit ENTER to jump to it.)
+
+Ctrl+L is probably the fastest way to move the keyboard
+focus to the "address box".
+
+The references for "Hash", "Array" and "String" are the most
+sought-after, so instead of typing their full name in the address
+box you can just type the letters h, a or s, respectively.
+
+You can type the topic(s) directly on the command line;
+e.g., "tkri Array.flatten sort_by"
+
+Left-clicking on a word doesn't yet send you to a new page. It's
+*releasing* the button that sends you there. This makes it possible to
+select pieces of code: left-click, then drag, then release; since some
+text is now selected, Tkri figures out that's all you wanted.
+EOS
+  end
+
+  def help_rc
+    helpbox('Help: RC', <<EOS)
+Tkri has some settings. E.g., the colors and fonts it uses.
+
+These settings are hard-coded in the source code. But you can
+override them by having an 'rc' file in your home folder. On
+your system this file is here:
+
+    #{Tkri.get_rc_file_path}
+
+(If it's at a weird place, set your $HOME environment variable.)
+
+Of course, you're a busy person and don't have time to write
+this file from scratch. So you're going to tell Tkri to write
+this file for you; When you type:
+
+    tkri --dump-rc
+
+you're telling Tkri to dump all its default settings into that
+file. Then edit this file to your liking using your text editor.
+Finally, run tkri; it will automatically merge the settings from
+this file onto the hard-coded ones.
 EOS
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: tkri
 version: !ruby/object:Gem::Version 
-  version: 0.9.0
+  version: 0.9.1
 platform: ruby
 authors: 
 - Mooffie
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-01-12 00:00:00 +02:00
+date: 2009-10-26 00:00:00 +02:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -34,8 +34,10 @@ files:
 - README
 - lib/tkri.rb
 - bin/tkri
-has_rdoc: false
+has_rdoc: true
 homepage: http://rubyforge.org/projects/tkri/
+licenses: []
+
 post_install_message: 
 rdoc_options: []
 
@@ -56,9 +58,9 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 
 rubyforge_project: tkri
-rubygems_version: 1.3.1
+rubygems_version: 1.3.3
 signing_key: 
-specification_version: 2
+specification_version: 3
 summary: GUI front-end to FastRI's or RI's executables.
 test_files: []