ctioga2 0.0

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

@@ -0,0 +1,359 @@
+# markup.rb: simple markup system used wirhin the documentation.
+# 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'
+
+module CTioga2
+
+  Version::register_svn_info('$Revision: 84 $', '$Date: 2009-06-12 00:09:41 +0200 (Fri, 12 Jun 2009) $')
+
+  module Commands
+
+    module Documentation
+
+      # The documentation strings are written in a simple markup
+      # language. 
+      class MarkedUpText
+
+        # Do we really need logging ?
+        include Log
+
+        # The base class for markup items.
+        class MarkupItem
+          # The documentation object
+          attr_accessor :doc
+
+          def initialize(doc)
+            @doc = doc
+          end
+
+          def to_s
+          end
+
+          def dump_string
+            return ""
+          end
+
+        end
+
+        # A markup item representing plain text.
+        #
+        # TODO: in to_s a simple word-wrapping algorithm could be
+        # used.
+        class MarkupText < MarkupItem
+          # The text
+          attr_accessor :text
+          
+          def initialize(doc, text = "", strip = true)
+            super(doc)
+            @text = text
+            if strip
+              @text.gsub!(/\n/, " ")
+            end
+          end
+
+          def to_s
+            return text
+          end
+
+          def dump_string
+            return "text: #{@text}"
+          end
+
+        end
+
+        # A markup item representing verbatim text, with the given
+        # class
+        class MarkupVerbatim < MarkupItem
+          # The text
+          attr_accessor :text
+
+          # The verbatim text class
+          attr_accessor :cls
+          
+          def initialize(doc, text, cls)
+            super(doc)
+            @text = text
+            @cls = cls
+          end
+
+          def to_s
+            return text
+          end
+
+          def dump_string
+            return "#{@cls}: #{@text}"
+          end
+
+        end
+
+        # A link to a type/group/command
+        class MarkupLink < MarkupItem
+          # The object target of the link
+          attr_accessor :target
+          
+          # _target_ is the name of the target, which can be of _type_
+          # 'group', 'command' and 'type'.
+          def initialize(doc, target, type)
+            super(doc)
+            @target = doc.send("#{type}s")[target]
+          end
+
+          def to_s
+            if @target
+              return @target.name
+            else
+              return "unknown"
+            end
+          end
+
+          def dump_string
+            return "link: #{@target}"
+          end
+        end
+
+        # An itemize object 
+        class MarkupItemize < MarkupItem
+
+          # An array of arrays of MarkupItem, each representing an
+          # element of the itemize object.
+          attr_accessor :items
+          
+          def initialize(doc, items = [])
+            super(doc)
+            @items = items
+          end
+          
+          def to_s
+            str = ""
+            for i in @items
+              str << " * "
+              for j in i
+                str << j.to_s 
+              end
+              str << "\n"
+            end
+            return str
+          end
+          
+          def dump_string
+            return @items.map {|x|
+              "* #{x.map do |y| y.dump_string; end}\n"
+            }.join('')
+          end
+
+        end
+
+        # An item that contains a paragraph
+        class MarkupParagraph < MarkupItem
+          attr_accessor :elements
+          
+          def initialize(doc, elements)
+            super(doc)
+            @elements = elements
+          end
+
+          def to_s
+            return @elements.map {|x| x.to_s }.join('')
+          end
+
+          def dump_string
+            return "par: " + @elements.map {|x|
+              "  #{x.dump_string}\n"
+            }.join('')
+          end
+
+        end
+
+        # The reference Doc object
+        attr_accessor :doc
+
+        # The elements that make up the MarkedUpText
+        attr_accessor :elements
+
+        # Creates a MarkedUpText object.
+        def initialize(doc, text = nil)
+          @elements = []
+          @doc = doc
+          if text
+            parse_from_string(text)
+          end
+        end
+
+
+        def dump
+          puts "Number of elements: #{@elements.size}"
+          for el in @elements
+            puts "#{el.class} -> #{el.to_s}"
+          end
+        end
+
+
+        # Parses the given _string_ and append the results to the
+        # MarkedUpText's elements.
+        #
+        # Markup elements:
+        #
+        # * a line beginning with '> ' is an example for command-line
+        # * a line beginning with '# ' is an example for use within a
+        #   command file.
+        # * a line beginning with '@ ' is a generic verbatim text.
+        # * a line beginning with ' *' is an element of an
+        #   itemize. The itemize finishes when a new paragraph is
+        #   starting.
+        # * a {group: ...} or {type: ...} or {command: ...} is a link
+        #   to the element.
+        # * a blank line marks a paragraph break.
+        def parse_from_string(string)
+          @last_type = nil
+          @last_string = ""
+
+          lines = string.split(/[ \t]*\n/)
+          for l in lines
+            l.chomp!
+            case l
+            when /^[#>@]\s(.*)/  # a verbatim line
+              case l[0,1]
+              when '#'
+                type = :cmdfile
+              when '>'
+                type = :cmdline
+              else
+                type = :example
+              end
+              if @last_type == type
+                @last_string << "#{$1}\n"
+              else
+                flush_element
+                @last_type = type
+                @last_string = "#{$1}\n"
+              end
+            when /^\s\*\s*(.*)/
+              flush_element
+              @last_type = :item
+              @last_string = "#{$1}\n"
+            when /^\s*$/          # Blank line:
+              flush_element
+              @last_type = nil
+              @last_string = ""
+            else
+              case @last_type
+              when :item, :paragraph # simply go on
+                @last_string << "#{l}\n"
+              else
+                flush_element
+                @last_type = :paragraph
+                @last_string = "#{l}\n"
+              end
+            end
+          end
+          flush_element
+        end
+
+        protected 
+
+        # Parses the markup found within a paragraph (ie: links and
+        # other text attributes, but not verbatim, list or other
+        # markings) and returns an array containing the MarkupItem
+        # elements.
+        def parse_paragraph_markup(doc, string)
+          els = []
+          while string =~ /\{(group|type|command):\s*([^}]+?)\s*\}/
+            els << MarkupText.new(doc, $`)
+            els << MarkupLink.new(doc, $2, $1) 
+            string = $'
+          end
+          els << MarkupText.new(doc, string)
+          return els
+        end
+
+        # Adds the element accumulated so far to the @elements array.
+        def flush_element
+          case @last_type
+          when :cmdline, :cmdfile
+            @elements << MarkupVerbatim.new(@doc, @last_string, 
+                                            "examples-#{@last_type}")
+          when :example
+            @elements << MarkupVerbatim.new(@doc, @last_string, "examples")
+          when :paragraph
+            @elements << 
+              MarkupParagraph.new(@doc, 
+                                  parse_paragraph_markup(doc, @last_string))
+          when :item
+            if @elements.last.is_a?(MarkupItemize)
+              @elements.last.items << 
+                parse_paragraph_markup(doc, @last_string)
+            else
+              @elements << 
+                MarkupItemize.new(@doc, 
+                                  [ parse_paragraph_markup(doc, @last_string)])
+            end
+          else                  # In principle, nil
+            return
+          end
+        end
+
+
+      end
+      
+      # A class dumping markup information to standard output
+      class Markup
+        # The Doc object the Markup class should dump
+        attr_accessor :doc
+
+        def initialize(doc)
+          @doc = doc
+        end
+        
+        # Dumps the markup of all commands
+        def write_commands(out = STDOUT)
+          cmds, groups = @doc.documented_commands
+
+          for g in groups
+            out.puts "Group markup: #{g.name}"
+            out.puts dump_markup(g.description)
+
+            commands = cmds[g].sort {|a,b|
+              a.name <=> b.name
+            }
+            
+            for cmd in commands
+              out.puts "Command: #{cmd.name}"
+              out.puts dump_markup(cmd.long_description)
+            end
+          end
+        end
+
+        # Dumps the markup of all types
+        def write_types(out = STDOUT)
+          types = @doc.types.sort.map { |d| d[1]}
+          for t in types
+            out.puts "Type: #{t.name}"
+            out.puts dump_markup(t.description)
+          end
+        end
+
+        def dump_markup(items)
+          if items.is_a? String 
+            mup = MarkedUpText.new(@doc, items)
+            return dump_markup(mup.elements)
+          end
+          return items.map { |x| "-> #{x.dump_string}\n"}
+        end
+
+      end
+    end
+
+  end
+end

data/lib/ctioga2/commands/general-commands.rb

@@ -0,0 +1,119 @@
+# general-commands.rb: various global scope commands
+# 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/general-types'
+require 'ctioga2/commands/parsers/file'
+
+module CTioga2
+
+  Version::register_svn_info('$Revision: 55 $', '$Date: 2009-05-27 00:01:34 +0200 (Wed, 27 May 2009) $')
+
+  module Commands
+ 
+    # General scope commands.
+    GeneralGroup = 
+      CmdGroup.new('general', "General commands", 
+                   "General scope commands", 1000)
+    
+
+    
+    # Display help on the command-line
+    CommandLineHelpCommand = 
+      Cmd.new("command-line-help", 'h', 
+              "--help", [ ]) do |plotmaker|
+      plotmaker.interpreter.doc.display_command_line_help
+      exit 
+    end
+    
+    CommandLineHelpCommand.describe("Prints help on command-line options and exits",
+                                    <<EOH, GeneralGroup)
+Prints helps about short and long options available when run from the
+command-line.
+EOH
+    
+    # Prints the version of ctioga2 used
+    PrintVersion = Cmd.new("version", '-V', "--version", []) do |plotmaker|
+      puts "This is ctioga2 version #{CTioga2::Version::version}"
+    end
+    
+    PrintVersion.describe("Prints the version", 
+                          "Prints the version of ctioga in use", 
+                          GeneralGroup)
+
+    # Includes a file
+    RunCommandFile = 
+      Cmd.new("include", '-f', "--file", 
+              [ CmdArg.new('file'), ]) do |plotmaker, file|
+      plotmaker.interpreter.run_command_file(file)
+    end
+    
+    RunCommandFile.describe("Runs given command file", <<EOH, GeneralGroup)
+Reads the file and runs commands found in them, using the ctioga language.
+> ctioga2 -f my_file.ct2
+EOH
+
+    # Evaluate a series of commands.
+    EvalCommand =  Cmd.new("eval", '-e', "--eval", 
+                           [ CmdArg.new('commands'), ]) do |plotmaker, string|
+      plotmaker.interpreter.run_commands(string)
+    end
+    
+    EvalCommand.describe("Runs the given commands", <<EOH, GeneralGroup)
+Runs the given strings as commands, as if given from a command file.
+EOH
+
+    # Increases verbosity
+    VerboseLogging = 
+      Cmd.new("verbose", '-v',  "--verbose", [ ]) do |plotmaker|
+      CTioga2::Log::set_level(Logger::INFO)
+    end
+    
+    VerboseLogging.describe("Makes ctioga2 more verbose", <<EOH, GeneralGroup)
+With this on, ctioga2 outputs quite a fair amount of informative messages.
+EOH
+
+    # Write debugging information.
+    #
+    # TODO: this should be the place where a lot of customization of
+    # the debug output could go - including channels or things like
+    # that. To be seen later on...
+    DebugLogging = 
+      Cmd.new("debug", nil,  "--debug", [ ]) do |plotmaker|
+      CTioga2::Log::set_level(Logger::DEBUG)
+    end
+    
+    DebugLogging.describe("Makes ctioga2 write out debugging information", 
+                          <<EOH, GeneralGroup)
+With this on, ctioga2 writes a whole lot of debugging information. You
+probably will not need that unless you intend to file a bug report or
+to tackle a problem yourself.
+EOH
+
+    # Includes a file
+    EchoCmd = 
+      Cmd.new("echo", nil,  "--echo", [ ]) do |plotmaker|
+      STDERR.puts "Command-line used: "
+      STDERR.puts plotmaker.quoted_command_line
+    end
+    
+    EchoCmd.describe("Prints command-line used to standard error", 
+                     <<EOH, GeneralGroup)
+Writes the whole command-line used to standard error, quoted in such a
+way that it should be usable directly for copy/paste.
+EOH
+    
+    
+  end
+end
+