yobi 0.3.1 → 1.1.0

data/lib/yobi/repository/cat.rb

@@ -2,52 +2,41 @@
 
 module Yobi
   class Repository
-    # `restic cat config`: the repository's own config document.
-    #
-    # @return [Hash]
-    # @raise [Yobi::RepositoryNotFound, Yobi::AuthenticationFailed]
+    # +restic cat config+: the repository's own config document, as a Hash.
+    # Raises Yobi::RepositoryNotFound or Yobi::AuthenticationFailed.
     def cat_config
       execution = run_restic(build_argv("cat", "config"))
       parse_json_output(execution)
     end
     alias_method :config, :cat_config
 
-    # `restic cat snapshot ID`: one snapshot's own raw stored record.
-    #
-    # @param id [String, Yobi::Snapshot]
-    # @return [Hash]
+    # +restic cat snapshot ID+: one snapshot's own raw stored record, as a
+    # Hash. +id+ can be a String or a Yobi::Snapshot.
     def cat_snapshot(id)
       id = id.id if id.is_a?(Yobi::Snapshot)
       execution = run_restic(build_argv("cat", "snapshot", id))
       parse_json_output(execution)
     end
 
-    # `restic cat index ID`: one index file's own raw contents. IDs come
-    # from `list(:index)`.
-    #
-    # @param id [String]
-    # @return [Hash]
+    # +restic cat index ID+: one index file's own raw contents, as a Hash.
+    # IDs come from +list(:index)+.
     def cat_index(id)
       execution = run_restic(build_argv("cat", "index", id))
       parse_json_output(execution)
     end
 
-    # `restic cat key ID`: one key's own raw stored record.
-    #
-    # @param id [String, Yobi::Key]
-    # @return [Hash]
+    # +restic cat key ID+: one key's own raw stored record, as a Hash. +id+
+    # can be a String or a Yobi::Key.
     def cat_key(id)
       id = id.id if id.is_a?(Yobi::Key)
       execution = run_restic(build_argv("cat", "key", id))
       parse_json_output(execution)
     end
 
-    # `restic cat tree snapshot:subfolder`: the raw tree object at a
-    # snapshot's root, or at `subfolder` within it.
-    #
-    # @param snapshot_id [String, Yobi::Snapshot] also accepts Restic's own `"snapshotID:subfolder"` form directly
-    # @param subfolder [String, nil]
-    # @return [Hash]
+    # +restic cat tree snapshot:subfolder+: the raw tree object at a
+    # snapshot's root, or at +subfolder+ within it. +snapshot_id+ can be a
+    # String, a Yobi::Snapshot, or Restic's own +"snapshotID:subfolder"+
+    # form directly.
     def cat_tree(snapshot_id, subfolder: nil)
       snapshot_id = snapshot_id.id if snapshot_id.is_a?(Yobi::Snapshot)
       target = if subfolder.nil?
@@ -59,34 +48,25 @@ module Yobi
       parse_json_output(execution)
     end
 
-    # `restic cat pack ID`: one pack file's raw, still-encrypted bytes.
-    # IDs come from `list(:packs)`. Same block/handle shape as {#dump}.
-    #
-    # @param id [String]
-    # @yieldparam io [IO]
-    # @return [Yobi::IOHandle] if no block is given
+    # +restic cat pack ID+: one pack file's raw, still-encrypted bytes. IDs
+    # come from +list(:packs)+. Same block/handle shape as #dump: without a
+    # block, returns a Yobi::IOHandle.
     def cat_pack(id, &block)
       run_restic_dump(build_argv("cat", "pack", id), &block)
     end
 
-    # `restic cat blob ID`: one data blob's raw, decrypted bytes. IDs come
-    # from {#cat_tree}'s own node `"content"` arrays. Same block/handle
-    # shape as {#dump}.
-    #
-    # @param id [String]
-    # @yieldparam io [IO]
-    # @return [Yobi::IOHandle] if no block is given
+    # +restic cat blob ID+: one data blob's raw, decrypted bytes. IDs come
+    # from #cat_tree's own node +"content"+ arrays. Same block/handle shape
+    # as #dump.
     def cat_blob(id, &block)
       run_restic_dump(build_argv("cat", "blob", id), &block)
     end
 
-    # `restic cat masterkey`: this repository's own encryption/MAC key
-    # material. Extremely sensitive: this is the actual key, not a
-    # redacted reference to it, and there is no operation that rotates it;
-    # every other key/password management method here only manages
-    # different ways to unlock this same master key.
-    #
-    # @return [Hash]
+    # +restic cat masterkey+: this repository's own encryption/MAC key
+    # material. Extremely sensitive: this is the actual key, not a redacted
+    # reference to it, and there is no operation that rotates it; every
+    # other key/password management method here only manages different ways
+    # to unlock this same master key.
     def cat_masterkey_and_game_over_if_this_leaks
       execution = run_restic(build_argv("cat", "masterkey"))
       parse_json_output(execution)

data/lib/yobi/repository/check.rb

@@ -2,15 +2,16 @@
 
 module Yobi
   class Repository
-    # `restic check`: tests the repository for errors.
+    # +restic check+: tests the repository for errors.
     #
-    # @param hosts [Array<String>, String] filter by hostname(s)
-    # @param paths [Array<String>, String] filter by originally backed-up path(s)
-    # @param read_data [Boolean] read and verify pack file contents, not just structure
-    # @param read_data_subset [String, nil] read and verify only a subset of packs, e.g. `"5%"`
-    # @param tags [Array<String>, String] filter by tag(s)
-    # @param with_cache [Boolean] use the local cache
-    # @return [Yobi::CheckOutcome]
+    # +hosts:+, +paths:+ and +tags:+ each accept a single value or an Array
+    # to filter by.
+    #
+    # +read_data:+ reads and verifies pack file contents, not just structure.
+    # +read_data_subset:+ narrows that to a subset of packs, e.g. +"5%"+.
+    # +with_cache:+ uses the local cache.
+    #
+    # Returns a Yobi::CheckOutcome.
     def check(hosts: [], paths: [], read_data: false, read_data_subset: nil, tags: [], with_cache: false)
       argv = build_argv("check") do |a|
         a.repeat_flag(:host, hosts)
@@ -26,16 +27,7 @@ module Yobi
     end
   end
 
-  # Classifies a raw check message Hash by its own message_type, wrapping
-  # it in the matching typed class. Used both as the {Yobi::ResticOutput}
-  # `transform:` for {Yobi::Repository#check} and by {Yobi::CheckOutcome}'s
-  # own post-hoc accessors.
-  #
-  # @private
-  module CheckMessageWrapper
-    # @param raw [Hash]
-    # @return [Yobi::CheckError, Yobi::CheckSummary, Hash]
-    #   the raw Hash itself for a message_type this version of Yobi doesn't recognize
+  module CheckMessageWrapper # :nodoc:
     def self.call(raw)
       case raw["message_type"]
       when "error" then CheckError.new(raw)
@@ -45,28 +37,26 @@ module Yobi
     end
   end
 
-  # The outcome of one {Yobi::Repository#check} call.
+  # The outcome of one Yobi::Repository#check call.
   class CheckOutcome
-    # @return [Yobi::ResticOutput]
+    # The Yobi::ResticOutput backing this outcome.
     attr_reader :output
 
-    # @private
-    def initialize(execution)
+    def initialize(execution) # :nodoc:
       @output = execution[:output]
     end
 
-    # @return [Yobi::CheckSummary] Restic's own `"summary"` fields
+    # The Yobi::CheckSummary of Restic's own +"summary"+ fields.
     def summary
       @summary ||= output.messages("summary").first || CheckSummary.new({})
     end
     alias_method :report, :summary
 
-    # @return [Enumerable<Yobi::CheckError>]
+    # Every Yobi::CheckError from the run.
     def errors
       @errors ||= output.messages("error")
     end
 
-    # @return [void]
     def pretty_print(q)
       q.object_group(self) do
         q.breakable
@@ -77,34 +67,31 @@ module Yobi
     end
   end
 
-  # One `"error"` message from a check run.
-  # https://restic.readthedocs.io/en/stable/075_scripting.html#error
+  # One +"error"+ message from a check run.
   class CheckError < Yobi::FancyHash
-    # @return [String]
     def message
       self["message"]
     end
   end
 
-  # The `"summary"` message from a check run, the final result once the
-  # command finishes. Dispatched to {Yobi::CheckOutcome#summary}.
+  # The +"summary"+ message from a check run, the final result once the
+  # command finishes. Dispatched to Yobi::CheckOutcome#summary.
   class CheckSummary < Yobi::FancyHash
-    # @return [Integer]
     def num_errors
       self["num_errors"] || 0
     end
 
-    # @return [Array<String>] pack IDs needing `repair_packs`/`repair_snapshots`
+    # Pack IDs needing #repair_packs / #repair_snapshots.
     def broken_packs
       self["broken_packs"] || []
     end
 
-    # @return [Boolean] whether to run {Yobi::Repository#repair_index}
+    # Whether to run Yobi::Repository#repair_index.
     def suggest_repair_index?
       self["suggest_repair_index"]
     end
 
-    # @return [Boolean] whether to run {Yobi::Repository#prune}
+    # Whether to run Yobi::Repository#prune.
     def suggest_prune?
       self["suggest_prune"]
     end

data/lib/yobi/repository/copy.rb

@@ -2,20 +2,18 @@
 
 module Yobi
   class Repository
-    # `restic copy`: replicates snapshots from another repository into
-    # this one. Already-copied snapshots are skipped automatically.
+    # +restic copy+: replicates snapshots from another repository into this
+    # one. Already-copied snapshots are skipped automatically.
     #
-    # @param from_repo [String, Yobi::Repository, Array] the source repository's
-    #   URL; a `Repository` instance (its own `#url`/`#password` are used
-    #   automatically); or a `[:file, "..."]` tuple reading the URL from a file
-    # @param from_password [String, Array, Symbol, #call, nil] the source
-    #   repository's password, same shape as {#initialize}'s `password:`
-    # @param snapshot_ids [Array<String>, String] snapshots to copy; all of them if empty
-    # @param from_key_hint [String, nil]
-    # @param hosts [Array<String>, String] filter by hostname(s)
-    # @param paths [Array<String>, String] filter by originally backed-up path(s)
-    # @param tags [Array<String>, String] filter by tag(s)
-    # @return [true]
+    # +from_repo:+ is the source repository's URL, a Yobi::Repository (its
+    # own #url/#password are used automatically), or a +[:file, "..."]+
+    # tuple reading the URL from a file. +from_password:+ takes the same
+    # shape as #initialize's +password:+, and defaults to the source
+    # Repository's own password when +from_repo:+ is one.
+    #
+    # +snapshot_ids:+ names the snapshots to copy; all of them if empty.
+    # +hosts:+, +paths:+, and +tags:+ each accept a single value or an
+    # Array to filter by.
     def copy(from_repo:, from_password: nil, snapshot_ids: [], from_key_hint: nil, hosts: [], paths: [], tags: [])
       from_repo_flag, from_repo_value = resolved_from_repo_flag(from_repo)
       from_password = from_repo_password(from_repo) if from_password.nil?

data/lib/yobi/repository/diff.rb

@@ -2,12 +2,9 @@
 
 module Yobi
   class Repository
-    # `restic diff`: compares two snapshots.
-    #
-    # @param from [String] snapshot ID
-    # @param to [String] snapshot ID
-    # @param metadata [Boolean] also report metadata-only changes (access mode, timestamps, ...)
-    # @return [Yobi::DiffOutcome]
+    # +restic diff+: compares two snapshots, +from:+ and +to:+ (both
+    # snapshot IDs). +metadata: true+ also reports metadata-only changes
+    # (access mode, timestamps, ...). Returns a Yobi::DiffOutcome.
     def diff(from:, to:, metadata: false)
       argv = build_argv("diff", from, to) do |a|
         a.flag(:metadata) if metadata
@@ -18,16 +15,7 @@ module Yobi
     end
   end
 
-  # Classifies a raw diff message Hash by its own message_type, wrapping
-  # it in the matching typed class. Used both as the {Yobi::ResticOutput}
-  # `transform:` for {Yobi::Repository#diff} and by {Yobi::DiffOutcome}'s
-  # own post-hoc accessors.
-  #
-  # @private
-  module DiffMessageWrapper
-    # @param raw [Hash]
-    # @return [Yobi::DiffChange, Yobi::DiffStatistics, Hash]
-    #   the raw Hash itself for a message_type this version of Yobi doesn't recognize
+  module DiffMessageWrapper # :nodoc:
     def self.call(raw)
       case raw["message_type"]
       when "change" then DiffChange.new(raw)
@@ -37,28 +25,26 @@ module Yobi
     end
   end
 
-  # The outcome of one {Yobi::Repository#diff} call.
+  # The outcome of one Yobi::Repository#diff call.
   class DiffOutcome
-    # @return [Yobi::ResticOutput]
+    # The Yobi::ResticOutput backing this outcome.
     attr_reader :output
 
-    # @private
-    def initialize(execution)
+    def initialize(execution) # :nodoc:
       @output = execution[:output]
     end
 
-    # @return [Yobi::DiffStatistics] Restic's own `"statistics"` fields
+    # The Yobi::DiffStatistics of Restic's own +"statistics"+ fields.
     def statistics
       @statistics ||= output.messages("statistics").first || DiffStatistics.new({})
     end
     alias_method :report, :statistics
 
-    # @return [Enumerable<Yobi::DiffChange>]
+    # Every Yobi::DiffChange from the run.
     def changes
       @changes ||= output.messages("change")
     end
 
-    # @return [void]
     def pretty_print(q)
       q.object_group(self) do
         q.breakable
@@ -67,109 +53,92 @@ module Yobi
     end
   end
 
-  # One `"change"` message from a diff run. `modifier` is Restic's own
-  # concatenation of single-character codes: `"+"` added, `"-"` removed,
-  # `"U"` metadata updated, `"M"` content modified, `"T"` type changed,
-  # `"?"` bitrot detected.
+  # One +"change"+ message from a diff run. #modifier is Restic's own
+  # concatenation of single-character codes: +"+"+ added, +"-"+ removed,
+  # +"U"+ metadata updated, +"M"+ content modified, +"T"+ type changed,
+  # +"?"+ bitrot detected.
   class DiffChange < Yobi::FancyHash
-    # @return [String]
     def path
       self["path"]
     end
 
-    # @return [String]
     def modifier
       self["modifier"]
     end
 
-    # @return [Boolean]
     def added?
       modifier.include?("+")
     end
 
-    # @return [Boolean]
     def removed?
       modifier.include?("-")
     end
 
-    # @return [Boolean]
     def type_changed?
       modifier.include?("T")
     end
 
-    # @return [Boolean]
     def modified?
       modifier.include?("M")
     end
 
-    # @return [Boolean]
     def metadata_updated?
       modifier.include?("U")
     end
 
-    # @return [Boolean]
     def bitrot?
       modifier.include?("?")
     end
   end
 
-  # The `"statistics"` message from a diff run, the final result once the
-  # command finishes. Dispatched to {Yobi::DiffOutcome#statistics}.
+  # The +"statistics"+ message from a diff run, the final result once the
+  # command finishes. Dispatched to Yobi::DiffOutcome#statistics.
   class DiffStatistics < Yobi::FancyHash
-    # @return [String, nil]
     def source_snapshot
       self["source_snapshot"]
     end
 
-    # @return [String, nil]
     def target_snapshot
       self["target_snapshot"]
     end
 
-    # @return [Integer]
     def changed_files
       self["changed_files"] || 0
     end
 
-    # @return [Yobi::DiffStat]
+    # A Yobi::DiffStat of what was added.
     def added
       @added ||= DiffStat.new(self["added"] || {})
     end
 
-    # @return [Yobi::DiffStat]
+    # A Yobi::DiffStat of what was removed.
     def removed
       @removed ||= DiffStat.new(self["removed"] || {})
     end
   end
 
-  # The `"added"`/`"removed"` sub-object of a {Yobi::DiffStatistics} message.
+  # The +"added"+ / +"removed"+ sub-object of a Yobi::DiffStatistics message.
   class DiffStat < Yobi::FancyHash
-    # @return [Integer]
     def files
       self["files"] || 0
     end
 
-    # @return [Integer]
     def dirs
       self["dirs"] || 0
     end
 
-    # @return [Integer]
     def others
       self["others"] || 0
     end
 
-    # @return [Integer]
     def data_blobs
       self["data_blobs"] || 0
     end
 
-    # @return [Integer]
     def tree_blobs
       self["tree_blobs"] || 0
     end
 
-    # @return [Integer]
     def bytes
       self["bytes"] || 0
     end

data/lib/yobi/repository/dump.rb

@@ -4,24 +4,23 @@ require "tempfile"
 
 module Yobi
   class Repository
-    # @private
-    ARCHIVE_TYPES = Set.new(%w[tar zip].flat_map { [_1, _1.to_sym] }).freeze
+    ARCHIVE_TYPES = Set.new(%w[tar zip].flat_map { [_1, _1.to_sym] }).freeze # :nodoc:
 
-    # `restic dump`: extracts a file/folder from a snapshot. A single file's
+    # +restic dump+: extracts a file/folder from a snapshot. A single file's
     # raw bytes are written as-is; a folder is written as a tar/zip archive.
-    # Give at most one of `target:` or a block.
+    # Give at most one of +target:+ or a block.
     #
-    # @param snapshot_id [String] also accepts Restic's own `"snapshotID:subfolder"` form directly
-    # @param file [String] path within the snapshot to extract; `"/"` dumps the whole snapshot
-    # @param target [String, nil] write straight to this file path instead of yielding a block
-    # @param archive [String, Symbol, nil] `"tar"` (default) or `"zip"`, when `file` is a folder
-    # @param hosts [Array<String>, String] only relevant when `snapshot_id` is `"latest"`
-    # @param paths [Array<String>, String] only relevant when `snapshot_id` is `"latest"`
-    # @param tags [Array<String>, String] only relevant when `snapshot_id` is `"latest"`
-    # @yieldparam io [IO]
-    # @return [true] if `target:` was given
-    # @return [Yobi::IOHandle] if no block is given
-    # @raise [ArgumentError] if given both `target:` and a block
+    # +snapshot_id:+ is a snapshot ID, or Restic's own
+    # +"snapshotID:subfolder"+ form. +file:+ is the path within the snapshot
+    # to extract; +"/"+ dumps the whole snapshot. +archive:+ is +"tar"+
+    # (default) or +"zip"+, and only applies when +file+ is a folder.
+    #
+    # +hosts:+, +paths:+ and +tags:+ are only relevant when +snapshot_id+
+    # is +"latest"+.
+    #
+    # With +target:+, writes straight to that file path and returns +true+.
+    # Without a block, returns a Yobi::IOHandle. Raises ArgumentError if
+    # given both +target:+ and a block.
     def dump(snapshot_id:, file:, target: nil, archive: nil, hosts: [], paths: [], tags: [], &block)
       raise ArgumentError, "give at most one of target: or a block, not both" if target && block
 

data/lib/yobi/repository/find.rb

@@ -4,25 +4,20 @@ require "time"
 
 module Yobi
   class Repository
-    # `restic find`: searches for files/directories across snapshots by
+    # +restic find+: searches for files/directories across snapshots by
     # name pattern.
     #
-    # @param patterns [Array<String>, String] glob patterns to match
-    # @param blob [Boolean] match blob IDs instead of file names
-    # @param pack [Boolean] match pack IDs instead of file names
-    # @param tree [Boolean] match tree IDs instead of file names
-    # @param hosts [Array<String>, String] filter by hostname(s)
-    # @param human_readable [Boolean] format sizes for humans
-    # @param ignore_case [Boolean] case-insensitive matching
-    # @param long [Boolean] include long listing format
-    # @param newest [String, nil] only consider snapshots at or before this time
-    # @param oldest [String, nil] only consider snapshots at or after this time
-    # @param paths [Array<String>, String] filter by originally backed-up path(s)
-    # @param reverse [Boolean] reverse sort order
-    # @param show_pack_id [Boolean] include the pack ID each match is stored in
-    # @param snapshot_ids [Array<String>, String] restrict to these snapshot ID(s)
-    # @param tags [Array<String>, String] filter by tag(s)
-    # @return [Array<Yobi::MatchesPerSnapshot>]
+    # +patterns:+ accepts a single glob or an Array. +blob:+, +pack:+ and
+    # +tree:+ match blob/pack/tree IDs instead of file names.
+    #
+    # +hosts:+, +paths:+, +snapshot_ids:+, and +tags:+ each accept a single
+    # value or an Array to filter by. +newest:+ / +oldest:+ restrict the
+    # snapshot window.
+    #
+    # +ignore_case:+, +long:+, +human_readable:+, +reverse:+ and
+    # +show_pack_id:+ toggle formatting/matching options.
+    #
+    # Returns an Array of Yobi::MatchesPerSnapshot.
     def find(patterns:, blob: false, pack: false, tree: false, hosts: [], human_readable: false,
       ignore_case: false, long: false, newest: nil, oldest: nil, paths: [], reverse: false,
       show_pack_id: false, snapshot_ids: [], tags: [])
@@ -48,88 +43,73 @@ module Yobi
     end
   end
 
-  # One matched file/directory from a {Yobi::Repository#find} call.
+  # One matched file/directory from a Yobi::Repository#find call.
   class FindMatch < Yobi::FancyHash
-    # @return [String]
     def path
       self["path"]
     end
 
-    # @return [String]
     def type
       self["type"]
     end
 
-    # @return [Integer]
     def size
       self["size"]
     end
 
-    # @return [String]
     def permissions
       self["permissions"]
     end
 
-    # @return [Integer]
     def uid
       self["uid"]
     end
 
-    # @return [Integer]
     def gid
       self["gid"]
     end
 
-    # @return [String]
     def user
       self["user"]
     end
 
-    # @return [String]
     def group
       self["group"]
     end
 
-    # @return [Integer]
     def inode
       self["inode"]
     end
 
-    # @return [Time]
     def mtime
       @mtime ||= Time.parse(self["mtime"])
     end
 
-    # @return [Time]
     def atime
       @atime ||= Time.parse(self["atime"])
     end
 
-    # @return [Time]
     def ctime
       @ctime ||= Time.parse(self["ctime"])
     end
   end
 
-  # One snapshot's worth of matches from a {Yobi::Repository#find} call.
+  # One snapshot's worth of matches from a Yobi::Repository#find call.
   class MatchesPerSnapshot < Yobi::FancyHash
-    # Restic's own `find --json` output only gives the snapshot's ID here,
+    # Restic's own +find --json+ output only gives the snapshot's ID here,
     # not a full record - unlike every other place in this API where
-    # "snapshot" means a {Yobi::Snapshot}. Call {Yobi::Repository#snapshots}
+    # "snapshot" means a Yobi::Snapshot. Call Yobi::Repository#snapshots
     # yourself if you need the full record.
-    #
-    # @return [String]
     def snapshot
       self["snapshot"]
     end
     alias_method :snapshot_id, :snapshot
 
-    # @return [Integer]
     def hits
       self["hits"]
     end
 
-    # @return [Array<Yobi::FindMatch>]
+    # An Array of Yobi::FindMatch objects for this snapshot.
     def matches
       @matches ||= (self["matches"] || []).map { |raw| Yobi::FindMatch.new(raw) }
     end