Opened 4 years ago

Closed 4 years ago

#4317 closed proposal (fixed)

Add comments to the definition of IODeviceType (module GHC.IO.Device)

Reported by: golubovsky Owned by: simonmar
Priority: normal Milestone: 7.0.1
Component: libraries/base Version: 6.12.3
Keywords: Cc:
Operating System: Unknown/Multiple Architecture: Unknown/Multiple
Type of failure: Documentation bug Difficulty:
Test Case: Blocked By:
Blocking: Related Tickets:

Description

-- | Type  of a device that can be used to back a 'GHC.IO.Handle.Handle' 
-- (see also 'GHC.IO.Handle.mkFileHandle'). The standard libraries provide creation of 'GHC.IO.Handle.Handle's via 
-- Posix file operations with file descriptors (see 'GHC.IO.Handle.FD.mkHandleFromFD') 
-- with FD being the underlying 'GHC.IO.Device.IODevice' instance. 

-- Users may provide custom instances of 'GHC.IO.Device.IODevice' which are expected to conform the following rules:

data IODeviceType
  = Directory --^ The standard libraries do not have direct support
              -- for this device type, but user implementation is 
              -- expected to provide a newline-separated list of 
              -- file names in a directory (without path to the 
              -- directory itself) in any suitable order,
              -- excluding "dot" and "dotdot" names. See 
              -- also 'System.Directory.getDirectoryContents'.
              -- Seek operation is not supported on directories 
              -- (other than to the zero position).
  | Stream    --^ A duplex communications channel (results in 
              -- creation of a duplex 'GHC.IO.Handle.Handle'). The 
              -- standard libraries use this device type when 
              -- creating 'GHC.IO.Handle.Handle's for open sockets.
  | RegularFile --^ A file that may be read or written, and also 
                -- may be seekable.
  | RawDevice --^ A "raw" (disk) device which supports block binary 
              -- read and write operations and may be seekable only 
              -- to positions of certain granularity (block-
              -- aligned).
  deriving (Eq)

Change History (9)

comment:1 Changed 4 years ago by simonmar

  • Milestone set to 7.0.1
  • Owner set to simonmar

comment:2 Changed 4 years ago by igloo

-- expected to provide a newline-separated list of 
-- file names in a directory (without path to the 

I'd suggest '\0'-separated instead.

comment:3 Changed 4 years ago by golubovsky

Well, the idea of newline-separated names was that output is immediately printable, and can be tirned into a list of strings using the lines function.

Zero-separated output does not have this property.

OTOH, there was an alternative proposal in my e-mail that the handle could provide a serialized list of FileStatus (or similar) structures, which is slower of course, but if one wants to extract as much file information as possible not worrying about being printable this is IMHO a better (yet complicated) way.

I still stand for newline-separated output.

comment:4 Changed 4 years ago by igloo

newline-separated output breaks if files contain newline characters.

comment:5 Changed 4 years ago by golubovsky

Well, it does as do many other programs that don't expect newline there...

I thought such a handle could be just a wrapper for getDirectoryContents in the general case.

If we make this one zero-separated, should this also affect getDirectoryContents itself?

comment:6 Changed 4 years ago by igloo

I'm not following. getDirectoryContents returns a list.

comment:7 Changed 4 years ago by golubovsky

OK, my bad...

comment:8 Changed 4 years ago by simonmar

  • Status changed from new to merge

Done:

Wed Sep 15 14:13:41 BST 2010  Simon Marlow <marlowsd@gmail.com>
  * documentation for IODeviceType (#4317, edited by me)
Wed Sep 22 12:38:11 BST 2010  Simon Marlow <marlowsd@gmail.com>
  * doc tweak for Directory file type: file names are '\0'-separated

comment:9 Changed 4 years ago by igloo

  • Resolution set to fixed
  • Status changed from merge to closed

Both merged

Note: See TracTickets for help on using tickets.