virginity 0.3.31

data/lib/virginity/dir_info/content_line.rb

@@ -0,0 +1,146 @@
+require 'virginity/encoding_decoding'
+require 'virginity/dir_info/param'
+
+module Virginity
+
+  # raised when merging will fail
+  class MergeError < Error; end
+
+  # rfc 2425 describes a content line as this:
+  #   contentline  = [group "."] name *(";" param) ":" value CRLF
+  # See also: DirectoryInformation
+  #
+  # A ContentLine is a tuple of one group (optional), a name, zero or more parameters and a value.
+
+  # Type names and parameter names are case insensitive (e.g., the type
+  # name "fn" is the same as "FN" and "Fn"). Parameter values MAY be case
+  # sensitive or case insensitive, depending on their definition.
+  class ContentLine
+    attr_accessor :group, :name, :value
+    attr_writer :params
+    alias_method :raw_value, :value
+
+    extend Encodings
+    include Encodings
+
+    # create a ContentLine by specifying all its parts
+    def initialize(name = "X-FOO", value = nil, params = [], group = nil, options = {})
+      @group = group
+      @name = name.to_s
+      @params = options[:no_deep_copy] ? (params) : Param.deep_copy(params)
+      @value = value.to_s
+    end
+
+    # decode a line
+    def self.parse(line = "X-FOO:bar")
+      group, name, params, value = line_parts(line.to_s)
+      # optimization: since params is deep_copied, constructing many objects and we know for certain that params can safely be used without copying, we put it in later.
+      new(name, value, params, group, :no_deep_copy => true)
+    end
+
+    class << self
+      alias_method :from_line, :parse
+    end
+
+    # the combination of two content lines
+    # This method will raise a MergeError if names, groups or values are conflicting
+    def self.merger(left, right)
+      raise MergeError, "group, #{left.group} != #{right.group}" unless left.group == right.group or left.group.nil? or left.group.nil?
+      raise MergeError, "name, #{left.name} != #{right.name}" unless left.has_name?(right.name)
+      raise MergeError, "value, #{left.raw_value} != #{right.raw_value}" unless left.raw_value == right.raw_value
+      ContentLine.new(left.name, left.raw_value, (left.params + right.params).uniq, left.group || right.group)
+    end
+
+    # combine with new values from another line.
+    # This method will raise a MergeError if names, groups or values are conflicting
+    def merge_with!(other)
+      raise MergeError, "group, #{group} != #{other.group}" unless group == other.group or group.nil? or other.group.nil?
+      raise MergeError, "name, #{name} != #{other.name}" unless has_name?(other.name)
+      raise MergeError, "value, #{raw_value} != #{other.raw_value}" unless raw_value == other.raw_value
+      self.group = group || other.group
+      self.params = (params + other.params).uniq
+      self
+    end
+
+    GROUP_DELIMITER = "."
+    COLON_CHAR = ":"
+    def encode #(options = {})
+      line = ""
+      line << group << GROUP_DELIMITER unless group.nil?
+      line << name << params_to_s << COLON_CHAR << raw_value
+    end
+    alias_method :to_s, :encode
+
+    def pretty_print(q)
+      q.text({:line => { group: @group, name: @name, params: params_to_s, value: @value }}.to_yaml)
+    end
+
+    def has_name?(name)
+      @name.casecmp(name) == 0
+    end
+
+    # if key is given, return only matching parameters
+    def params(key = nil)
+      if key.nil?
+        @params
+      else
+        @params.select { |param| param.has_key?(key) } # case insensitive by design!
+      end
+    end
+
+    # convenience method to grab only the values of the parameters (without the keys)
+    def param_values(key = nil)
+      params(key).map { |param| param.value }
+    end
+
+    def ==(other)
+      group == other.group &&
+        has_name?(other.name) &&
+        params == other.params &&
+        raw_value == other.raw_value
+    end
+
+    def <=>(other)
+      str_diff(group, other.group) || str_diff(name, other.name) || (to_s <=> other.to_s)
+    end
+
+    def hash
+      [group, name, params, raw_value].hash
+    end
+
+    def eql?(other)
+      group == other.group &&
+        has_name?(other.name) &&
+        params == other.params &&
+        raw_value ==  other.raw_value
+    end
+
+    GROUP = /#{Bnf::NAME}\./
+    NAME = /#{Bnf::NAME}/
+    # decode a contentline, returns the four parts [group, name, params, value]
+    def self.line_parts(line)
+      scanner = StringScanner.new(line)
+      if group = scanner.scan(GROUP)
+        group.chomp!(".")
+        group
+      end
+      name = scanner.scan(NAME)
+      name.upcase! # FIXME: names should be case insensitive when compared... only when compared
+      [group, name, Param::scan_params(scanner), scanner.rest]
+    rescue InvalidEncoding
+      raise
+    rescue => e
+      raise InvalidEncoding, "#{scanner.string.inspect}, at pos #{scanner.pos} (original error: #{e})"
+    end
+
+    def params_to_s
+      Param::params_to_s(params)
+    end
+
+  private
+    def str_diff(left, right)
+      diff = (left <=> right)
+      diff == 0 ? nil : diff
+    end
+  end
+end

data/lib/virginity/dir_info/line_folding.rb

@@ -0,0 +1,60 @@
+require 'strscan'
+$KCODE = 'U' unless defined? Encoding::UTF_8
+
+module Virginity
+
+  module LineFolding
+    LINE_ENDING = /\r\n|\n|\r/ # the order is important!
+    FOLD = /(#{LINE_ENDING})[\t\ ]/ # we accept unix-newlines and mac-newlines too (spec says only windows newlines, \r\n, are okay)
+
+    # 5.8.1.  Line delimiting and folding.
+    # A logical line MAY be continued on the next physical line anywhere between two characters by inserting a CRLF immediately followed by a single white space character (space, ASCII decimal 32, or horizontal tab, ASCII decimal 9).  At least one character must be present on the folded line. Any sequence of CRLF followed immediately by a single white space character is ignored (removed) when processing the content type.
+    def self.unfold(card)
+      card.gsub(FOLD, '')
+    end
+
+    def self.unfold_and_split(string)
+      unfold(string).split(LINE_ENDING)
+    end
+
+    # TODO: option to encode with "\r\n" instead of "\n"?
+    # not multibyte-safe but very safe for ascii
+    def self.fold_ascii(card, width = 75)
+      return card unless width > 0
+      # binary should already be encoded to a width that is smaller than width
+      card.gsub(/.{#{width}}/, "\\0\n ") # "\\0" is the matched string
+    end
+
+    # utf-8 safe folding:
+    # TODO: I think this is a good candidate to be ported to C
+    def self.fold(card, width = 75)
+      return card unless width > 0
+      # binary fields should already be encoded to a width that is smaller than width
+      scanner = StringScanner.new(card)
+      folded = ""
+      line_pos = 0
+      while !scanner.eos?
+        char = scanner.getch
+        charsize = char.size
+        if line_pos + charsize > width
+          folded << "\n "
+          line_pos = 0
+        end
+        folded << char
+        char == "\n" ? line_pos = 0 : line_pos += charsize
+      end
+      folded
+    end
+
+    # Content lines SHOULD be folded to a maximum width of 75 octets, excluding the
+    # line break.  Multi-octet characters MUST remain contiguous.
+    # So, we're doing it wrong, we should count octets... bytes.
+
+    # This is way faster than the method above and unicode-safe
+    # it is slightly different: it does not count bytes, it counts characters
+    def self.fold(card)
+      card.gsub(/.{75}(?=.)/, "\\0\n ")  # "\\0" is the matched string
+    end
+
+  end
+end

data/lib/virginity/dir_info/param.rb

@@ -0,0 +1,208 @@
+module Virginity
+
+  # A directory information parameter is basically a key-value pair.
+  # An instance of this class represents such a pair. It can deal with comparison and encoding. The class contains some methods to deal with lists of parameters
+  # Param keys are case insensitive
+  class Param
+    attr_reader :key
+    attr_accessor :value
+
+    def initialize(key, value)
+      self.key = key
+      @value = value.to_s
+    end
+
+    # convenience method, the same as calling Param.new("TYPE", value)
+    def self.type(value)
+      new('TYPE', value)
+    end
+
+    def self.pref
+      new('TYPE', 'PREF')
+    end
+
+    # convenience method, the same as calling Param.new("CHARSET", value)
+    def self.charset(value)
+      new('CHARSET', value)
+    end
+
+    # convenience method, the same as calling Param.new("ENCODING", value)
+    def self.encoding(value)
+      new('ENCODING', value)
+    end
+
+    # convenience method, the same as calling Param.new("ETAG", value)
+    def self.etag(value)
+      new('ETAG', value)
+    end
+
+    def to_s
+      "#{@key}=#{escaped_value}"
+    end
+    alias_method :inspect, :to_s
+
+    # param-name = x-name / iana-token
+    # iana-token   = 1*(ALPHA / DIGIT / "-")
+    #              ; identifier registered with IANA
+    PARAM_NAME_CHECK = /^((X|x)\-)?(\w|\-)+$/
+    def key=(key)
+      raise "Invalid param-key: #{key.inspect}" unless key =~ PARAM_NAME_CHECK
+      @key = key.upcase
+    end
+
+    def hash
+      [@key, @value].hash
+    end
+
+    def eql?(other)
+      other.is_a?(Param) && has_key?(other.key)&& @value == other.value
+    end
+
+    def has_key?(other_key)
+      @key.casecmp(other_key) == 0
+    end
+
+    # NB. Other doesn't necessarily have to be a Param
+    def ==(other)
+      has_key?(other.key) && @value == other.value
+    rescue
+      false
+    end
+
+    def <=>(other)
+      if has_key?(other.key)
+        @value <=> other.value
+      else
+        @key <=> other.key
+      end
+    end
+
+    # A semi-colon in a property parameter value must be escaped with a Blackslash character.
+    # commas too I think, since these are used to separate the param-values
+    #     param-value  = ptext / quoted-string
+    #     ptext  = *SAFE-CHAR
+    #     SAFE-CHAR    = WSP / %x21 / %x23-2B / %x2D-39 / %x3C-7E / NON-ASCII
+    #        ; Any character except CTLs, DQUOTE, ";", ":", ","
+    #     quoted-string = DQUOTE *QSAFE-CHAR DQUOTE
+    #        QSAFE-CHAR   = WSP / %x21 / %x23-7E / NON-ASCII
+    #       ; Any character except CTLs, DQUOTE
+    ESCAPE_CHARS = /\\|\;|\,|\"/
+    LF = "\n"
+    ESCAPED_LF = "\\n"
+    ESCAPE_CHARS_WITH_LF = /\\|\;|\,|\"|\n/
+    ESCAPE_HASH = {
+      '\\' => '\\\\',
+      ';' => '\;',
+      ',' => '\,',
+      '"' => '\"',
+      "\n" => '\n'
+      }
+    def escaped_value
+      if @value =~ ESCAPE_CHARS_WITH_LF
+        # put quotes around the escaped string
+        "\"#{@value.gsub(ESCAPE_CHARS) { |char| "\\#{char}" }.gsub(LF, ESCAPED_LF)}\""
+#         "\"#{@value.gsub(ESCAPE_CHARS_WITH_LF, ESCAPE_HASH)}\"" # ruby1.9
+      else
+        @value
+      end
+    end
+
+    def self.decode_value(val)
+      if Bnf::QUOTED_STRING =~ val
+        EncodingDecoding::decode_text($2)
+      else
+        val
+      end
+    end
+
+    # encodes an array of params
+    def self.simple_params_to_s(params)
+      return "" if params.empty?
+      ";" + params.uniq.sort.join(";")
+    end
+
+    # encodes an array of params
+    # param = param-name "=" param-value *("," param-value)
+    def self.params_to_s(params)
+      return "" if params.empty?
+      s = []
+      params.map {|p| p.key }.uniq.sort!.each do |key|
+        values = params.select {|p| p.has_key? key }.map {|p| p.escaped_value }.uniq.sort!
+        s << "#{key}=#{values.join(",")}"
+      end
+      ";#{s.join(";")}"
+    end
+
+    # encodes an array of params
+    def self.params_to_s(params)
+      return "" if params.empty?
+      s = ""
+      params.map { |p| p.key }.uniq.sort!.each do |key|
+        values = params.select {|p| p.has_key? key }.map {|p| p.escaped_value }.uniq.sort!
+        s << ";#{key}=#{values.join(",")}"
+      end
+      s
+    end
+
+    COLON = /:/
+    SEMICOLON = /;/
+    COMMA = /,/
+    EQUALS = /=/
+    KEY = /#{Bnf::NAME}/
+    PARAM_NAME = /((X|x)\-)?(\w|\-)+/
+    PARAM_VALUE = /#{Bnf::PVALUE}/
+
+    BASE64_OR_B = /^(BASE64)|(B)$/i
+    XSYNTHESIS_REF = /^X-Synthesis-Ref\d*$/i
+
+    # scans all params at the given position from a StringScanner including the pending colon
+    def self.scan_params(scanner)
+      unless scanner.skip(SEMICOLON)
+        scanner.skip(COLON)
+        return []
+      end
+      params = []
+      until scanner.skip(COLON) # a colon indicates the end of the paramlist
+        key = scanner.scan(PARAM_NAME)
+        unless scanner.skip(EQUALS)
+          # it's not a proper DirInfo param but nevertheless some companies (Apple) put vCard2.1 shorthand params without a key in they vCard3.0. Therefore we include support for these special cases.
+          case key
+          when Vcard21::QUOTED_PRINTABLE
+            params << Param.new('ENCODING', key)
+          when BASE64_OR_B
+            params << Param.new('ENCODING', 'B')
+          when XSYNTHESIS_REF
+            # we ignore this crap.
+          when *Vcard21::KNOWNTYPES
+            params << Param.new('TYPE', key)
+          else
+            raise InvalidEncoding, "encountered paramkey #{key.inspect} without a paramvalue"
+          end
+        end
+        key.upcase!
+        begin
+          if value = scanner.scan(PARAM_VALUE)
+            params << Param.new(key, Param::decode_value(value))
+          end
+          break if scanner.skip(SEMICOLON) # after a semicolon, we expect key=(value)+
+        end until scanner.skip(COMMA).nil? # a comma indicates another values (TYPE=HOME,WORK)
+      end
+      params
+    rescue InvalidEncoding
+      raise
+    rescue => e
+      raise InvalidEncoding, "#{scanner.string.inspect} at character #{scanner.pos}\noriginal error: #{e}"
+    end
+
+    def self.params_from_string(string)
+      scan_params(StringScanner.new(string))
+    end
+
+    def self.deep_copy(paramlist)
+      return [] if paramlist.nil? or paramlist.empty?
+      # params_from_string(simple_params_to_s(paramlist)) # slower
+      Marshal::load(Marshal::dump(paramlist)) # faster
+    end
+
+  end # class Param
+end

data/lib/virginity/dir_info/query.rb

@@ -0,0 +1,144 @@
+module Virginity
+
+  # Helper methods to perform queries on lines in a DirectoryInformation instance
+  #
+  # query format: <tt>[group.][name][:value]</tt>
+  #
+  # examples:
+  # * "FN" searches for FN-fields
+  # * "FN:John Smith" searches for an FN-field with the value "John Smith"
+  # * ":John Smith" searches for any field with the value "John Smith"
+  # * "item1.:John Smith" searches for any field with the value "John Smith" and group item1
+  module Query
+
+    # if a query cannot be parsed an InvalidQuery is raised
+    # the query-decoder expects correct input, it will not attempt to find errors or even correct them for you
+    class InvalidQuery < Error; end
+
+    GROUP = /#{Bnf::NAME}\./
+    NAME = /#{Bnf::NAME}/
+    SEMICOLON = /\;/
+    COLON = /\:/
+    def self.decode_query(query)
+      scanner = StringScanner.new(query)
+      # does the query start with a name that ends in a dot?
+      if group = scanner.scan(GROUP)
+        group.chomp!(".")
+      end
+      name = scanner.scan(NAME) # could be nil
+      params = params(scanner)
+      value = nil
+      if scanner.skip(COLON)
+        value = scanner.rest
+      end
+      [group, name, params, value]
+    end
+
+    COMMA = /,/
+    EQUALS = /=/
+    KEY = /#{Bnf::NAME}/
+    PARAM_NAME = /((X|x)\-)?(\w|\-)+/
+    PARAM_VALUE = /#{Bnf::PVALUE}/
+    def self.params(scanner)
+      return nil unless scanner.skip(SEMICOLON)
+      params = []
+      until scanner.check(COLON) or scanner.eos?  # <--- check of end of string! and *check* for colon
+        key = scanner.scan(PARAM_NAME)
+        raise InvalidQuery unless scanner.skip(EQUALS)
+        begin
+          if value = scanner.scan(PARAM_VALUE)
+            params << Param.new(key, Param::decode_value(value))
+          end
+          break if scanner.skip(SEMICOLON) # after a semicolon, we expect key=(value)+
+        end until scanner.skip(COMMA).nil? # a comma indicates another value (TYPE=HOME,WORK)
+      end
+      params
+    end
+
+    def query(query = "")
+      group, name, params, value = Query::decode_query(query)
+      lines.select do |line|
+        # to_s is used here to match a nil-group to the empty-group-query: "."
+        (group.nil? || group == line.group.to_s) &&
+        (params.nil? || params.all? { |p| line.params.include? p }) &&
+        (name.nil? || line.has_name?(name)) &&
+        (value.nil? || value == line.raw_value)
+      end
+    end
+
+    # return the first match for query q. By definition this is equivalent to query(q).first but it is faster.
+    def first_match(query = "")
+      group, name, params, value = Query::decode_query(query)
+      lines.detect do |line|
+        # to_s is used here to match a nil-group to the empty-group-query: "."
+        (group.nil? || group == line.group.to_s) &&
+        (params.nil? || params.all? { |p| line.params.include?(p) }) &&
+        (name.nil? || line.has_name?(name)) &&
+        (value.nil? || value == line.raw_value)
+      end
+    end
+
+    def lines_with_name(name = "")
+      lines.select do |line|
+        line.has_name?(name)
+      end
+    end
+
+    def line_matches_query?(line, q, v)
+      raise ArgumentError, "query cannot be nil { #{q.inspect} => #{v.inspect} }?" if v.nil?
+      case q
+      when :name
+        line.has_name?(v)
+      when :raw_value
+        v == line.raw_value
+      when :text
+        return false unless line.respond_to? :text
+        v == line.text
+      when :sha1
+        return false unless line.respond_to? :sha1
+        v == line.sha1
+      when :group
+        v == line.group
+      when :values
+        raise ArgumentError, "expected an array of values { #{q.inspect} => #{v.inspect} }?" unless v.is_a? Array
+        if line.respond_to? :values
+          if line.respond_to? :components # stuctured text, values are ordered and the lenght of the array is guaranteed to be correct.
+            line.values == v
+          else
+            (line.values - v).empty?
+          end
+        else
+          false
+        end
+      when :has_param
+        # true if one param matches the array we feed it
+        line.params.include? Param.new(v.first, v.last)
+      when :has_param_with_key
+        # true if one param matches the array we feed it
+        line.params.any? { |p| p.has_key?(v) }
+      when :has_type
+        # true if one param matches the array we feed it
+        line.params.include? Param.new('TYPE', v)
+      when :params
+        # all params match v, and no param is not matching
+        raise NotImplementedError
+      else
+        raise ArgumentError, "what do you expect me to do with { #{q.inspect} => #{v.inspect} }?"
+      end
+    end
+
+    def where(query = {})
+      lines.select do |line|
+        query.all? { |q,v| line_matches_query?(line, q, v) }
+      end
+    end
+
+    def find_first(query = {})
+      lines.detect do |line|
+        query.all? { |q,v| line_matches_query?(line, q, v) }
+      end
+    end
+
+    alias_method(:/, :query) #/# kate's syntax highlighter is (slightly) broken so I put a slash here
+  end
+end