Class: Stashify::File

Inherits:
Object
  • Object
show all
Defined in:
lib/stashify/file.rb,
lib/stashify/file/local.rb

Overview

A common abstraction for interacting with files. All methods that need to interact with files are assumed to adhere to the methods defined here. Specifically the methods #write, #delete, #contents and #exists? are guaranteed to exist and behave in a way that is consistent across all gems. Unless called out separately, documentation for those methods here will hold true of any implementations of this class.

Direct Known Subclasses

Local

Defined Under Namespace

Classes: Local

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(name: nil, path: nil, contents: nil) ⇒ File

Basic information associated with a file that is necessary to enable memory-based interactions.

Parameters:

  • name (String not containing a "/") (defaults to: nil) —

    The name of the file. Either this or path must be defined.

  • path (String) (defaults to: nil) —

    The path of the file, will populate name with everything following the final “/”.

  • contents (String) (defaults to: nil) —

    The contents of the file, if nil this object will mimic a missing file.

Raises:

  • (StandardError) 


37
38
39
40
41
42
43
44
 
# File 'lib/stashify/file.rb', line 37

def initialize(name: nil, path: nil, contents: nil)
  raise StandardError, "name or path must be defined" unless name || path
  raise Stashify::InvalidFile, "Name '#{name}' contains a /" if name && name =~ %r{/}

  @path = path
  @name = name || ::File.basename(path)
  @contents = contents
end

Instance Attribute Details

#contents ⇒ Object (readonly)

Provides the contents of this file. In the base class, this is implemented as an attribute, but most implementations will override this with a method. In most implementations, the performance cost of reading the file is high enough that we only want to pay it if it’s actually needed.



19
20
21
 
# File 'lib/stashify/file.rb', line 19

def contents
  @contents
end

#name ⇒ Object (readonly)

The name of the file is the actual filename in a directory. In other words, it is everything that follows the final “/” in the #path. This is always guaranteed to be populated.



24
25
26
 
# File 'lib/stashify/file.rb', line 24

def name
  @name
end

#path ⇒ Object (readonly)

The full path to the file this represents. Anything after the final “/” will also be returned from #name. This is not necessarily guaranteed to be populated, but usually will be.



29
30
31
 
# File 'lib/stashify/file.rb', line 29

def path
  @path
end

Instance Method Details

#==(other) ⇒ Object

Two files are considered equal if they have the same name and contents. This means that equality holds between files in two separate directories.



91
92
93
 
# File 'lib/stashify/file.rb', line 91

def ==(other)
  name == other.name && contents == other.contents
end

#delete ⇒ Object

Deletes the underlying file.

In general, if #exists? returns true prior to this method being called, it will no longer return true after this method is called.

Returns:

  • No guarantees are made as to the return value of this method, it will largely depend on the implementation of the implementing class.



74
75
76
 
# File 'lib/stashify/file.rb', line 74

def delete
  @contents = nil
end

#exists? ⇒ Boolean

Note:

The base class checks if #contents returns nil, but this is extremely unlikely for other implementations.

Answers if the file exists. In general, it will always return true after #write is called and always return false after #delete is called.

Returns:

  • (Boolean) 


84
85
86
 
# File 'lib/stashify/file.rb', line 84

def exists?
  !contents.nil?
end

#write(contents) ⇒ Object

Note:

For the base implementation, it will assign something to @contents. The value of this instance variable should not be relied upon outside of the base implementation though, every other implementation so far overrides to an action more appropriate to its storage medium.

Persists the provided contents into #path. If that file does not exist, it creates it in the process. Otherwise it updates the existing file.

In general, if #exists? returns false before this is called it will return true after this is called.

Parameters:

  • contents (String) —

    A String describing the contents of the file.

Returns:

  • No guarantees are made as to the return value of this method, it will largely depend on the implementation of the implementing class.



62
63
64
 
# File 'lib/stashify/file.rb', line 62

def write(contents)
  @contents = contents
end