hermeneutics 1.11 → 1.14

data/lib/hermeneutics/cli/smtp.rb

@@ -0,0 +1,218 @@
+#
+#  hermeneutics/cli/smtp.rb  --  SMTP client
+#
+
+require "hermeneutics/cli/protocol"
+
+module Hermeneutics
+
+  module Cli
+
+    class SMTP < Protocol
+
+      CRLF = true
+
+      PORT, PORT_SSL = 25, 465
+
+      class Error           < StandardError ; end
+      class UnspecError     < Error         ; end
+      class ServerNotReady  < Error         ; end
+      class NotOk           < Error         ; end
+      class NotReadyForData < Error         ; end
+      class Unused          < Error         ; end
+      class Uncaught        < Error         ; end
+
+      class <<self
+        private :new
+        def open host, port = nil, timeout: nil, ssl: false
+          port ||= ssl ? PORT_SSL : PORT
+          super host, port, timeout: timeout, ssl: ssl
+        end
+      end
+
+      attr_reader :domain, :greet
+      attr_reader :advertised
+      attr_reader :last_response
+
+      def initialize *args
+        super
+        get_response.ok? or raise ServerNotReady, @last_response.msg
+      end
+
+      def size
+        @advertised && @advertised[ :SIZE]
+      end
+
+      def auth
+        @advertised && @advertised[ :AUTH]
+      end
+
+      def has_auth? meth
+        a = auth
+        a and a.include? meth
+      end
+
+
+      def helo host = nil
+        cmd_hello "HELO", host
+      end
+
+      def ehlo host = nil
+        @advertised = {}
+        cmd_hello "EHLO", host do |code,msg|
+          unless @domain then
+            @domain, @greet = msg.split nil, 2
+            next
+          end
+          keyword, param = msg.split nil, 2
+          keyword.upcase!
+          keyword = keyword.to_sym
+          case keyword
+            when :SIZE then param = Integer param
+            when :AUTH then param = param.split.map { |p| p.upcase! ; p.to_sym }
+          end
+          @advertised[ keyword] = param || true
+        end
+      end
+
+      def mail_from from
+        cmd "MAIL", "FROM:<#{from}>"
+      end
+
+      def rcpt_to to
+        cmd "RCPT", "TO:<#{to}>"
+      end
+
+      def data reader
+        write_cmd "DATA"
+        get_response.waiting? or raise NotReadyForData, @last_response.msg
+        reader.each_line { |l|
+          l =~ /\A\./ and l = ".#{l}"
+          writeline l
+        }
+        writeline "."
+        get_response_ok
+      end
+
+      def bdat data
+        data.each { |d|
+          write_cmd "BDAT", d.bytesize
+          write d
+          get_response_ok
+        }
+        write_cmd "BDAT", 0, "LAST"
+        get_response_ok do |code,msg|
+          yield msg if block_given?
+        end
+      end
+
+      def rset
+        cmd "RSET"
+      end
+
+      def help str = nil, &block
+        cmd "HELP", str, &block
+      end
+
+      def noop str = nil
+        cmd "NOOP"
+      end
+
+      def quit
+        cmd "QUIT"
+      end
+
+
+      def plain user, password
+        write_cmd "AUTH", "PLAIN"
+        get_response.waiting? or raise NotReadyForData, @last_response.msg
+        l = ["\0#{user}\0#{password}"].pack "m0"
+        writeline l
+        get_response_ok
+      end
+
+
+      def login user, password
+        write_cmd "AUTH", "LOGIN"
+        get_response.waiting? or raise NotReadyForData, @last_response.msg
+        writeline [user].pack "m0"
+        get_response.waiting? or raise NotReadyForData, @last_response.msg
+        writeline [password].pack "m0"
+        get_response_ok
+      end
+
+
+      private
+
+      def cmd_hello name, host, &block
+        host ||= Socket.gethostname
+        write_cmd name, host
+        get_response_ok &block
+        unless @domain then
+          @domain, @greet = @last_response.msg.split nil, 2
+        end
+      end
+
+      def cmd name, *args, &block
+        write_cmd name, *args
+        get_response_ok &block
+      end
+
+      def write_cmd name, *args
+        l = [ name, *args].join " "
+        writeline l
+      end
+
+      class Response
+
+        attr_reader :code, :msg
+
+        def initialize code, msg
+          @code, @msg = code, msg
+        end
+
+        def kat ; code / 100 ; end
+
+        def to_s ; "%03d %s" % [ @code, @msg] ; end
+
+        def prelim?  ; kat == 1 ; end
+        def ok?      ; kat == 2 ; end
+        def waiting? ; kat == 3 ; end
+        def error?   ; kat == 4 ; end
+        def fatal?   ; kat == 5 ; end
+
+      end
+
+      def get_response_ok &block
+        get_response &block
+        @last_response.ok? or raise NotOk, @last_response.msg
+        true
+      end
+
+      def get_response
+        loop do
+          r = readline
+          if r =~ /\A(\d\d\d) / then
+            @last_response = Response.new $1.to_i, $'
+            break
+          elsif r =~ /\A(\d\d\d)-/ then
+            block_given? or raise Uncaught, r
+            yield $1.to_i, $'
+          else
+            raise UnspecError, r
+          end
+        end
+        @last_response
+      ensure
+        unless done? then
+          r = readline
+          r and raise Unused, "Unexpected data: #{r.inspect}"
+        end
+      end
+
+    end
+
+  end
+
+end
+

data/lib/hermeneutics/color.rb

@@ -8,7 +8,7 @@
 
 Hermeneutics::Color handles 24-bit colors.
 
-Hermeneutics::Colour is an alias for <code>Hermeneutics::Color</code>.
+Hermeneutics::Colour is an alias for +Hermeneutics::Color+.
 
 =end
 
@@ -41,7 +41,7 @@ module Hermeneutics
     #   new( r, g, b)           -> clr
     #
     # Create a color with red, green and blue values.  They are in range
-    # <code>0..255</code>.
+    # +0..255+.
     #
     def initialize r, *gb
       if gb.any? then
@@ -79,8 +79,8 @@ module Hermeneutics
       # :call-seq:
       #   gray( num)           -> clr
       #
-      # Create a gray color (r=b=g). <code>num</code> is in range
-      # <code>0..255</code>.
+      # Create a gray color (r=b=g). +num+ is in range
+      # +0..255+.
       #
       def gray i
         new i, i, i
@@ -96,7 +96,7 @@ module Hermeneutics
     #
     def to_s ; "#" + tuple.map { |x| "%02x" % x }.join ; end
 
-    def inspect ; "#<#{cls}:#{'0x%08x' % (object_id << 1)} #{to_s}>" ; end
+    def inspect ; "#<#{self.class}:#{'0x%08x' % (object_id << 1)} #{to_s}>" ; end
 
     class <<self
 
@@ -224,8 +224,8 @@ module Hermeneutics
     # :call-seq:
     #   edit_hsv() { |h,s,v| ... }    -> clr
     #
-    # Convert it to an HSV triple, yield that to the block and build a
-    # new <code>Color</code> from the blocks result.
+    # Convert it to an HSV triple, yield that to the block and build a new
+    # +Color+ from the blocks result.
     #
     def edit_hsv
       hsv = yield *to_hsv
@@ -241,7 +241,7 @@ module Hermeneutics
 
   end
 
-  # Alias for class <code>Hermeneutics::Color</code> in British English.
+  # Alias for class +Hermeneutics::Color+ in British English.
   Colour = Color
 
 end

data/lib/hermeneutics/contents.rb

@@ -115,6 +115,9 @@ module Hermeneutics
       end
     end
 
+    def empty?    ; @hash.empty?            ; end
+    def notempty? ; self if @hash.notempty? ; end
+
     # :call-seq:
     #   []( key)      -> str or nil
     #
@@ -256,6 +259,9 @@ module Hermeneutics
       super hash
     end
 
+    def empty?    ; @caption.empty? and super           ; end
+    def notempty? ; self if @caption.notempty? or super ; end
+
     def =~ re
       @caption =~ re
     end

data/lib/hermeneutics/css.rb

@@ -26,7 +26,7 @@ module Hermeneutics
   #       a ":visited", ATTR_COL2, ATTR_DECON
   #       a ":active", ATTR_COL1, ATTR_DECON
   #       a ":focus",  ATTR_COL1, ATTR_DECOU
-  #       space
+  #       skip
   #
   #       body "#dummy" do
   #         properties background_color: "f7f7f7".to_rgb
@@ -145,22 +145,22 @@ module Hermeneutics
     def comment str
       @out << "/*"
       str = mask_comment str
-      ml = str =~ %r(#$/)
+      ml = str =~ %r(\n)
       if ml then
-        @out << $/
+        @out << "\n"
         str.each_line { |l|
           l.chomp!
-          @out << " * " << l << $/
+          @out << " * " << l << "\n"
         }
       else
         @out << " " << str
       end
       @out << " */"
-      ml and @out << $/
+      ml and @out << "\n"
     end
 
-    def space
-      @out << $/
+    def skip
+      @out << "\n"
     end
 
     def tag *args
@@ -232,15 +232,15 @@ module Hermeneutics
       args.each { |a| p.update a }
       @out << sel << " {"
       nl, ind = if p.size > 1 then
-        @out << $/
-        [ $/, INDENT]
+        @out << "\n"
+        [ "\n", INDENT]
       else
         [ " ", " "]
       end
       single p do |s|
         @out << ind << s << nl
       end
-      @out << "}" << $/
+      @out << "}" << "\n"
     end
 
     def single hash

data/lib/hermeneutics/escape.rb

@@ -12,25 +12,25 @@ require "supplement"
 :section: Classes definied here
 
 Hermeneutics::Entities encodes to and decodes from HTML-Entities
-(<code>&amp;</code> etc.)
+(+&amp;+ etc.)
 
 Hermeneutics::URLText encodes to and decodes from URLs
-(<code>%2d</code> etc.)
+(+%2d+ etc.)
 
 Hermeneutics::HeaderExt encodes to and decodes from E-Mail Header fields
-(<code>=?UTF-8?Q?=C3=B6?=</code> etc.).
+(+=?UTF-8?Q?=C3=B6?=+ etc.).
 
 =end
 
 module Hermeneutics
 
-  # Translate HTML and XML character entities: <code>"&"</code> to
-  # <code>"&amp;"</code> and vice versa.
+  # Translate HTML and XML character entities: +"&"+ to
+  # +"&amp;"+ and vice versa.
   #
   # == What actually happens
   #
-  # HTML pages usually come in with characters encoded <code>&lt;</code>
-  # for <code><</code> and <code>&euro;</code> for <code>€</code>.
+  # HTML pages usually come in with characters encoded +&lt;+ for +<+ and
+  # +&euro;+ for +€+.
   #
   # Further, they may contain a meta tag in the header like this:
   #
@@ -41,27 +41,25 @@ module Hermeneutics
   #
   #   <?xml version="1.0" encoding="UTF-8" ?>         (XHTML)
   #
-  # When +charset+ is <code>utf-8</code> and the file contains the byte
-  # sequence <code>"\303\244"</code>/<code>"\xc3\xa4"</code> then there will
-  # be displayed a character <code>"ä"</code>.
+  # When +charset+ is +utf-8+ and the file contains the byte sequence
+  # +"\303\244"+/+"\xc3\xa4"+ then there will be displayed a character +"ä"+.
   #
-  # When +charset+ is <code>iso8859-15</code> and the file contains the byte
-  # sequence <code>"\344"</code>/<code>"\xe4"</code> then there will be
-  # displayed a character <code>"ä"</code>, too.
+  # When +charset+ is +iso8859-15+ and the file contains the byte sequence
+  # +"\344"+/+"\xe4"+ then there will be displayed a character +"ä"+, too.
   #
-  # The sequence <code>"&auml;"</code> will produce an <code>"ä"</code> in any
+  # The sequence +"&auml;"+ will produce an +"ä"+ in any
   # case.
   #
   # == What you should do
   #
   # Generating your own HTML pages you will always be safe when you only
-  # produce entity tags as <code>&auml;</code> and <code>&euro;</code> or
-  # <code>&#x00e4;</code> and <code>&#x20ac;</code> respectively.
+  # produce entity tags as +&auml;+ and +&euro;+ or +&#x00e4;+ and +&#x20ac;+
+  # respectively.
   #
   # == What this module does
   #
-  # This module translates strings to a HTML-masked version.  The encoding will
-  # not be changed and you may demand to keep 8-bit-characters.
+  # This module translates strings to a HTML-masked version.  The encoding
+  # will not be changed and you may demand to keep 8-bit-characters.
   #
   # == Examples
   #
@@ -118,7 +116,7 @@ module Hermeneutics
     # :call-seq:
     #   new( keep_8bit: bool)     -> ent
     #
-    # Creates an <code>Entities</code> converter.
+    # Creates an +Entities+ converter.
     #
     #   ent = Entities.new keep_8bit: true
     #
@@ -184,9 +182,8 @@ module Hermeneutics
       #   Entities.decode "&lt;"                       #=> "<"
       #   Entities.decode "&auml;&ouml;&uuml;"         #=> "äöü"
       #
-      # Unmasked 8-bit-characters (<code>"ä"</code> instead of
-      # <code>"&auml;"</code>) will be kept but translated to
-      # a unique encoding.
+      # Unmasked 8-bit-characters (+"ä"+ instead of +"&auml;"+) will be kept
+      # but translated to a unique encoding.
       #
       #   s = "ä &ouml; ü"
       #   s.encode! "utf-8"
@@ -259,7 +256,7 @@ module Hermeneutics
     # :call-seq:
     #   new( hash)  -> urltext
     #
-    # Creates a <code>URLText</code> converter.
+    # Creates a +URLText+ converter.
     #
     # The parameters may be given as values or as a hash.
     #
@@ -276,7 +273,7 @@ module Hermeneutics
     # :call-seq:
     #   encode( str)     -> str
     #
-    # Create a string that contains <code>%XX</code>-encoded bytes.
+    # Create a string that contains +%XX+-encoded bytes.
     #
     #   utx = URLText.new
     #   utx.encode "'Stop!' said Fred."       #=> "%27Stop%21%27+said+Fred."
@@ -292,15 +289,14 @@ module Hermeneutics
     #   s = "< ä >".encode "ISO-8859-1"
     #   utx.encode s                    #=> "%3C+\xe4+%3E"      in ISO-8859-1
     #
-    # A space <code>" "</code> will not be replaced by a plus <code>"+"</code>
-    # if +keep_space+ is set.
+    # A space +" "+ will not be replaced by a plus +"\+"+ if +keep_space+ is
+    # set.
     #
     #   utx = URLText.new keep_space: true
     #   s = "< x >"
     #   utx.encode s                    #=> "%3C x %3E"
     #
-    # When +mask_space+ is set, then a space will be represented as
-    # <code>"%20"</code>,
+    # When +mask_space+ is set, then a space will be represented as +"%20"+,
     #
     def encode str
       r = str.new_string
@@ -370,7 +366,7 @@ module Hermeneutics
     # :call-seq:
     #   encode_hash( hash)     -> str
     #
-    # Encode a <code>Hash</code> to a URL-style string.
+    # Encode a +Hash+ to a URL-style string.
     #
     #   utx = URLText.new
     #
@@ -470,8 +466,8 @@ module Hermeneutics
       #   decode_hash( str)                      -> hash
       #   decode_hash( str) { |key,val| ... }    -> nil or int
       #
-      # Decode a URL-style encoded string to a <code>Hash</code>.
-      # In case a block is given, the number of key-value pairs is returned.
+      # Decode a URL-style encoded string to a +Hash+. In case a block is
+      # given, the number of key-value pairs is returned.
       #
       #   str = "a=%3B%3B%3B&x=%26auml%3B%26ouml%3B%26uuml%3B"
       #   URLText.decode_hash str do |k,v|
@@ -528,7 +524,7 @@ module Hermeneutics
     # :call-seq:
     #   new( [ parameters] )    -> con
     #
-    # Creates a <code>HeaderExt</code> converter.
+    # Creates a +HeaderExt+ converter.
     #
     # See the +encode+ method for an explanation of the parameters.
     #
@@ -572,8 +568,8 @@ module Hermeneutics
     # The result will not contain any 8-bit characters. The encoding will
     # be kept although it won't have a meaning.
     #
-    # The parameter <code>:mask</code> will have no influence on the masking
-    # itself but will guarantee characters to be masked.
+    # The parameter +:mask+ will have no influence on the masking itself but
+    # will guarantee characters to be masked.
     #
     # == Examples
     #

data/lib/hermeneutics/html.rb

@@ -151,7 +151,7 @@ module Hermeneutics
               @out << tag
               mkattrs attrs
             end
-            if nls >3 then
+            if nls>3 then
               verbose_block yield
             else
               indent_if nls>2 do
@@ -213,9 +213,9 @@ module Hermeneutics
           @out << "/* "
           brace false do
             @out << "![CDATA["
-            @out << " */" << $/
+            @out << " */\n"
             @out << str
-            @out << $/ << "/* "
+            @out << "\n/* "
             @out << "]]"
           end
           @out << " */"
@@ -227,7 +227,7 @@ module Hermeneutics
       def brk
         unless @nl then
           @nl = true
-          @out << $/
+          @out << "\n"
         end
       end
       def out_brk str