class ROBundle::File

This class represents a Research Object Bundle file. See the RO Bundle specification for more details.

Many of the methods that this class provides are actually implemented in the Manifest class, so please see its documentation for details.

Attributes

manifest[R]

Public Class Methods

create(filename) → File click to toggle source
create(filename, mimetype) → File
create(filename) {|file| ...}
create(filename, mimetype) {|file| ...}

Create a new RO Bundle file on disk and open it for editing. A custom mimetype for the bundle may be specified but is unnecessary if the default, “application/vnd.wf4ever.robundle+zip”, will be used.

Please see the UCF documentation for much more information and a list of all the other methods available in this class. RDoc does not list inherited methods, unfortunately.

Calls superclass method
   # File lib/ro-bundle/file.rb
58 def self.create(filename, mimetype = MIMETYPE, &block)
59   # Wow. I have to specifically send nil as the block to stop super from
60   # sending the other block up automatically. Is this a bug in Ruby?
61   ro = super(filename, mimetype, &nil)
62   ro.init_metadata
63 
64   if block_given?
65     begin
66       yield ro
67     ensure
68       ro.close
69     end
70   end
71 
72   ro
73 end

Public Instance Methods

add(entry, src_path, options = {}, &continue_on_exists_proc) → Aggregate or nil click to toggle source

Convenience method for adding the contents of a file to the bundle file. If asked to add a file with a reserved name, such as the special mimetype header file or .ro/manifest.json, this method will raise a ReservedNameClashError.

This method automatically adds new entries to the list of bundle aggregates unless the :aggregate option is set to false.

If the added entry is aggregated then the Aggregate object is returned, otherwise nil is returned.

See the rubyzip documentation for details of the continue_on_exists_proc parameter.

Calls superclass method
   # File lib/ro-bundle/file.rb
91 def add(entry, src_path, options = {}, &continue_on_exists_proc)
92   super(entry, src_path, &continue_on_exists_proc)
93 
94   options = { :aggregate => true }.merge(options)
95 
96   if options[:aggregate]
97     @manifest.add_aggregate(entry)
98   end
99 end
add_aggregate(uri) → Aggregate click to toggle source
add_aggregate(entry) → Aggregate
add_aggregate(entry, src_path, &continue_on_exists_proc) → Aggregate

The first form of this method adds a URI as an aggregate of the bundle.

The second form adds an already existing entry in the bundle to the list of aggregates. Errno:ENOENT is raised if the entry does not exist.

The third form is equivalent to File#add called without any options.

In all cases the Aggregate object added to the Research Object is returned.

    # File lib/ro-bundle/file.rb
116 def add_aggregate(entry, src_path = nil, &continue_on_exists_proc)
117   if src_path.nil?
118     @manifest.add_aggregate(entry)
119   else
120     add(entry, src_path, &continue_on_exists_proc)
121   end
122 end
add_annotation(annotation_object) → Annotation click to toggle source
add_annotation(aggregate, content, options = {}) → Annotation
add_annotation(aggregate, file, options = {}) → Annotation
add_annotation(aggregate, uri, options = {}) → Annotation
add_annotation(uri, content, options = {}) → Annotation
add_annotation(uri, file, options = {}) → Annotation
add_annotation(uri, uri, options = {}) → Annotation
add_annotation(annotation, content, options = {}) → Annotation
add_annotation(annotation, file, options = {}) → Annotation
add_annotation(annotation, uri, options = {}) → Annotation

This method has two forms.

The first form registers an already initialized Annotation object in this Research Object.

The second form creates a new Annotation object for the specified target with the specified (or empty content) and registers it in this Research Object.

In both cases Errno:ENOENT is raised if the target of the annotation is not an annotatable resource.

The Annotation object added to the Research Object is returned.

    # File lib/ro-bundle/file.rb
149 def add_annotation(target, body = nil, options = {})
150   options = { :aggregate => false }.merge(options)
151 
152   if target.is_a?(Annotation) || annotatable?(target)
153     if body.nil? || aggregate?(body)
154       content = body
155     elsif Util.is_absolute_uri?(body)
156       content = body
157       @manifest.add_aggregate(body) if options[:aggregate]
158     else
159       content = @ro_dir.write_annotation_data(body, options)
160     end
161 
162     @manifest.add_annotation(target, content)
163   else
164     raise Errno::ENOENT,
165       "'#{target}' is not a member of this Research Object or a URI."
166   end
167 end
add_history(entry) click to toggle source
add_history(entry, src_path, &continue_on_exists_proc)

The first form of this method adds an already existing entry in the bundle to the history list in the manifest. Errno:ENOENT is raised if the entry does not exist.

The second form adds the entry before adding it to the history list. The entry is not aggregated.

    # File lib/ro-bundle/file.rb
179 def add_history(entry, src_path = nil, &continue_on_exists_proc)
180   unless src_path.nil?
181     add(entry, src_path, :aggregate => false, &continue_on_exists_proc)
182   end
183 
184   @manifest.add_history(entry)
185 end
aggregate?(uri) → true or false click to toggle source
aggregate?(entry) → true or false

Is the supplied URI or entry aggregated in this Research Object?

    # File lib/ro-bundle/file.rb
192 def aggregate?(entry)
193   return true if entry == @manifest.id
194 
195   if Util.is_absolute_uri?(entry)
196     entry = entry.to_s
197   else
198     entry = entry_name(entry)
199   end
200 
201   aggregates.each do |agg|
202     return true if agg.uri == entry || agg.file_entry == entry
203   end
204 
205   false
206 end
annotatable?(target) → true or false click to toggle source

Is the supplied target an annotatable resource? An annotatable resource is either an absolute URI (which may or may not be aggregated in the RO), an aggregated resource or another registered annotation.

    # File lib/ro-bundle/file.rb
214 def annotatable?(target)
215   Util.is_absolute_uri?(target) || annotation?(target) || aggregate?(target)
216 end
annotation?(id) → true or false click to toggle source
annotation?(annotation) → true or false

Is the supplied id or annotation registered in this Research Object?

    # File lib/ro-bundle/file.rb
223 def annotation?(id)
224   id = id.uri if id.instance_of?(Annotation)
225 
226   annotations.each do |ann|
227     return true if ann.uri == id
228   end
229 
230   false
231 end
close → true or false
Alias for: commit
commit → true or false click to toggle source

Commits changes that have been made since the previous commit to the RO Bundle file. Returns true if anything was actually done, false otherwise.

Calls superclass method
    # File lib/ro-bundle/file.rb
240 def commit
241   if @manifest.edited?
242     # This will overwrite the old version.
243     @manifest.write
244 
245     @ro_dir.cleanup_annotation_data
246   end
247 
248   super
249 end
Also aliased as: close
commit_required? → true or false click to toggle source

Returns true if any changes have been made to this RO Bundle file since the last commit, false otherwise.

Calls superclass method
    # File lib/ro-bundle/file.rb
258 def commit_required?
259   super || @manifest.edited?
260 end
find_entry(entry_name, options = {}) → Zip::Entry or nil click to toggle source

Searches for the entry with the specified name. Returns nil if no entry is found or if the specified entry is hidden for normal use. You can specify :include_hidden => true to include hidden entries in the search.

Calls superclass method
    # File lib/ro-bundle/file.rb
269 def find_entry(entry_name, options = {})
270   return if Util.is_absolute_uri?(entry_name)
271 
272   super(entry_name, options)
273 end
remove(entry) click to toggle source

Removes the specified entry from the Research Object bundle. If asked to remove any reserved files such as the special mimetype header file this method will do nothing.

If the entry being removed is aggregated in this RO then the aggregation is removed. All annotations that refer to the removed entry are also removed.

Calls superclass method
    # File lib/ro-bundle/file.rb
285 def remove(entry, preserve_manifest = false)
286   super(entry)
287 
288   # The preserve manifest flag is STRICTLY for internal use only.
289   unless preserve_manifest
290     name = entry_name(entry)
291     @manifest.remove_aggregate("/#{name}")
292     remove_annotation("/#{name}")
293   end
294 end
remove_aggregate(entry) click to toggle source
remove_aggregate(uri)
remove_aggregate(Aggregate)

Remove (unregister) an aggregate from this Research Object. If it is a file then the file is no longer aggregated, and it is deleted from the bundle by this method unless the option :keep_file => true is supplied.

Any annotations with the removed aggregate as their target are also removed from the RO.

    # File lib/ro-bundle/file.rb
308 def remove_aggregate(object, options = {})
309   options = { :keep_file => false }.merge(options)
310   file = nil
311 
312   if object.is_a?(Aggregate)
313     file = object.file_entry
314   elsif !Util.is_absolute_uri?(object)
315     object = entry_name(object)
316     file = Util.strip_leading_slash(object)
317   end
318 
319   if !file.nil? && !options[:keep_file]
320     remove(file, true)
321   end
322 
323   @manifest.remove_aggregate(object)
324 end