Class: Box::Folder

Inherits:
Item
  • Object
show all
Defined in:
lib/box/folder.rb

Overview

Represents a folder stored on Box. Any attributes or actions typical to a Box folder can be accessed through this class.

Instance Attribute Summary

Attributes inherited from Item

#api, #data, #parent

Class Method Summary collapse

Instance Method Summary collapse

Methods inherited from Item

#copy, #delete, #id, #initialize, #method_missing, #move, #path, #rename, #respond_to?, #set_description, #share_private, #share_public, #type, #types, types, #unshare

Constructor Details

This class inherits a constructor from Box::Item

Dynamic Method Handling

This class handles dynamic methods through the method_missing method in the class Box::Item

Class Method Details

.type ⇒ String

Returns The string representation of this item.

Returns:

  • (String) —

    The string representation of this item.



10
 
# File 'lib/box/folder.rb', line 10

def self.type; 'folder'; end

Instance Method Details

#at(target_path) ⇒ Item

Get the item at the given path.

Examples:

Find a folder based on its absolute path.

folder.at('/box/is/awesome')

Find a file based on a relative path.

folder.at('awesome/file.pdf')

Find a folder using the parent.

folder.at('../other/folder')

Parameters:

  • The (String) —

    path to search for. This follows the typical unix path syntax, in that the root folder is ‘/’. Supports the dot sytax, where ‘.’ is the current folder and ‘..’ is the parent folder.

Returns:

  • (Item) —

    The item that exists at this path, or nil.



142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
 
# File 'lib/box/folder.rb', line 142

def at(target_path)
  # start with this folder
  current = self

  if target_path.start_with?('/')
    # absolute path, find the root folder
    current = current.parent while current.parent != nil
  end

  # split each part of the target path
  target_path.split('/').each do |target_name|
    # update current based on the target name
    current = case target_name
    when "", "."
      # no-op
      current
    when ".."
      # use the parent folder
      parent
    else
      # must be a file/folder name, so make sure this is a folder
      return nil unless current and current.type == 'folder'

      # search for an item with that name
      current.find(:name => target_name, :recursive => false).first
    end
  end

  if current
    # ends with a slash, so it has to be a folder
    if target_path.end_with?('/') and current.type != 'folder'
      # get the folder with the same name (if it exists)
      current = parent.find(:type => 'folder', :name => name, :recursive => false).first
    end
  end

  current
end

#create(name, share = 0) ⇒ Folder

Create a new folder using this folder as the parent.

Parameters:

  • name (String) —

    The name of the new folder.

  • share (Integer) (defaults to: 0) —

    The shared status of the new folder. Defaults to not being shared.

Returns:

  • (Folder) —

    The new folder.



52
53
54
55
56
57
58
 
# File 'lib/box/folder.rb', line 52

def create(name, share = 0)
  info = @api.create_folder(id, name, share)['folder']

  delete_info('folders')

  Box::Folder.new(api, self, info)
end

#find(criteria) ⇒ Array

Note:

The recursive option will call #tree, which can be slow for large folders.

Note:

Any item method (as a symbol) can be used as criteria, which could cause major problems if used improperly.

Search for sub-items using criteria.

TODO: Lookup YARD syntax for options hash.

Examples:

Find all sub-items with the name ‘README’

folder.search(:name => 'README')

Recusively find a sub-item with the given path.

folder.search(:path => '/test/file.mp4', :recursive => true)

Recursively find all files with a given sha1.

folder.search(:type => 'file', :sha1 => 'abcdefg', :recursive => true)

Parameters:

  • criteria (Hash) —

    The hash of criteria to use. Each key of the criteria will be called on each sub-item and tested for equality. This lets you use any method of Item, Box::Folder, and Box::File as the criteria.

Returns:

  • (Array) —

    An array of all sub-items that matched the criteria.



95
96
97
98
99
100
101
102
 
# File 'lib/box/folder.rb', line 95

def find(criteria)
  recursive = criteria.delete(:recursive)
  recursive = false if recursive == nil # default to false for performance reasons

  tree if recursive # get the full tree

  find!(criteria, recursive)
end

#force_cached_info ⇒ Object

Consider the item cached. This prevents an additional api when we know the item is fully fetched.



105
106
107
108
109
110
 
# File 'lib/box/folder.rb', line 105

def force_cached_info
  create_sub_items(nil, Box::Folder)
  create_sub_items(nil, Box::File)

  super
end

#force_cached_tree ⇒ Object

Consider the tree cached. This prevents an additional api when we know the item is fully fetched.



114
115
116
117
118
119
120
121
122
123
 
# File 'lib/box/folder.rb', line 114

def force_cached_tree
  @cached_tree = true

  create_sub_items(nil, Box::Folder)
  create_sub_items(nil, Box::File)

  folders.each do |folder|
    folder.force_cached_tree
  end
end

#info(refresh = false) ⇒ Item

Get the info for this item. Uses a cached copy if avaliable, or else it is fetched from the api.

Files and folders will only be one-level deep, and #tree should be used if fetching deeper than that.

Parameters:

  • refresh (Boolean) (defaults to: false) —

    Does not use the cached copy if true.

Returns:



15
16
17
18
19
20
21
22
 
# File 'lib/box/folder.rb', line 15

def info(refresh = false)
  return self if @cached_info and not refresh

  create_sub_items(nil, Box::Folder)
  create_sub_items(nil, Box::File)

  super
end

#tree(refresh = false) ⇒ Folder

Note:

Fetching the tree can take a long time for large folders. There is a trade-off between one #tree call and multiple #info calls, so use the one most relevant for your application.

Get the tree for this folder. The tree includes all sub folders and files, including their info. Uses a cached copy if avaliable, or else it is fetched from the api.

Parameters:

  • refresh (Boolean) (defaults to: false) —

    Does not use the cached copy if true.

Returns:



34
35
36
37
38
39
40
41
42
43
44
 
# File 'lib/box/folder.rb', line 34

def tree(refresh = false)
  return self if @cached_tree and not refresh

  @cached_info = true # count the info as cached as well
  @cached_tree = true

  update_info(get_tree)
  force_cached_tree

  self
end

#upload(path) ⇒ File

Upload a new file using this folder as the parent

Parameters:

  • path (String) —

    The path of the file on disk to upload.

Returns:

  • (File) —

    The new file.



64
65
66
67
68
69
70
 
# File 'lib/box/folder.rb', line 64

def upload(path)
  info = @api.upload(path, id)['files']['file']

  delete_info('files')

  Box::File.new(api, self, info)
end