lib/cdio.rb in rbcdio-0.02 vs lib/cdio.rb in rbcdio-0.03

- old
+ new

@@ -1,25 +1,23 @@ #!/usr/bin/env ruby -# $Id: cdio.rb,v 1.19 2007/10/13 23:00:18 rocky Exp $ +# $Id: cdio.rb,v 1.21 2008/05/02 13:05:40 karl Exp $ # -# Copyright (C) 2006 Rocky Bernstein <rocky@gnu.org> +# Copyright (C) 2006, 2007, 2008 Rocky Bernstein <rocky@gnu.org> # -# This program is free software; you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation; either version 2 of the License, or -# (at your option) any later version. +# This program is free software: you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation, either version 3 of the License, or +# (at your option) any later version. # -# This program is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. # -# You should have received a copy of the GNU General Public License -# along with this program; if not, write to the Free Software -# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA -# 02110-1301 USA. -# +# You should have received a copy of the GNU General Public License +# along with this program. If not, see <http://www.gnu.org/licenses/>. + # Author:: Rocky Bernstein (mailto:rocky@gnu.org) # # = cdio # Module for CD Input and Control library. # == Version @@ -144,21 +142,21 @@ } end # close media tray in CD drive if there is a routine to do so. -# The driver id is returned. A DeviceException is thrown on error. +# The +driver id +is returned. A DeviceException is thrown on error. def close_tray(drive=nil, driver_id=Rubycdio::DRIVER_UNKNOWN) drc, found_driver_id = Rubycdio::close_tray(drive, driver_id) possibly_raise_exception__(drc) return found_driver_id end # Returns: [device, driver] # # Return a string containing the default CD device if none is -# specified. if driver_id is DRIVER_UNKNOWN or DRIVER_DEVICE +# specified. if +driver_id+ is DRIVER_UNKNOWN or DRIVER_DEVICE # then one set the default device for that. # # nil is returned as the device if we couldn't get a default # device. def default_device_driver(driver_id=Rubycdio::DRIVER_DEVICE) @@ -172,13 +170,13 @@ return Rubycdio::get_devices(driver_id) end # Returns: [device1, device2, ... driver_id] # -# Like get_devices, but return the p_driver_id which may be different +# Like get_devices, but return the driver_id which may be different # from the passed-in driver_id if it was Rubycdio::DRIVER_DEVICE or -# Rubycdio::DRIVER_UNKNOWN. The return driver_id may be useful because +# Rubycdio::DRIVER_UNKNOWN. The return +driver_id+ may be useful because # often one wants to get a drive name and then *open* it # afterwards. Giving the driver back facilitates this, and speeds things # up for libcdio as well. def devices_ret(driver_id=Rubycdio::DRIVER_UNKNOWN) devices = Rubycdio::get_devices_ret(driver_id) @@ -192,13 +190,13 @@ # must be satisified. If any is true, then if any of the # capabilities matches, we call that a success. # # To find a CD-drive of any type, use the mask Rubycdio::CDIO_FS_MATCH_ALL. # -# The array of device names is returned or NULL if we couldn't get a -# default device. It is also possible to return a non NULL but after -# dereferencing the the value is NULL. This also means nothing was +# The array of device names is returned or nil if we couldn't get a +# default device. It is also possible to return a non nil but after +# dereferencing the the value is nil. This also means nothing was # found. def devices_with_cap(capabilities, any=false) return Rubycdio::get_devices_with_cap(capabilities, any) end @@ -231,11 +229,11 @@ #-- # FIXME ? is not quite right # binfile?(binfile_name)->cue_name #++ # -# Determine if binfile_name is the BIN file part of a CDRWIN CD +# Determine if +binfile_name+ is the BIN file part of a CDRWIN CD # disk image. # # Return the corresponding CUE file if bin_name is a BIN file or # nil if not a BIN file. def binfile?(binfile_name) @@ -243,11 +241,11 @@ end #-- # FIXME ? is not quite right #++ -# return bin_name +# return bin_name for a corresponding CUE file # # Determine if cuefile_name is the CUE file part of a CDRWIN CD # disk image. # # Return the corresponding BIN file if bin_name is a CUE file or @@ -271,16 +269,16 @@ return Rubycdio::nrg?(nrgfile_name) end # tocfile?(tocfile_name)->bool # -# Determine if tocfile_name is a cdrdao CD disc image +# Determine if +tocfile_name+ is a cdrdao CD disc image def tocfile?(tocfile_name) return Rubycdio::tocfile?(tocfile_name) end -# Convert bit mask for miscellaneous drive properties +# Convert +bitmask+ for miscellaneous drive properties # into a dictionary of drive capabilities def convert_drive_cap_misc(bitmask) result={} if bitmask & Rubycdio::DRIVE_CAP_ERROR result[:DRIVE_CAP_ERROR] = true @@ -371,11 +369,11 @@ result[:DRIVE_CAP_READ_ISRC] = true end return result end -# Convert bit mask for drive write properties +# Convert +bitmask+ for drive write properties # into a dictionary of drive capabilities def convert_drive_cap_write(bitmask) result={} if bitmask & Rubycdio::DRIVE_CAP_WRITE_CD_R result[:DRIVE_CAP_WRITE_CD_R] = true @@ -456,11 +454,11 @@ possibly_raise_exception__(drc) end # Returns: status # - # Playing CD through analog output at the given lsn to the ending lsn + # Playing CD through analog output from +start_lsn+ to +ending_lsn+ # A DeviceError exception may be raised. def audio_play_lsn(start_lsn, end_lsn) drc=Rubycdio::audio_play_lsn(@cd, start_lsn, end_lsn) possibly_raise_exception__(drc) end @@ -481,12 +479,13 @@ def audio_stop() drc=Rubycdio::audio_stop(@cd) possibly_raise_exception__(drc) end - # Free resources associated with p_cdio. Call this when done using - # using CD reading/control operations for the current device. + # Free (C memory) resources associated with the object. Call this when + # done using using CD reading/control operations for the current + # device. def close() if @cd Rubycdio::close(@cd) else puts "***No object to close" @@ -694,17 +693,17 @@ return Track.new(@cd, track_num) end # Returns: track # - # Find the track which contains lsn. + # Find the track which contains +lsn+. # nil is returned if the lsn outside of the CD or # if there was some error. # - # If the lsn is before the pregap of the first track, + # If +lsn+ is before the pregap of the first track, # A track object with a 0 track is returned. - # Otherwise we return the track that spans the lsn. + # Otherwise we return the track that spans the LSN. def track_for_lsn(lsn) track = Rubycdio::get_last_track_num(@cd) if track == Rubycdio::INVALID_TRACK: return nil end @@ -713,25 +712,25 @@ # Returns: Fixnum # Reposition read offset # Similar to (if not the same as) libc's fseek() # - # cdio is object to get adjested, offset is amount to seek and - # whence is like corresponding parameter in libc's lseek, e.g. + # +offset+ is amount to seek and + # +whence+ is like corresponding parameter in libc's lseek, e.g. # it should be SEEK_SET or SEEK_END. # # the offset is returned or -1 on error. def lseek(offset, whence) return Rubycdio::lseek(@cd, offset, whence) end - # Sets up to read from place specified by source, driver_id and - # access mode. This should be called before using any other routine + # Sets up to read from place specified by +source+, +driver_id+ and + # +access_mode+. This should be called before using any other routine # except those that act on a CD-ROM drive by name. # - # If nil is given as the source, we'll use the default driver device. - # If nil is given as the driver_id, we'll find a suitable device driver. + # If nil is the value of +source+, we'll use the default driver device. + # If nil is the value of +driver_id+, we'll find a suitable device driver. # # If device object was, previously opened it is closed first. # # Device is opened so that subsequent operations can be performed. def open(source=nil, driver_id=Rubycdio::DRIVER_UNKNOWN, @@ -751,11 +750,11 @@ @cd = Rubycdio::open_cd(source, driver_id, access_mode) end # Returns: [size, data] # - # Reads the next size bytes. + # Reads the next +size+ bytes. # Similar to (if not the same as) libc's read() # # The number of bytes read and the data is returned. # A DeviceError exception may be raised. def read(size) @@ -766,11 +765,11 @@ # return [size, data] # # Reads a number of data sectors (AKA blocks). # - # lsn is sector to read, bytes is the number of bytes. + # +lsn+ is the sector to read; +bytes+ is the number of bytes to read. # A DeviceError exception may be raised. def read_data_blocks(lsn, blocks=1) size = Rubycdio::ISO_BLOCKSIZE*blocks triple = Rubycdio::read_data_bytes(@cd, lsn, Rubycdio::ISO_BLOCKSIZE, size) @@ -784,22 +783,22 @@ # return [blocks, data] # # Reads a number of sectors (AKA blocks). # - # lsn is sector to read, bytes is the number of bytes. + # +lsn+ is the sector to read, +bytes+ is the number of bytes to read. # - # If read_mode is Rubycdio::MODE_AUDIO, the return buffer size will be + # If +read_mode+ is Rubycdio::MODE_AUDIO, the return buffer size will be # truncated to multiple of Rubycdio::CDIO_FRAMESIZE_RAW i_blocks bytes. # - # If read_mode is Rubycdio::MODE_DATA, buffer will be truncated to a + # If +read_mode+ is Rubycdio::MODE_DATA, buffer will be truncated to a # multiple of Rubycdio::ISO_BLOCKSIZE, Rubycdio::M1RAW_SECTOR_SIZE or # Rubycdio::M2F2_SECTOR_SIZE bytes depending on what mode the data is in. # - # If read_mode is Rubycdio::MODE_M2F1, buffer will be truncated to a + # If +read_mode+ is Rubycdio::MODE_M2F1, buffer will be truncated to a # multiple of Rubycdio::M2RAW_SECTOR_SIZE bytes. # - # If read_mode is Rubycdio::MODE_M2F2, the return buffer size will be + # If +read_mode+ is Rubycdio::MODE_M2F2, the return buffer size will be # truncated to a multiple of Rubycdio::CD_FRAMESIZE bytes. # # The number of bytes read and the data is returned. # A DeviceError exception may be raised. def read_sectors(lsn, read_mode, blocks=1)