imap-backup 14.4.4 → 14.4.5

data/lib/imap/backup/serializer/transaction.rb

@@ -1,15 +1,23 @@
 module Imap; end
 
 module Imap::Backup
+  # Stores data during a transaction
   class Serializer::Transaction
+    # @return the transaction's stored data
     attr_reader :data
 
+    # @param owner [any] the class using the transaction -
+    #   this is used when raising errors
     def initialize(owner:)
       @data = nil
       @owner = owner
       @in_transaction = false
     end
 
+    # Runs the transaction
+    # @param data [any] the data to maintain during the transaction
+    # @param block [block] the block to wrap with the transaction
+    # @return [void]
     def begin(data, &block)
       @data = data
       @in_transaction = true
@@ -17,6 +25,8 @@ module Imap::Backup
       @in_transaction = false
     end
 
+    # Clears rollback data
+    # @return [void]
     def clear
       @data = nil
     end
@@ -25,10 +35,18 @@ module Imap::Backup
       @in_transaction
     end
 
+    # Throws an exception if there is a current transaction
+    # @param method [Symbol] the method where the check is run
+    # @raise [RuntimeError] if called from inside a transaction
+    # @return [void]
     def fail_in_transaction!(method, message: "not supported inside trasactions")
       raise "#{owner.class}##{method} #{message}" if in_transaction?
     end
 
+    # Throws an exception if there is not a current transaction
+    # @param method [Symbol] the method where the check is run
+    # @raise [RuntimeError] if called from outside a transaction
+    # @return [void]
     def fail_outside_transaction!(method)
       raise "#{owner.class}##{method} can only be called inside a transaction" if !in_transaction?
     end

data/lib/imap/backup/serializer/unused_name_finder.rb

@@ -3,11 +3,15 @@ require "imap/backup/serializer"
 module Imap; end
 
 module Imap::Backup
+  # Finds a name that can be used to rename a serialized folder
   class Serializer::UnusedNameFinder
+    # @param serializer [Serializer] a folder serializer
     def initialize(serializer:)
       @serializer = serializer
     end
 
+    # Finds the name
+    # @return [String] the name
     def run
       digit = 0
       folder = nil

data/lib/imap/backup/serializer/version2_migrator.rb

@@ -5,7 +5,9 @@ require "imap/backup/serializer/imap"
 module Imap; end
 
 module Imap::Backup
+  # Migrates serialized folder metadata from the version 2 format to the version 3 format
   class Serializer::Version2Migrator
+    # @param folder_path [String] the base pathv(without extension) of the folder backup
     def initialize(folder_path)
       @folder_path = folder_path
     end
@@ -21,6 +23,8 @@ module Imap::Backup
       true
     end
 
+    # Runs the migration
+    # @return [Boolean] whether the migration was run
     def run
       return false if !required?
 

data/lib/imap/backup/serializer.rb

@@ -15,7 +15,11 @@ require "imap/backup/serializer/unused_name_finder"
 module Imap; end
 
 module Imap::Backup
+  # Handles serialization for a folder
   class Serializer
+    # @param path [String] an account's backup path
+    # @param folder [String] a folder name
+    # @return [String] the full path to a serialized folder (without file extensions)
     def self.folder_path_for(path:, folder:)
       relative = File.join(path, folder)
       File.expand_path(relative)
@@ -26,9 +30,13 @@ module Imap::Backup
     def_delegator :mbox, :pathname, :mbox_pathname
     def_delegators :imap, :get, :messages, :uid_validity, :uids, :update_uid
 
+    # @return [String] a folder name
     attr_reader :folder
+    # @return [String] an account's backup path
     attr_reader :path
 
+    # @param path [String] an account's backup path
+    # @param folder [String] a folder name
     def initialize(path, folder)
       @path = path
       @folder = folder
@@ -38,14 +46,17 @@ module Imap::Backup
     # Calls the supplied block.
     # This method is present so that this class implements the same
     # interface as {DelayedMetadataSerializer}
+    # @param block [block] the block that is wrapped by the transaction
     #
     # @return [void]
     def transaction(&block)
       block.call
     end
 
-    # Returns true if there are existing, valid files
-    # false otherwise (in which case any existing files are deleted)
+    # Checks that the metadata files are valid, migrates the metadata file
+    # from older versions, if necessary,
+    # or deletes any existing files if the pair are not valid.
+    # @return [Boolean] indicates whether there are existing, valid files
     def validate!
       return true if @validated
 
@@ -61,16 +72,33 @@ module Imap::Backup
       false
     end
 
+    # Checks that the folder's data is stored correctly
+    # @return [void]
     def check_integrity!
       IntegrityChecker.new(imap: imap, mbox: mbox).run
     end
 
+    # Deletes the serialized data
+    # @return [void]
     def delete
       imap.delete
       mbox.delete
       reload
     end
 
+    # Sets the folder's UID validity.
+    # If the existing value is nil, it sets the new value
+    # and ensures that both the metadata file and the mailbox
+    # are saved.
+    # If the supplied value is the same as the existing value,
+    # it does nothing.
+    # If the supplied valued is *different* to the existing value,
+    # it renames the existing folder to a new name, and creates a
+    # new folder with the supplied value.
+    #
+    # @param value [Integer] The new UID validity value
+    #
+    # @return [String, nil] The name of the new folder
     def apply_uid_validity(value)
       validate!
 
@@ -86,12 +114,22 @@ module Imap::Backup
       end
     end
 
+    # Overwrites the UID validity of the folder
+    # and ensures that both the metadata file and the mailbox
+    # are saved.
+    # @param value [Integer] the new UID validity
+    # @return [void]
     def force_uid_validity(value)
       validate!
 
       internal_force_uid_validity(value)
     end
 
+    # Appends a message to the serialized data
+    # @param uid [Integer] the message's UID
+    # @param message [Integer] the message text
+    # @param flags [Array[Symbol]] the message's flags
+    # @return [void]
     def append(uid, message, flags)
       validate!
 
@@ -99,6 +137,10 @@ module Imap::Backup
       appender.append(uid: uid, message: message, flags: flags)
     end
 
+    # Updates a messages flags
+    # @param uid [Integer] the message's UID
+    # @param flags [Array<Symbol>] the flags to set on the message
+    # @return [void]
     def update(uid, flags: nil)
       message = imap.get(uid)
       return if !message
@@ -107,6 +149,10 @@ module Imap::Backup
       imap.save
     end
 
+    # Enumerates over a series of messages.
+    # When called without a block, returns an Enumerator
+    # @param required_uids [Array<Integer>] the UIDs of the message to enumerate over
+    # @return [Enumerator, void]
     def each_message(required_uids = nil, &block)
       return enum_for(:each_message, required_uids) if !block
 
@@ -118,6 +164,10 @@ module Imap::Backup
       enumerator.run(uids: required_uids, &block)
     end
 
+    # Calls the supplied block on each message in the folder
+    # and discards those for which the block returns a false result
+    # @param block [block] the block to call
+    # @return [void]
     def filter(&block)
       temp_name = Serializer::UnusedNameFinder.new(serializer: self).run
       temp_folder_path = self.class.folder_path_for(path: path, folder: temp_name)
@@ -137,14 +187,18 @@ module Imap::Backup
       reload
     end
 
+    # @return [String] the path to the serialized folder (without file extensions)
     def folder_path
       self.class.folder_path_for(path: path, folder: sanitized)
     end
 
+    # @return [String] The folder's name adapted for using as a file name
     def sanitized
       @sanitized ||= Naming.to_local_path(folder)
     end
 
+    # Forces a reload of the serialized files
+    # @return [void]
     def reload
       @imap = nil
       @mbox = nil

data/lib/imap/backup/setup/account/header.rb

@@ -8,12 +8,18 @@ module Imap::Backup
   class Setup; end
   class Setup::Account; end
 
+  # Displays the header to the account modification menu
   class Setup::Account::Header
+    # @param menu [Highline::Menu] the menu
+    # @param account [Account] an Account
     def initialize(menu:, account:)
       @menu = menu
       @account = account
     end
 
+    # Displays the header
+    #
+    # @return [void]
     def run
       rows = [
         email,

data/lib/imap/backup/setup/account.rb

@@ -10,13 +10,19 @@ module Imap; end
 module Imap::Backup
   class Setup; end
 
+  # Handles interactive account setup
   class Setup::Account
+    # @param config [Configuration] the application configuration
+    # @param account [Account] an Account
+    # @param highline [Higline] the configured Highline instance
     def initialize(config, account, highline)
       @account = account
       @config = config
       @highline = highline
     end
 
+    # Shows the menu
+    # @return [void]
     def run
       if !account.local_path
         account.local_path = File.join(config.path, account.username.tr("@", "_"))

data/lib/imap/backup/setup/asker.rb

@@ -3,11 +3,17 @@ module Imap; end
 module Imap::Backup
   class Setup; end
 
+  # Implements interactively requesting information from the user
   class Setup::Asker
+    # @param highline [Higline] the configured Highline instance
     def initialize(highline)
       @highline = highline
     end
 
+    # Asks for a email address
+    #
+    # @param default [String] the existing email address
+    # @return [String] the email address
     def email(default = "")
       highline.ask("email address: ") do |q|
         q.default               = default
@@ -16,6 +22,9 @@ module Imap::Backup
       end
     end
 
+    # Asks for a password
+    #
+    # @return [String] the password
     def password
       password     = highline.ask("password: ")        { |q| q.echo = false }
       confirmation = highline.ask("repeat password: ") { |q| q.echo = false }
@@ -29,10 +38,17 @@ module Imap::Backup
       password
     end
 
+    # Asks for a email address using the configured menu handler
+    #
+    # @param default [String] the existing email address
+    # @return [String] the email address
     def self.email(default = "")
       new(Setup.highline).email(default)
     end
 
+    # Asks for a password using the configured menu handler
+    #
+    # @return [String] the password
     def self.password
       new(Setup.highline).password
     end

data/lib/imap/backup/setup/backup_path.rb

@@ -3,12 +3,18 @@ module Imap; end
 module Imap::Backup
   class Setup; end
 
+  # Requests an updated backup path from the user
   class Setup::BackupPath
+    # @param account [Account] an Account
+    # @param config [Configuration] the application configuration
     def initialize(account:, config:)
       @account = account
       @config = config
     end
 
+    # Asks the user for a backup path
+    #
+    # @return [void]
     def run
       account.local_path = highline.ask("backup directory: ") do |q|
         q.default  = account.local_path

data/lib/imap/backup/setup/connection_tester.rb

@@ -5,11 +5,16 @@ module Imap; end
 module Imap::Backup
   class Setup; end
 
+  # Attempts to login to an account and reports the result
   class Setup::ConnectionTester
+    # @param account [Account] an Account
     def initialize(account)
       @account = account
     end
 
+    # Carries out the attempted login and indicates
+    # whether it was successful
+    # @return [void]
     def test
       account.client.login
       "Connection successful"

data/lib/imap/backup/setup/email_changer.rb

@@ -6,12 +6,18 @@ module Imap; end
 module Imap::Backup
   class Setup; end
 
+  # Asks the user for a new email address
   class Setup::EmailChanger
+    # @param account [Account] an Account
+    # @param config [Configuration] the application configuration
     def initialize(account:, config:)
       @account = account
       @config = config
     end
 
+    # Asks the user for an email address,
+    # ensuring that the supplied address is not an existing account
+    # @return [void]
     def run
       username = Setup::Asker.email(account.username)
       other_accounts = config.accounts.reject { |a| a == account }

data/lib/imap/backup/setup/folder_chooser.rb

@@ -5,11 +5,15 @@ module Imap; end
 module Imap::Backup
   class Setup; end
 
+  # Allows the user to select and deselect folders to be backed up
   class Setup::FolderChooser
+    # @param account [Account] an Account
     def initialize(account)
       @account = account
     end
 
+    # Lists account folders and allows the user to toggle whther they are selected
+    # @return [void]
     def run
       if client.nil?
         highline.ask "Press a key "

data/lib/imap/backup/setup/global_options/download_strategy_chooser.rb

@@ -5,11 +5,15 @@ module Imap::Backup; end
 class Imap::Backup::Setup; end
 
 class Imap::Backup::Setup::GlobalOptions
+  # Allows changing the globally configured download strategy
   class DownloadStrategyChooser
+    # @param config [Configuration] the application configuration
     def initialize(config:)
       @config = config
     end
 
+    # Shows the menu
+    # @return [void]
     def run
       catch :done do
         loop do

data/lib/imap/backup/setup/global_options.rb

@@ -6,11 +6,15 @@ module Imap; end
 module Imap::Backup
   class Setup; end
 
+  # Shows the menu of global options
   class Setup::GlobalOptions
+    # @param config [Configuration] the application configuration
     def initialize(config:)
       @config = config
     end
 
+    # Shows the menu
+    # @return [void]
     def run
       catch :done do
         loop do

data/lib/imap/backup/setup/helpers.rb

@@ -5,11 +5,14 @@ module Imap; end
 module Imap::Backup
   class Setup; end
 
+  # Helpers for the setup system
   class Setup::Helpers
+    # @return [String] the prefix for setup menus
     def title_prefix
       "imap-backup -"
     end
 
+    # @return [String] the current application version
     def version
       VERSION
     end

data/lib/imap/backup/setup.rb

@@ -10,16 +10,21 @@ require "imap/backup/setup/helpers"
 module Imap; end
 
 module Imap::Backup
+  # Interactively updates the application's configuration file
   class Setup
     class << self
+      # @return [Highline]
       attr_accessor :highline
     end
     self.highline = HighLine.new
 
+    # @param config [Configuration] the application configuration
     def initialize(config:)
       @config = config
     end
 
+    # Shows the menu
+    # @return [void]
     def run
       catch :done do
         loop do

data/lib/imap/backup/text/sanitizer.rb

@@ -5,17 +5,24 @@ module Imap; end
 module Imap::Backup
   module Text; end
 
+  # Wraps standard output and hides passwords from debug output
+  # Any text matching Net::IMAP debug output of passwords is sanitized
   class Text::Sanitizer
     extend Forwardable
 
     delegate puts: :output
     delegate write: :output
 
+    # @param output [IO] the stream to write output to
     def initialize(output)
       @output = output
       @current = ""
     end
 
+    # Outputs everything up to the last newline character,
+    # storing whatever follows the newline.
+    # @param args [Array<String>] lines of text
+    # @return [void]
     def print(*args)
       @current << args.join
       loop do
@@ -28,6 +35,8 @@ module Imap::Backup
       end
     end
 
+    # Outputs any text still not printed
+    # @return [void]
     def flush
       return if @current == ""
 

data/lib/imap/backup/thunderbird/mailbox_exporter.rb

@@ -7,7 +7,11 @@ module Imap; end
 module Imap::Backup
   class Thunderbird; end
 
+  # Exports an account's emails to Thunderbird
   class Thunderbird::MailboxExporter
+    # @param email [String] an email address
+    # @param serializer [Serializer] a local folder backup
+    # @param profile [Thunderbird::Profile] an existing Thunderbird profile
     def initialize(email, serializer, profile, force: false)
       @email = email
       @serializer = serializer
@@ -15,6 +19,9 @@ module Imap::Backup
       @force = force
     end
 
+    # Copies the account's messages to the Thunderbird directory
+    # in the format expected by Thunderbird
+    # @return [void]
     def run
       if !profile_set_up
         error "The Thunderbird profile '#{profile.title}' " \

data/lib/imap/backup/uploader.rb

@@ -5,12 +5,17 @@ require "imap/backup/serializer"
 module Imap; end
 
 module Imap::Backup
+  # Uploads a backed-up folder
   class Uploader
+    # @param folder [Account::Folder] an online folder
+    # @param serializer [Serializer] a local folder backup
     def initialize(folder, serializer)
       @folder = folder
       @serializer = serializer
     end
 
+    # Uploads messages that are present in the backup, but not in the online folder
+    # @return [void]
     def run
       if folder.uids.any?
         rename_serialized_folder

data/lib/imap/backup/version.rb

@@ -1,9 +1,14 @@
 module Imap; end
 
 module Imap::Backup
+  # @private
   MAJOR    = 14
+  # @private
   MINOR    = 4
-  REVISION = 4
+  # @private
+  REVISION = 5
+  # @private
   PRE      = nil
+  # The application version
   VERSION  = [MAJOR, MINOR, REVISION, PRE].compact.map(&:to_s).join(".")
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: imap-backup
 version: !ruby/object:Gem::Version
-  version: 14.4.4
+  version: 14.4.5
 platform: ruby
 authors:
 - Joe Yates
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-11-17 00:00:00.000000000 Z
+date: 2023-11-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: highline
@@ -133,10 +133,8 @@ files:
 - LICENSE
 - README.md
 - bin/imap-backup
-- docs/api.md
 - docs/delimiters-and-prefixes.md
-- docs/development.md
-- docs/migrate-server-keep-address.md
+- docs/documentation.md
 - docs/performance.md
 - imap-backup.gemspec
 - lib/imap/backup/account.rb

data/docs/api.md

@@ -1,20 +0,0 @@
-# @title Index
-# imap-backup API Documentation
-
-![Version](https://img.shields.io/gem/v/imap-backup?label=Version&logo=rubygems)
-[![Build Status](https://github.com/joeyates/imap-backup/actions/workflows/main.yml/badge.svg)][CI Status]
-![Coverage](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/joeyates/b54fe758bfb405c04bef72dad293d707/raw/coverage.json)
-![License](https://img.shields.io/github/license/joeyates/imap-backup?color=brightgreen&label=License)
-[![Stars](https://img.shields.io/github/stars/joeyates/imap-backup?style=social)][GitHub Stars]
-
-[CI Status]: https://github.com/joeyates/imap-backup/actions/workflows/main.yml
-[GitHub Stars]: https://github.com/joeyates/imap-backup/stargazers "GitHub Stars"
-
-This is the developer documentation for imap-backup's **code**.
-
-Usage documentation is on [GitHub](https://github.com/joeyates/imap-backup).
-
-You can get an overview of the program's structure from the
-{file:ARCHITECTURE.md ARCHITECTURE} file.
-
-The {file:CHANGELOG.md CHANGELOG} has a history of the changes to the program.