ctioga2 0.0

data/lib/ctioga2/commands/doc/introspection.rb

@@ -0,0 +1,211 @@
+# introspection.rb: get informations about what is known to ctioga2
+# copyright (c) 2009 by Vincent Fourmond
+  
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+  
+# This program 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 General Public License for more details (in the COPYING file).
+
+require 'ctioga2/utils'
+require 'ctioga2/commands/commands'
+
+module CTioga2
+
+  Version::register_svn_info('$Revision: 36 $', '$Date: 2009-05-04 21:23:15 +0200 (Mon, 04 May 2009) $')
+
+  module Commands
+
+    # The base of the 'self-documentation' of CTioga2
+    module Documentation
+
+      # This class provides facilities to display information
+      class Introspection
+        
+        # Display all known commands, along with their definition place
+        def list_commands(raw = false)
+          puts "Known commands:" unless raw
+          cmds = Interpreter::commands
+          names = cmds.keys.sort
+          if raw
+            puts names
+          else
+            max = names.inject(0) {|m,x| [m,x.size].max}
+            max2 = names.inject(0) {|m,x| [m,cmds[x].long_option.size].max}
+            for n in names
+              f,l = cmds[n].context
+              puts "\t%-#{max}s\t--%-#{max2}s\t(#{f}: #{l})" % 
+                [n, cmds[n].long_option ]
+            end
+          end
+        end
+
+        # List known groups
+        def list_groups(raw = false)
+          puts "Known groups:" unless raw
+          groups = Interpreter::groups
+          names = groups.keys.sort
+          if raw
+            puts names
+          else
+            for n in names
+              f,l = groups[n].context
+              puts "\t#{n}\t(#{f}: #{l})"
+            end
+          end
+        end
+
+        # List known types
+        def list_types(raw = false)
+          puts "Known types:" unless raw
+          types = Interpreter::types
+          names = types.keys.sort
+          if raw
+            puts names
+          else
+            for n in names
+              f,l = types[n].context
+              puts "\t#{n}\t(#{f}: #{l})"
+            end
+          end
+        end
+
+        # Lauches an editor to edit the given command:
+        def edit_command(cmd)
+          cmd = Interpreter::command(cmd)
+          if cmd
+            edit_file(*cmd.context)
+          end
+        end
+
+        # Lauches an editor to edit the given command:
+        def edit_group(group)
+          group = Interpreter::group(group)
+          if group
+            edit_file(*group.context)
+          end
+        end
+
+        # Lauches an editor to edit the given command:
+        def edit_type(type)
+          type = Interpreter::type(type)
+          if type
+            edit_file(*type.context)
+          end
+        end
+
+
+        protected 
+
+        # Launches an editor to edit the given file at the given place.
+        def edit_file(file, line)
+          editor = ENV['EDITOR'] || 'emacs'
+          if ENV['CT2_DEV_HOME']
+            file = "#{ENV['CT2_DEV_HOME']}/#{file}"
+          end
+          system("#{editor} +#{line} #{file} &")
+        end
+
+      end
+
+      IntrospectionGroup = 
+        CmdGroup.new('introspection', "Introspection",
+                     "Displays information about the internals of ctioga2",
+                     100, true)
+
+      RawOption = {'raw' => CmdArg.new('boolean')}
+
+      ListCommandsCmd = 
+        Cmd.new('list-commands', nil, '--list-commands',
+                [], RawOption) do |p, opts|
+        Introspection.new.list_commands(opts['raw'])
+      end
+
+      ListCommandsCmd.describe("List known commands",
+                               <<EOH, IntrospectionGroup)
+List all commands known to ctioga2
+EOH
+
+      ListGroupsCmd = 
+        Cmd.new('list-groups', nil, '--list-groups',
+                [], RawOption) do |p, opts|
+        Introspection.new.list_groups(opts['raw'])
+      end
+
+      ListGroupsCmd.describe("List known groups",
+                             <<EOH, IntrospectionGroup)
+List all command groups known to ctioga2
+EOH
+
+      ListTypesCmd = 
+        Cmd.new('list-types', nil, '--list-types',
+                [], RawOption) do |p, opts|
+        Introspection.new.list_types(opts['raw'])
+      end
+
+      ListTypesCmd.describe("List known types",
+                             <<EOH, IntrospectionGroup)
+List all types known to ctioga2
+EOH
+
+      EditCommandCmd = 
+        Cmd.new('edit-command', nil, '--edit-command',
+                [ CmdArg.new('text')]) do |plotmaker, cmd|
+        Introspection.new.edit_command(cmd)
+      end
+
+      EditCommandCmd.describe("Edit the command",
+                               <<EOH, IntrospectionGroup)
+Edit the given command in an editor. It will only work from the 
+top directory of a ctioga2 source tree.
+EOH
+
+      EditGroupCmd = 
+        Cmd.new('edit-group', nil, '--edit-group',
+                [ CmdArg.new('text')]) do |plotmaker, cmd|
+        Introspection.new.edit_group(cmd)
+      end
+
+      EditGroupCmd.describe("Edit the group",
+                            <<EOH, IntrospectionGroup)
+Edit the given group in an editor. It will only work from the 
+top directory of a ctioga2 source tree.
+EOH
+
+      EditTypeCmd = 
+        Cmd.new('edit-type', nil, '--edit-type',
+                [ CmdArg.new('text')]) do |plotmaker, cmd|
+        Introspection.new.edit_type(cmd)
+      end
+
+      EditTypeCmd.describe("Edit the type",
+                            <<EOH, IntrospectionGroup)
+Edit the given type in an editor. It will only work from the 
+top directory of a ctioga2 source tree.
+EOH
+
+      VersionRawCmd = 
+        Cmd.new('version-raw', nil, '--version-raw',
+                [ ]) do |plotmaker|
+        print Version::version
+      end
+
+      VersionRawCmd.describe("Raw version",
+                             <<EOH, IntrospectionGroup)
+Prints the raw version number, without any other decoration and 
+newline.
+EOH
+
+      
+
+    end
+
+  end
+
+
+end
+

data/lib/ctioga2/commands/doc/man.rb

@@ -0,0 +1,279 @@
+# man.rb: conversion of the internal help into a hand-modifiable manual page.
+# copyright (c) 2009 by Vincent Fourmond
+
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+
+# This program 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 General Public License for more details (in the COPYING file).
+
+require 'ctioga2/utils'
+require 'ctioga2/log'
+require 'ctioga2/commands/commands'
+require 'ctioga2/commands/parsers/command-line'
+
+module CTioga2
+
+  Version::register_svn_info('$Revision: 40 $', '$Date: 2009-05-08 00:45:47 +0200 (Fri, 08 May 2009) $')
+
+  module Commands
+
+    module Documentation
+
+      # Converts help texts found in the Command descriptions into a
+      # manual page that can be further edited and *updated* using this
+      # module.
+      class Man
+
+        include Log
+
+        # The Doc object Help2Man should be working on.
+        attr_accessor :doc
+
+        def initialize(doc)
+          @doc = doc
+        end
+
+        RoffCommentRE = /\.\s*\\"/
+
+        # Writes a manual page to the given _io_ stream, using _version_
+        # as the target version (the one ending up in the headers).
+        #
+        # NO... We should *input* a manual page, and spit out
+        # replacement texts.
+        def write_manual_page(version, input, out = STDOUT)
+          passed_header = false
+          if input.is_a? String
+            filename = input
+            input = File::open(input)
+          elsif input.respond_to? :path
+            filename = input.path
+          else
+            filename = "unkown"
+          end
+
+          @cmds, @groups = @doc.documented_commands
+          @cmd_exclude = {}
+          @group_exclude = {}
+
+          while line = input.gets
+            case line
+            when /^#{RoffCommentRE}\s*write-header\s*$/
+              out.puts header_string(version, filename)
+              passed_header = true
+            when /^#{RoffCommentRE}\s*write-commands\s*$/
+              write_commands(out)
+            when /^#{RoffCommentRE}\s*write-group:\s*(.*)\s*$/
+              id = $1
+              if @groups[id]
+                write_group(out, g)
+              else
+                warn "Unkown group: #{id}"
+              end
+            when /^#{RoffCommentRE}\s*write-types\s*$/
+              write_types(out)
+            else
+              if passed_header
+                out.puts line
+              end
+            end
+          end
+          out.close
+          input.close
+        end
+
+        protected
+
+        ItemizeLabel = '\fB*\fR'
+        ItemizeLabelSize = 2 
+        ItemizeIndent = 2
+        ManIndent = 8
+
+        # Takes up an array of MarkupItem objects and returns its
+        # equivalent in roff format. Alternativelely, it can take a
+        # String and feed it to MarkedUpText.
+        #
+        # TODO: make sure things are escaped the way they should be.
+        #
+        # if _inside_cmds_ is true, additional indentation is added
+        # for the lists, so that is looks neat in the end.
+        #
+        # TODO: try to be more clever about spaces in the target
+        # file. (does not matter too much for the output of man)
+        def markup_to_man(items, inside_cmds = true)
+          if items.is_a? String 
+            mup = MarkedUpText.new(@doc, items)
+            return markup_to_man(mup.elements, inside_cmds)
+          end
+          str = ""
+          for it in items
+            case it
+            when MarkedUpText::MarkupText
+              str << it.to_s
+            when MarkedUpText::MarkupLink
+              str << "\\fI#{it.to_s}\\fR"
+            when MarkedUpText::MarkupItemize
+              indent = ItemizeIndent
+              if inside_cmds
+                indent += ManIndent
+              end
+              str << "\n.RS #{indent}"
+              str << "\n.IP \"#{ItemizeLabel}\" #{ItemizeLabelSize}\n"
+              str << it.items.map {
+                |x| markup_to_man(x)
+              }.join("\n.IP \"#{ItemizeLabel}\" #{ItemizeLabelSize}\n")
+              str << "\n.RE\n\n"
+              # We restore the indentation afterwards.
+              if inside_cmds
+                str << ".IP \"\" #{ManIndent}\n"
+              end
+            when MarkedUpText::MarkupVerbatim
+              str << it.text.gsub(/^/, '  ')
+            when MarkedUpText::MarkupParagraph
+              str << "#{markup_to_man(it.elements)}\n\n"
+            else
+              raise "Markup #{it.class} isn't implemented yet for man"
+            end
+          end
+          return str
+        end
+
+        # Writes out all commands to _out_.
+        def write_commands(out)
+          for group in @groups
+            next if @group_exclude[group]
+            write_group(out, group)
+          end
+        end
+
+        # Writes out a single _group_ 
+        def write_group(out, group)
+          write_group_name(out, group)
+          write_group_description(out, group)
+          write_group_commands(out, group)
+        end
+
+        # Writes the name of a _group_ 
+        def write_group_name(out, group)
+          out.puts 
+          out.puts ".SS #{group.name}"
+          out.puts 
+        end
+
+        # Writes the description of a _group_.
+        def write_group_description(out, group)
+          out.puts 
+          out.puts markup_to_man(group.description, false)
+          out.puts 
+        end
+
+        # Writes the remaining commands of a group
+        def write_group_commands(out, group)
+          for cmd in @cmds[group].sort {|a,b|
+              a.long_option <=> b.long_option
+            }
+            next if @cmd_exclude[cmd]
+            out.puts
+            out.puts ".TP #{ManIndent}"
+            write_command(out, cmd)
+          end
+          # Now blacklist the group
+          @group_exclude[group] = true
+        end
+
+        def write_command(out, cmd)
+          write_command_signature(out, cmd)
+          write_command_description(out, cmd)
+          out.puts ".br"
+          write_command_options(out, cmd)
+          out.puts ".br"
+          write_corresponding_command(out, cmd)
+        end
+
+        # Writes a signature (ie the option specification) for the
+        # command
+        def write_command_signature(out, cmd)
+          short, long, dummy = cmd.option_strings
+          long, *args = long.split(/\s+/)
+          args = " \\fI#{args.join(' ')}\\fR"
+          out.puts ".B %s%s%s%s" % [ short, (short ? ", " : ""), long, args ]
+          # Blacklist commands whose signature we wrote.
+          @cmd_exclude[cmd] = true
+        end
+
+
+        # Returns the description for the command
+        def write_command_description(out, cmd)
+          mup = MarkedUpText.new(@doc, cmd.long_description)
+          out.puts markup_to_man(mup.elements)
+        end
+
+        # Displays the optional arguments for the given command
+        def write_command_options(out, cmd)
+          if cmd.has_options?
+            # .map {|x| "/#{x}="} ??? Does not seem to help much
+            options = cmd.optional_arguments.keys.sort.join(' ')
+            out.puts ".B Optional arguments:\n.I #{options}"
+          end
+        end
+
+        # Displays the corresponding 'file' command
+        def write_corresponding_command(out, cmd)
+          arguments = cmd.arguments.map {|a| a.displayed_name}.join(',')
+          if cmd.has_options?
+            arguments += ",option=..." 
+          end
+          out.puts ".B Corresponding command:\n.I #{cmd.name}(#{arguments})"
+        end
+
+        # Writes documentation about all the types known to ctioga.
+        def write_types(out)
+          first = true
+          for n, t in @doc.types.sort
+            write_type(out,t, first ? "8" : "")
+            first = false
+          end
+        end
+        
+        def write_type(out, type, indent = "")
+          out.puts ".TP #{indent}"
+          out.puts ".I #{type.name}"
+          out.puts "#{type.description}"
+        end
+
+        # Returns the header string
+        def header_string(version, file)
+          return ManualPageHeader % [ file, 
+                                      CTioga2::Version::last_modified_date, 
+                                      version ]
+        end
+
+        ManualPageHeader = <<'EOF'
+.\" This is the manual page for ctioga2
+.\"
+.\" Copyright 2009 by Vincent Fourmond
+.\"
+.\" This file is generated from the ctioga2 code and from the file %s
+.\"
+.\" This program is free software; you can redistribute it and/or modify
+.\" it under the terms of the GNU General Public License as published by
+.\" the Free Software Foundation; either version 2 of the License, or
+.\" (at your option) any later version.
+.\"  
+.\" This program 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 General Public License for more details (in the COPYING file).
+.\"
+.TH CTIOGA2 1 "%s" "Version %s" "Command-line interface for Tioga"
+EOF
+
+      end
+    end
+
+  end
+end