# Path Support

Denys Duchier

module
  x-oz://system/os/Path.ozf

This module provides an object-oriented interface for path and OS operations on them

## Exports

The module exports not only the object-oriented API for path, but also a convenient functional API built on top of the later. It should be noted however that the functional API always needs to build path objects and thus is less efficient than the OO API, though possibly occasionally more convenient.

`{Path.make +VS ?P}`
  given a virtual string `VS`, returns a new path object `P`. If `VS` is already a path object, then it is simply returned.
`{Path.is +X ?B}`
  return true iff `X` is a path object
`Path.'class'`
  The class which implements path objects
`{Path.toString +X ?S}`
`{Path.toAtom +X ?A}`
`{Path.length +X ?N}`
`{Path.isAbsolute +X ?B}`
`{Path.isRelative +X ?B}`
`{Path.dirname +X ?S}`
`{Path.basename +X ?S}`
`{Path.exists +X ?B}`
`{Path.stat +X ?R}`
`{Path.isDir +X ?B}`
`{Path.isFile +X ?B}`
`{Path.size +X ?N}`
`{Path.mtime +X ?N}`
`{Path.resolve +X1 +X2 ?S}`
`{Path.getcwd ?S}`
`{Path.mkdir +X}`
`{Path.mkdirs +X}`
`{Path.isRoot +X ?B}`
`{Path.readdir +X ?L}`
`{Path.extension +X ?S}`
`{Path.dropExtension +X ?S}`
`{Path.addExtension +X +VS ?S}`
`{Path.maybeAddPlatform +X ?S}`
`{Path.rmdir +X}`
  for proper descriptions, see path methods below. Returned path objects are converted to strings where applicable

## Instance API

Each path object `P` has the following methods:

`{P init(+S windows:WIN<=ISWIN exact:EXACT<=false)}`
  initializes a path object from the string `S`. `WIN` indicates that it should be considered a Windows-style path: this usually defaults to false, except on Windows where it defaults to true. `EXACT` indicates whether we should keep a terminal slash; the default is false.
`{P initFromRecord(+R)}`
  initializes the path object from its record-based representation
`{P newFromRecord(R $)}`
  This method is meant to be overriden when you subclass the `Path` class. It's default definition is `meth newFromRecord(R $) {New Path initFromRecord(R)} end`
`{P new(+S windows:WIN<=ISWIN exact:EXACT<=false)}`
  this method is also meant to be overriden to create derived instances from a string `S`
`{P toString($)}`
`{P toAtom($)}`
  return a string (resp. an atom) textual representation of the path
`{P length($)}`
  returns the length of the string that is the textual representation of the path
`{P isAbsolute($)}`
`{P isRelative($)}`
  returns true (resp. false) iff the path is absolute
`{P dirname($)}`
  returns a new path object representing the parent directory of `P`
`{P basenameString($)}`
  returns the string representation for the last component of `P`
`{P basename($)}`
  returns a new path object representing just the last component of path `P`
`{P exists($)}`
  returns true iff path `P` exists
`{P stat($)}`
  returns a record representation of the stat information for path `P`
`{P isDir($)}`
`{P isFile($)}`
  returns true iff `P` is a directory (resp. a regular file)
`{P size($)}`
  returns the size of file `P` in bytes
`{P mtime($)}`
  returns the time of last modification as an integer
`{P resolve(+P2 $)}`
  returns a new path object that results from resolving `P2` relative to `P` (if `P2` is not a path, it is made into one)
`{P getcwd($)}`
  returns a path object representing the current working directory
`{P mkdir}`
  creates directory `P`
`{P mkdirs}`
  creates directory `P` and its ancestor directories too if necessary
`{P rmdir}`
  removes directory `P`
`{P isRoot($)}`
  returns true iff `P` is a root path
`{P readdir($)}`
  returns a list of path objects representing the contents of directory `P`. Entries for `.` and `..` are omitted. All other entries are resolved relative to `P`
`{P extension($)}`
  returns the file extension for `P`, `unit` if none
`{P dropExtension($)}`
  returns a new path object with the extension of `P`, if any, omitted
`{P addExtension(+VS $)}`
  returns a new path object which is like `P` but with the extension `VS` added
`{P maybeAddPlatform($)}`
  is `P` has extension `so` then a new path object is returned with the appropriate (for native functors) platform-specific suffix added, else `P` itself is returned
`{P makeExecutable}`
  makes file `P` executable if this is meaningful on the current platform