tilia-vobject 4.0.0.pre.alpha5 → 4.0.2

data/lib/tilia/v_object/parser/mime_dir.rb

@@ -10,25 +10,28 @@ module Tilia
       # Sabre\VObject\Component\VCalendar
       # Sabre\VObject\Component\VCard
       class MimeDir < Parser
-        # The input stream.
+        # The list of character sets we support when decoding.
         #
-        # @var resource
-        # RUBY: attr_accessor :input
+        # This would be a const expression but for now we need to support PHP 5.5
+        @supported_charsets = [
+          'UTF-8',
+          'ISO-8859-1',
+          'Windows-1252'
+        ]
 
-        # Root component.
-        #
-        # @var Component
-        # RUBY: attr_accessor :root
+        class << self
+          attr_reader :supported_charsets
+        end
 
         # Parses an iCalendar or vCard file.
         #
         # Pass a stream or a string. If null is parsed, the existing buffer is
         # used.
         #
-        # @param string|resource|null input
-        # @param int options
+        # @param [String|resource, nil] input
+        # @param [Fixnum] options
         #
-        # @return Sabre\VObject\Document
+        # @return [Document]
         def parse(input = nil, options = 0)
           @root = nil
 
@@ -40,11 +43,27 @@ module Tilia
           @root
         end
 
+        # By default all input will be assumed to be UTF-8.
+        #
+        # However, both iCalendar and vCard might be encoded using different
+        # character sets. The character set is usually set in the mime-type.
+        #
+        # If this is the case, use setEncoding to specify that a different
+        # encoding will be used. If this is set, the parser will automatically
+        # convert all incoming data to UTF-8.
+        #
+        # @param [String] charset
+        def charset=(charset)
+          fail ArgumentError, "Unsupported encoding. (Supported encodings: #{MimeDir.supported_charsets.join(', ')})" unless MimeDir.supported_charsets.include?(charset)
+
+          @charset = charset
+        end
+
         # Sets the input buffer. Must be a string or stream.
         #
-        # @param resource|string input
+        # @param [IO, String] input
         #
-        # @return void
+        # @return [void]
         def input=(input)
           # Resetting the parser
           @line_index = 0
@@ -67,7 +86,7 @@ module Tilia
 
         # Parses an entire document.
         #
-        # @return void
+        # @return [void]
         def parse_document
           line = read_line
 
@@ -77,11 +96,11 @@ module Tilia
 
           case line.upcase
           when 'BEGIN:VCALENDAR'
-            klass = Tilia::VObject::Component::VCalendar
+            klass = Component::VCalendar.component_map['VCALENDAR']
           when 'BEGIN:VCARD'
-            klass = Tilia::VObject::Component::VCard
+            klass = Component::VCard.component_map['VCARD']
           else
-            fail Tilia::VObject::ParseException, 'This parser only supports VCARD and VCALENDAR files'
+            fail ParseException, 'This parser only supports VCARD and VCALENDAR files'
           end
 
           @root = klass.new({}, false)
@@ -95,17 +114,15 @@ module Tilia
           end
 
           name = line[4..-1].upcase
-          if name != @root.name
-            fail Tilia::VObject::ParseException, "Invalid MimeDir file. expected: \"END:#{@root.name}\" got: \"END:#{name}\""
-          end
+          fail Tilia::VObject::ParseException, "Invalid MimeDir file. expected: \"END:#{@root.name}\" got: \"END:#{name}\"" unless name == @root.name
         end
 
         # Parses a line, and if it hits a component, it will also attempt to parse
         # the entire component.
         #
-        # @param string line Unfolded line
+        # @param [String] line Unfolded line
         #
-        # @return Node
+        # @return [Node]
         def parse_line(line)
           # Start of a new component
           if line[0...6].upcase == 'BEGIN:'
@@ -143,7 +160,7 @@ module Tilia
         #
         # If that was not the case, we store it here.
         #
-        # @var null|string
+        # @return [null|string]
         # RUBY: attr_accessor :protected line_buffer
 
         # The real current line number.
@@ -152,12 +169,12 @@ module Tilia
         # In the case of unfolded lines, this property holds the line number for
         # the start of the line.
         #
-        # @var int
+        # @return [Fixnum]
         # RUBY: attr_accessor :start_line
 
         # Contains a 'raw' representation of the current line.
         #
-        # @var string
+        # @return [String]
         # RUBY: attr_accessor :raw_line
 
         # Reads a single line from the buffer.
@@ -166,7 +183,7 @@ module Tilia
         #
         # @throws \Sabre\VObject\EofException
         #
-        # @return string
+        # @return [String]
         def read_line
           if !@line_buffer.nil?
             raw_line = @line_buffer
@@ -218,9 +235,9 @@ module Tilia
 
         # Reads a property or component from a line.
         #
-        # @return void
+        # @return [Property]
         def read_property(line)
-          if @options & self.class::OPTION_FORGIVING > 0
+          if @options & OPTION_FORGIVING > 0
             prop_name_token = 'A-Z0-9\\-\\._\\/'
           else
             prop_name_token = 'A-Z0-9\\-\\.'
@@ -243,6 +260,9 @@ module Tilia
               ) (?=[;:,])
               /xi
 
+          # RUBY: We have to convert the string to UTF-8 for Regexp
+          encoding = StringUtil.guess_encoding(line)
+          line = line.encode(encoding, encoding)
           matches = line.scan(regex)
 
           property = {
@@ -311,9 +331,8 @@ module Tilia
 
           property['value'] = '' if property['value'].nil?
           if property['name'].blank?
-            if @options & self.class::OPTION_IGNORE_INVALID_LINES > 0
-              return false
-            end
+            return false if @options & OPTION_IGNORE_INVALID_LINES > 0
+
             fail Tilia::VObject::ParseException, "Invalid Mimedir file. Line starting at #{@start_line} did not follow iCalendar/vCard conventions"
           end
 
@@ -342,14 +361,27 @@ module Tilia
           if prop_obj.key?('ENCODING') && prop_obj['ENCODING'].to_s.upcase == 'QUOTED-PRINTABLE'
             prop_obj.quoted_printable_value = extract_quoted_printable_value
           else
+            charset = @charset
+            if @root.document_type == Document::VCARD21 && prop_obj.key?('CHARSET')
+              # vCard 2.1 allows the character set to be specified per property.
+              charset = prop_obj['CHARSET'].to_s
+            end
+
+            case charset
+            when 'UTF-8'
+              # NOOP
+            when 'ISO-8859-1',
+                'Windows-1252'
+              property['value'] = property['value'].to_s.encode('UTF-8', charset)
+            else
+              fail ParseException, "Unsupported CHARSET: #{charset}"
+            end
             prop_obj.raw_mime_dir_value = property['value']
           end
 
           prop_obj
         end
 
-        public
-
         # Unescapes a property value.
         #
         # vCard 2.1 says:
@@ -406,10 +438,10 @@ module Tilia
         # If it's a comma or a semi-colon the string will be split on those
         # characters, and always return an array.
         #
-        # @param string input
-        # @param string delimiter
+        # @param [String] input
+        # @param [String] delimiter
         #
-        # @return string|string[]
+        # @return [String|Array<String>]
         def self.unescape_value(input, delimiter = ';')
           regex = '(?: (\\\\ (?: \\\\ | N | n | ; | , ) )'
           regex += ' | (' + delimiter + ')' unless delimiter.blank?
@@ -474,9 +506,9 @@ module Tilia
         #   * ^ is encoded as ^^.
         #   * " is encoded as ^'
         #
-        # @param string input
+        # @param [String] input
         #
-        # @return void
+        # @return [String]
         def unescape_param(input)
           input.gsub(/(\^(\^|n|\'))/) do |match|
             case match
@@ -497,7 +529,7 @@ module Tilia
         #
         # This method does not do any decoding.
         #
-        # @return string
+        # @return [String]
         def extract_quoted_printable_value
           # We need to parse the raw line again to get the start of the value.
           #
@@ -520,7 +552,7 @@ module Tilia
           # Microsoft products don't always correctly fold lines, they may be
           # missing a whitespace. So if 'forgiving' is turned on, we will take
           # those as well.
-          if @options & self.class::OPTION_FORGIVING > 0
+          if @options & OPTION_FORGIVING > 0
             while value[-1] == '='
               # Reading the line
               read_line
@@ -532,10 +564,12 @@ module Tilia
           value
         end
 
+        # Initialize instance variables
         def initialize(*args)
           super(*args)
           @start_line = 0
           @line_index = 0
+          @charset = 'UTF-8'
         end
       end
     end

data/lib/tilia/v_object/parser/parser.rb

@@ -16,19 +16,14 @@ module Tilia
         # by the reader.
         OPTION_IGNORE_INVALID_LINES = 2
 
-        # Bitmask of parser options.
-        #
-        # @var int
-        # RUBY: attr_accessor :options
-
         # Creates the parser.
         #
         # Optionally, it's possible to parse the input stream here.
         #
-        # @param mixed input
-        # @param int options Any parser options (OPTION constants).
+        # @param input
+        # @param [Fixnum] options Any parser options (OPTION constants).
         #
-        # @return void
+        # @return [void]
         def initialize(input = nil, options = 0)
           self.input = input unless input.nil?
           @options = options
@@ -41,18 +36,18 @@ module Tilia
         #
         # If either input or options are not supplied, the defaults will be used.
         #
-        # @param mixed input
-        # @param int options
+        # @param input
+        # @param [Fixnum] options
         #
-        # @return array
-        def parse(_input = nil, _options = 0)
+        # @return [Document]
+        def parse(input = nil, options = 0)
         end
 
         # Sets the input data.
         #
-        # @param mixed input
+        # @param input
         #
-        # @return void
+        # @return [void]
         def input=(_input)
         end
       end

data/lib/tilia/v_object/parser/xml.rb

@@ -10,47 +10,32 @@ module Tilia
         XCAL_NAMESPACE = 'urn:ietf:params:xml:ns:icalendar-2.0'
         XCARD_NAMESPACE = 'urn:ietf:params:xml:ns:vcard-4.0'
 
-        # The input data.
-        #
-        # @var array
-        # RUBY: attr_accessor :input
-
-        # A pointer/reference to the input.
-        #
-        # @var array
-        # RUBY: attr_accessor :pointer
-
-        # Document, root component.
-        #
-        # @var Sabre\VObject\Document
-        # RUBY: attr_accessor :root
-
         # Creates the parser.
         #
         # Optionally, it's possible to parse the input stream here.
         #
-        # @param mixed input
-        # @param int options Any parser options (OPTION constants).
+        # @param input
+        # @param [Fixnum] options Any parser options (OPTION constants).
         #
-        # @return void
+        # @return [void]
         def initialize(input = nil, options = 0)
           @input = nil
           @pointer = nil
           @root = nil
 
-          options = self.class::OPTION_FORGIVING if options == 0
+          options = OPTION_FORGIVING if options == 0
 
           super(input, options)
         end
 
         # Parse xCal or xCard.
         #
-        # @param resource|string input
-        # @param int options
+        # @param [String, IO] input
+        # @param [Fixnum] options
         #
-        # @throws \Exception
+        # @fails [StandardError]
         #
-        # @return Sabre\VObject\Document
+        # @return [Document]
         def parse(input = nil, options = 0)
           self.input = input unless input.nil?
           @options = options if options != 0
@@ -59,11 +44,11 @@ module Tilia
           end
 
           case @input['name']
-          when "{#{self.class::XCAL_NAMESPACE}}icalendar"
+          when "{#{XCAL_NAMESPACE}}icalendar"
             @root = Tilia::VObject::Component::VCalendar.new({}, false)
             @pointer = @input['value'][0]
             parse_v_calendar_components(@root)
-          when "{#{self.class::XCARD_NAMESPACE}}vcards"
+          when "{#{XCARD_NAMESPACE}}vcards"
             @input['value'].each do |v_card|
               @root = Tilia::VObject::Component::VCard.new({ 'version' => '4.0' }, false)
               @pointer = v_card
@@ -83,9 +68,9 @@ module Tilia
 
         # Parse a xCalendar component.
         #
-        # @param Component parent_component
+        # @param [Component] parent_component
         #
-        # @return void
+        # @return [void]
         def parse_v_calendar_components(parent_component)
           components = @pointer['value'] ? @pointer['value'] : []
 
@@ -103,9 +88,9 @@ module Tilia
 
         # Parse a xCard component.
         #
-        # @param Component parent_component
+        # @param [Component] parent_component
         #
-        # @return void
+        # @return [void]
         def parse_v_card_components(parent_component)
           @pointer = @pointer['value']
           parse_properties(parent_component)
@@ -113,10 +98,10 @@ module Tilia
 
         # Parse xCalendar and xCard properties.
         #
-        # @param Component parent_component
-        # @param string  property_name_prefix
+        # @param [Component] parent_component
+        # @param [String]  property_name_prefix
         #
-        # @return void
+        # @return [void]
         def parse_properties(parent_component, property_name_prefix = '')
           properties = @pointer ? @pointer : {}
 
@@ -233,8 +218,8 @@ module Tilia
               property_type  = self.class.tag_name(xml_property['value'][0]['name'])
 
               property_value ||= []
-              xml_property['value'].each do |value|
-                property_value << value['value']
+              xml_property['value'].each do |v|
+                property_value << v['value']
               end
 
               property_parameters['value'] = 'DATE' if 'date' == property_type
@@ -252,9 +237,9 @@ module Tilia
 
         # Parse a component.
         #
-        # @param Component parent_component
+        # @param [Component] parent_component
         #
-        # @return void
+        # @return [void]
         def parse_component(parent_component)
           components = @pointer['value'] ? @pointer['value'] : []
 
@@ -271,13 +256,13 @@ module Tilia
 
         # Create a property.
         #
-        # @param Component parent_component
-        # @param string name
-        # @param array parameters
-        # @param string type
-        # @param mixed value
+        # @param [Component] parent_component
+        # @param [String] name
+        # @param [array] parameters
+        # @param [String] type
+        # @param value
         #
-        # @return void
+        # @return [void]
         def create_property(parent_component, name, parameters, type, value)
           property = @root.create_property(name, nil, parameters, type)
           parent_component.add(property)
@@ -288,16 +273,16 @@ module Tilia
 
         # Sets the input data.
         #
-        # @param resource|string input
+        # @param [resource|string] input
         #
-        # @return void
+        # @return [void]
         def input=(input)
           input = input.read unless input.is_a?(String)
 
           if input.is_a?(String)
             reader = Tilia::Xml::Reader.new
-            reader.element_map["{#{self.class::XCAL_NAMESPACE}}period"] = Tilia::VObject::Parser::Xml::Element::KeyValue
-            reader.element_map["{#{self.class::XCAL_NAMESPACE}}recur"] = Tilia::VObject::Parser::Xml::Element::KeyValue
+            reader.element_map["{#{XCAL_NAMESPACE}}period"] = Tilia::VObject::Parser::Xml::Element::KeyValue
+            reader.element_map["{#{XCAL_NAMESPACE}}recur"] = Tilia::VObject::Parser::Xml::Element::KeyValue
             reader.xml(input)
             input = reader.parse
           end
@@ -305,13 +290,11 @@ module Tilia
           @input = input
         end
 
-        protected
-
         # Get tag name from a Clark notation.
         #
-        # @param string clarked_tag_name
+        # @param [String] clarked_tag_name
         #
-        # @return string
+        # @return [String]
         def self.tag_name(clarked_tag_name)
           (_, tag_name) = Tilia::Xml::Service.parse_clark_notation(clarked_tag_name)
           tag_name