webloc 0.2.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e8ff9f7c12df7756811c14678b08b8ab6e42839dbb687b802ad37addf372f82d
-  data.tar.gz: 71f8eec3e245afe13e755127b519999255547829f3903f7d70b90099434a7493
+  metadata.gz: c818dbf002be73a6bcf36920bfae42c98bd5185d8076e5835773f3b08f41fc69
+  data.tar.gz: 78982a897fce013b29b15e66a64cdd003de478040d6399245942fd49858383e0
 SHA512:
-  metadata.gz: 82233db761cc8a120f29e0f98f6a285cf2184f3ec9c865feaef060deb1b6021682a604dc1f352ea9af3b9d81fc2dd7fab04a3d3f18e8b923e0f310eeb3e680ae
-  data.tar.gz: ce6d621dda047bd22bbc68353f031bcc91d579f3a46c0c2e049606bf9f778fbcb9d3a0ee03d87eef5c4ac3699ba351eb2be99d60a06500c9cef3cd95c036f2d7
+  metadata.gz: 659e74f401a6ce48cac21e72bcf0b07e1c2ac2214579ed700d7715efbff9d68da082a043a5036193cd7e792d7f3a8a38a2ef6ac2780951129f1aa37781e74e8f
+  data.tar.gz: 5799dbc3570c7395545a710f2f2f8bc4bb6f5cb79a681c4a9cb862647a489070fbdc35932a474d2fdac5253f9a090087da179cfe4e6365e32a1eb5efa26d5c0f

data/.gitignore

@@ -1,3 +1,4 @@
 pkg/*
 *.gem
 .bundle
+.DS_Store

data/README.md

@@ -2,7 +2,7 @@
 
 *webloc* is a Ruby library that can read from and write to <tt>.webloc</tt> files as used on macOS. These are a variant of 'plist' format files, specifically used for storing links to URLs.
 
-It works on Ruby 2.7 and up, including Ruby 3.x, and supports URLs of up to 255 characters in length.
+It works on Ruby 2.7 and up, including Ruby 3.x, and supports URLs of up to 2048 characters in length (and probably longer, but this is around the de facto limit for URLs in most systems).
 
 ## Installation
 
@@ -10,14 +10,114 @@ It works on Ruby 2.7 and up, including Ruby 3.x, and supports URLs of up to 255
     
 ## Usage
 
+### Basic Usage
+
 Reading a .webloc file:
 
-    Webloc.load(ARGV.first).url
+    webloc = Webloc.load('bookmark.webloc')
+    puts webloc.url
+    # => "https://example.com"
 
 Writing to a .webloc file:
 
     Webloc.new('https://rubyweekly.com/').save('rubyweekly.webloc')
 
+### Advanced Examples
+
+#### Processing multiple .webloc files
+
+```ruby
+require 'webloc'
+
+Dir.glob('*.webloc').each do |file|
+  webloc = Webloc.load(file)
+  puts "#{file}: #{webloc.url}"
+end
+```
+
+#### Creating webloc files from a list of URLs
+
+```ruby
+require 'webloc'
+
+urls = [
+  'https://github.com',
+  'https://stackoverflow.com',
+  'https://ruby-lang.org'
+]
+
+urls.each_with_index do |url, index|
+  filename = "bookmark_#{index + 1}.webloc"
+  Webloc.new(url).save(filename)
+  puts "Created #{filename}"
+end
+```
+
+#### Error handling
+
+```ruby
+require 'webloc'
+
+begin
+  webloc = Webloc.load('suspicious.webloc')
+  puts webloc.url
+rescue Webloc::FileNotFoundError => e
+  puts "File not found: #{e.message}"
+rescue Webloc::CorruptedFileError => e
+  puts "File is corrupted: #{e.message}"
+rescue Webloc::InvalidFormatError => e
+  puts "Invalid file format: #{e.message}"
+rescue Webloc::WeblocError => e
+  puts "General webloc error: #{e.message}"
+end
+```
+
+#### Validating URLs before creating webloc files
+
+```ruby
+require 'webloc'
+require 'uri'
+
+def create_webloc_safely(url, filename)
+  # Basic URL validation
+  uri = URI.parse(url)
+  unless uri.is_a?(URI::HTTP) || uri.is_a?(URI::HTTPS)
+    puts "Invalid URL scheme: #{url}"
+    return false
+  end
+  
+  # Create the webloc file
+  Webloc.new(url).save(filename)
+  puts "Created #{filename} for #{url}"
+  true
+rescue URI::InvalidURIError
+  puts "Invalid URL format: #{url}"
+  false
+rescue Webloc::WeblocError => e
+  puts "Failed to create webloc: #{e.message}"
+  false
+end
+
+create_webloc_safely('https://example.com', 'example.webloc')
+create_webloc_safely('invalid-url', 'invalid.webloc')
+```
+
+#### Converting between formats
+
+```ruby
+require 'webloc'
+require 'json'
+
+# Convert webloc to JSON
+webloc = Webloc.load('bookmark.webloc')
+json_data = { url: webloc.url, title: File.basename('bookmark.webloc', '.webloc') }
+File.write('bookmark.json', JSON.pretty_generate(json_data))
+
+# Convert JSON back to webloc
+json_content = JSON.parse(File.read('bookmark.json'))
+Webloc.new(json_content['url']).save('restored.webloc')
+```
+
 ## Thanks
 
 Thanks is due to Christos Karaiskos for [this article](https://medium.com/@karaiskc/understanding-apples-binary-property-list-format-281e6da00dbd
@@ -25,6 +125,6 @@ Thanks is due to Christos Karaiskos for [this article](https://medium.com/@karai
 
 ## License
 
-Copyright (C) 2011-2024 Peter Cooper
+Copyright (C) 2011-2025 Peter Cooper
 
 webloc is licensed under the terms of the MIT License

data/lib/webloc/version.rb

@@ -1,3 +1,3 @@
 class Webloc
-  VERSION = "0.2.0"
+  VERSION = "0.3.1"
 end

data/lib/webloc.rb

@@ -1,39 +1,115 @@
 require 'plist'
 
 class Webloc
+  class WeblocError < StandardError; end
+  class FileNotFoundError < WeblocError; end
+  class CorruptedFileError < WeblocError; end
+  class InvalidFormatError < WeblocError; end
+  class EmptyFileError < WeblocError; end
+
   attr_accessor :url
 
   def initialize(url)
+    raise ArgumentError, "URL cannot be nil or empty" if url.nil? || url.empty?
     @url = url
   end
 
   def self.load(filename)
-    data = File.read(filename)
+    raise FileNotFoundError, "File not found: #{filename}" unless File.exist?(filename)
+    
+    begin
+      data = File.read(filename)
+    rescue => e
+      raise FileNotFoundError, "Unable to read file '#{filename}': #{e.message}"
+    end
+    
+    raise EmptyFileError, "File is empty: #{filename}" if data.empty?
+    
     data = data.force_encoding('binary') rescue data
+    url = nil
     
     if data !~ /\<plist/
-      offset = (data =~ /SURL_/)
-      length = data[offset + 6]
-      length = length.ord rescue length
-      url = data[offset + 7,length]  
+      # Handle binary plist format
+      url = parse_binary_format(data, filename)
     else
-      url = Plist::parse_xml(filename)['URL'] rescue nil
+      # Handle XML plist format
+      url = parse_xml_format(filename)
     end
     
-    raise ArgumentError unless url
+    raise CorruptedFileError, "No URL found in webloc file: #{filename}" if url.nil? || url.empty?
     new(url)
   end
 
+  private
+
+  def self.parse_binary_format(data, filename)
+    offset = (data =~ /SURL_/)
+    raise InvalidFormatError, "Invalid binary webloc format - missing SURL marker in file: #{filename}" unless offset
+    
+    begin
+      length_offset = 7
+      if data[offset + 5] == "\x10"
+        length = data[offset + 6]
+        length = length.unpack('C')[0]  
+      elsif data[offset + 5] == "\x11"
+        length_offset = 8
+        length = data[offset + 6] + data[offset + 7]
+        length = length.unpack('S>')[0]  
+      else
+        raise InvalidFormatError, "Unsupported length encoding in binary webloc file: #{filename}"
+      end
+      
+      raise CorruptedFileError, "Invalid URL length (#{length}) in file: #{filename}" if length <= 0 || length > data.length
+      
+      url = data[offset + length_offset, length]
+      raise CorruptedFileError, "Extracted URL is empty from file: #{filename}" if url.nil? || url.empty?
+      
+      url
+    rescue CorruptedFileError, InvalidFormatError => e
+      raise e
+    rescue => e
+      raise CorruptedFileError, "Failed to parse binary webloc format in file '#{filename}': #{e.message}"
+    end
+  end
+
+  def self.parse_xml_format(filename)
+    begin
+      plist_data = Plist::parse_xml(filename)
+      raise InvalidFormatError, "Invalid XML plist format - could not parse file: #{filename}" unless plist_data.is_a?(Hash)
+      
+      url = plist_data['URL']
+      raise CorruptedFileError, "No 'URL' key found in plist file: #{filename}" unless url
+      
+      url
+    rescue => e
+      if e.message.include?('parse') || e.message.include?('XML') || e.message.include?('plist')
+        raise InvalidFormatError, "Invalid XML plist format in file '#{filename}': #{e.message}"
+      else
+        raise CorruptedFileError, "Failed to parse XML webloc format in file '#{filename}': #{e.message}"
+      end
+    end
+  end
+
+  public
+
   def data
     # PLIST HEADER
     @data = "bplist\x30\x30".bytes
 
     # PLIST OBJECT TABLE
     @data += "\xD1\x01\x02".bytes   # object 1 is a dictionary
-    @data += "\x53URL".bytes        # object 2 is an ASCII string of length 3
-    @data += "\x5f\x10".bytes       # object 3 is an ASCII string with a variable length length encoding (I know..)
-                              #   .. the '0' in \x10 denotes the length can be encoded within 2**0 bytes (i.e. 1!)
-    @data += @url.length.chr.bytes  # and here is that one byte..
+    @data += "SURL".bytes           # object 2
+
+    length_suffix = @url.length > 255 ? "\x11" : "\x10"
+    @data += ("\x5f" + length_suffix).bytes       # object 3 is an ASCII string with a variable length length encoding (I know..)
+                              #   .. the '0' in \x10 denotes the length can be encoded within 2**0 bytes (i.e. 1)
+                              #   .. the '1' in \x11 denotes the length can be encoded within 2**1 bytes (i.e. 2)
+    
+    if @url.length > 255
+      @data += [@url.length].pack('S>').bytes
+    else
+      @data += [@url.length].pack('C').bytes
+    end
     @data += @url.bytes             # and finally the URL itself
 
     # This is the offset table
@@ -52,12 +128,18 @@ class Webloc
     # Bytes 16-23 are for an offset from the offset table
     @data += "\x00\x00\x00\x00\x00\x00\x00\x00".bytes
     # Bytes 24-31 denote the position of the offset table from the start of the file
-    @data += "\x00\x00\x00\x00\x00\x00\x00".bytes + (@url.length + 18).chr.bytes
+    @data += "\x00\x00\x00\x00\x00\x00".bytes + [@url.length + 18].pack('S>').bytes
 
     @data = @data.pack('C*')
   end
   
   def save(filename)
-    File.open(filename, 'wb') { |f| f.write data }
+    raise ArgumentError, "Filename cannot be nil or empty" if filename.nil? || filename.empty?
+    
+    begin
+      File.open(filename, 'wb') { |f| f.write data }
+    rescue => e
+      raise WeblocError, "Failed to save webloc file '#{filename}': #{e.message}"
+    end
   end
 end

data/test/webloc_test.rb

@@ -6,6 +6,16 @@ class WeblocTest < Test::Unit::TestCase
   def test_webloc_object_requires_url
     assert_raise(ArgumentError) { Webloc.new }
   end
+
+  def test_webloc_object_rejects_nil_url
+    error = assert_raise(ArgumentError) { Webloc.new(nil) }
+    assert_equal "URL cannot be nil or empty", error.message
+  end
+
+  def test_webloc_object_rejects_empty_url
+    error = assert_raise(ArgumentError) { Webloc.new("") }
+    assert_equal "URL cannot be nil or empty", error.message
+  end
   
   def test_webloc_object_created_with_url
     assert_equal 'http://example.com', Webloc.new('http://example.com').url
@@ -25,8 +35,16 @@ class WeblocTest < Test::Unit::TestCase
   end
 
   def test_webloc_can_handle_long_urls
-    url = "http://example.com/this-is-a-very-long-url-indeed-it-should-easily-go-over-110-characters-for-our-testing-purposes"
+    url = "http://example.com/this-is-a-very-long-url-abcde" + ('a' * 2000)
     assert_nothing_raised { Webloc.new(url).data }
+    file = Tempfile.new('test-long-webloc')
+    begin
+      Webloc.new(url).save(file.path)
+      assert_equal url, Webloc.load(file.path).url
+    ensure
+      file.close
+      file.unlink
+    end
   end
 
   def test_webloc_can_write_file
@@ -39,4 +57,74 @@ class WeblocTest < Test::Unit::TestCase
       file.unlink
     end    
   end
+
+  def test_load_nonexistent_file_raises_file_not_found_error
+    error = assert_raise(Webloc::FileNotFoundError) { Webloc.load('nonexistent.webloc') }
+    assert_match(/File not found: nonexistent\.webloc/, error.message)
+  end
+
+  def test_load_empty_file_raises_empty_file_error
+    file = Tempfile.new('empty-webloc')
+    begin
+      file.close
+      error = assert_raise(Webloc::EmptyFileError) { Webloc.load(file.path) }
+      assert_match(/File is empty:/, error.message)
+    ensure
+      file.unlink
+    end
+  end
+
+  def test_load_corrupted_binary_file_raises_invalid_format_error
+    file = Tempfile.new('corrupted-webloc')
+    begin
+      file.write("corrupted binary data without SURL marker")
+      file.close
+      error = assert_raise(Webloc::InvalidFormatError) { Webloc.load(file.path) }
+      assert_match(/Invalid binary webloc format - missing SURL marker/, error.message)
+    ensure
+      file.unlink
+    end
+  end
+
+  def test_load_invalid_xml_file_raises_invalid_format_error
+    file = Tempfile.new('invalid-xml-webloc')
+    begin
+      file.write("<plist><invalid>xml</invalid>")
+      file.close
+      error = assert_raise(Webloc::InvalidFormatError) { Webloc.load(file.path) }
+      assert_match(/Invalid XML plist format/, error.message)
+    ensure
+      file.unlink
+    end
+  end
+
+  def test_load_xml_without_url_key_raises_invalid_format_error
+    file = Tempfile.new('no-url-xml-webloc')
+    begin
+      file.write('<?xml version="1.0"?><plist><dict><key>NotURL</key><string>value</string></dict></plist>')
+      file.close
+      error = assert_raise(Webloc::InvalidFormatError) { Webloc.load(file.path) }
+      assert_match(/No 'URL' key found in plist file/, error.message)
+    ensure
+      file.unlink
+    end
+  end
+
+  def test_save_with_nil_filename_raises_argument_error
+    webloc = Webloc.new('http://example.com')
+    error = assert_raise(ArgumentError) { webloc.save(nil) }
+    assert_equal "Filename cannot be nil or empty", error.message
+  end
+
+  def test_save_with_empty_filename_raises_argument_error
+    webloc = Webloc.new('http://example.com')
+    error = assert_raise(ArgumentError) { webloc.save("") }
+    assert_equal "Filename cannot be nil or empty", error.message
+  end
+
+  def test_save_to_invalid_path_raises_webloc_error
+    webloc = Webloc.new('http://example.com')
+    error = assert_raise(Webloc::WeblocError) { webloc.save('/invalid/path/that/does/not/exist/file.webloc') }
+    assert_match(/Failed to save webloc file/, error.message)
+  end
 end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: webloc
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.1
 platform: ruby
 authors:
 - Peter Cooper
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-01-26 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: plist
@@ -45,7 +44,6 @@ files:
 homepage: https://github.com/peterc/webloc
 licenses: []
 metadata: {}
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -60,8 +58,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.22
-signing_key:
+rubygems_version: 3.6.7
 specification_version: 4
 summary: Reads and writes .webloc files on macOS
 test_files: