webloc

webloc is a Ruby library that can read from and write to .webloc files as used on macOS. These are a variant of 'plist' format files, specifically used for storing links to URLs.

It works on Ruby 3.0 and up (including Ruby 4.0.2 and TruffleRuby). It reads XML and binary plist files and writes binary plist files, supporting Unicode and URLs longer than 65,535 characters.

Installation

gem install webloc

Usage

Basic Usage

Reading a .webloc file:

require 'webloc'
webloc = Webloc.load('bookmark.webloc')
puts webloc.url
# => "https://example.com"

Writing to a .webloc file:

require 'webloc'
Webloc.new('https://rubyweekly.com/').save('rubyweekly.webloc')

Advanced Examples

Error handling

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

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

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')

Compatibility

The public methods and error classes are unchanged. The reader also recovers historical long-URL files with the known offset bugs. New writes correct those offsets; short ASCII URLs retain their original binary encoding. Binary reading supports short URLs, additional metadata, and different object orders. URLs are stored as supplied, without escaping or scheme validation. Unicode strings use UTF-16 in binary files and are returned as UTF-8 when read.

Malformed files without a recoverable historical layout raise a WeblocError subclass instead of returning a partial URL.

Development

Run bundle install followed by bundle exec rake test.

The suite retains the original tests and fixtures and exercises the Ruby examples in this README. Additional fixtures cover other binary layouts and files written by older releases. Interoperability tests use Python 3's plistlib when available and Apple's plutil on macOS; neither is a runtime dependency of the gem.

Thanks

Thanks is due to Christos Karaiskos for this article which helped me understand the plist format a bit more when fixing a bug in 2024.

License

Copyright (C) 2011-2026 Peter Cooper

webloc is licensed under the terms of the MIT License