<?xml version='1.0' encoding='ISO-8859-1' standalone='no'?>
<!DOCTYPE interface-description SYSTEM 'file:///usr/pkgsrc/lang/oo2c/work.macaroon/oo2c_32-2.0.11/rsrc/OOC/xml/interface-description.dtd'>
<interface-description name='OS:HostPath' id=''>
  <oberon-doc>
    <summary>Operating systems differ in the syntax of file names and paths.</summary>
    <p pad-after='yes' no-indent='yes'>Operating systems differ in the syntax of file names and paths.</p>
    <p pad-after='yes' no-indent='no'>Unix paths are simple and systematic. The "/" symbol separates path elements. Paths with a leading separator are absolute; otherwise the path is relative to the user's current working directory.</p>
    <p pad-after='yes' no-indent='no'>Paths in Microsoft Windows are more problematic. Typically "\" is used as a path separator, but "/" is also permitted. Paths with a leading separator are relative to the user's current working drive. Paths with a leading drive specifier may be absolute or relative. For example, "C:\test" is an absolute path, whereas "C:test" is relative the the user's current directory on drive "C".</p>
    <p pad-after='yes' no-indent='no'>In order to avoid exposing OS-specific details such as "drives" and "working directory per drive", native host OS paths are converted into a "normalized" form in which:</p>
    <itemize pad-after='yes'>
      <itemize-mark><bullet/></itemize-mark>
      <item pad-after='yes'>
        <p pad-after='no' no-indent='yes'>The symbol "/" separates path elements.</p>
      </item>
      <item pad-after='yes'>
        <p pad-after='no' no-indent='yes'>Absolute paths begin with a path separator.</p>
      </item>
      <item pad-after='no'>
        <p pad-after='no' no-indent='yes'>Special symbols such as "\" and ":" (used in Windows) are not present in the path. This means that normalized paths may form part of URIs.</p>
      </item>
    </itemize>
    <p pad-after='yes' no-indent='no'>Normalized paths may be converted back to native OS paths. However, during normalization relative paths may be converted to absolute paths so a denormalized relative path may no longer be relative.</p>
    <p pad-after='yes' no-indent='yes'>Normalisation of Microsoft Windows paths:</p>
    <itemize pad-after='yes'>
      <itemize-mark><bullet/></itemize-mark>
      <item pad-after='yes'>
        <p pad-after='no' no-indent='yes'>Backslash is converted to forward slash.</p>
      </item>
      <item pad-after='yes'>
        <p pad-after='no' no-indent='yes'>Drive identifier "C:" is converted to "/C$".</p>
      </item>
      <item pad-after='no'>
        <p pad-after='no' no-indent='yes'>Drive-relative paths (eg. C:test) are converted to absolute paths by replacing the drive identifier with the user's current working directory on that drive.</p>
      </item>
    </itemize>
    <p pad-after='yes' no-indent='no'>Denormalisation of Microsoft Windows paths:</p>
    <itemize pad-after='yes'>
      <itemize-mark><bullet/></itemize-mark>
      <item pad-after='yes'>
        <p pad-after='no' no-indent='yes'>Backslashes cause problems in many contexts since they are often used as escape characters. Windows usually treats forward and back slashes equivalently, so we retain only forward slashes.</p>
      </item>
      <item pad-after='no'>
        <p pad-after='no' no-indent='yes'>(HACK) OOC sometimes treats paths like "c:/.." as relative, erroneously applying transformations on repository paths. For now, we treat all absolute paths as relative to the CURRENT drive.</p>
      </item>
    </itemize>
  </oberon-doc>
  <import-decl name='CharClass' id='CharClass' export='no' module='CharClass'/>
  <import-decl name='C' id='C' export='no' module='C'/>
  <import-decl name='IO' id='IO' export='no' module='IO'/>
  <import-decl name='StdChannels' id='StdChannels' export='no' module='IO:StdChannels'/>
  <procedure name='Normalize' id='Normalize' export='yes'>
    <oberon-doc>
      <summary>Convert path from host OS to normal form.</summary>
      <p pad-after='yes' no-indent='yes'>Convert path from host OS to normal form.</p>
    </oberon-doc>
    <formal-parameters>
      <parameter-decl name='path' id='Normalize.path' export='no' variable-parameter='no'>
        <type>
          <type-name name='STRING' href='#STRING'/>
        </type>
      </parameter-decl>
      <result-type>
        <type-name name='STRING' href='#STRING'/>
      </result-type>
      <exceptions>
        <type-name module='IO' name='Error' href='IO#Error'/>
      </exceptions>
    </formal-parameters>
  </procedure>
  <procedure name='Denormalize' id='Denormalize' export='yes'>
    <oberon-doc>
      <summary>Convert path from normal to host OS form.</summary>
      <p pad-after='yes' no-indent='yes'>Convert path from normal to host OS form.</p>
    </oberon-doc>
    <formal-parameters>
      <parameter-decl name='path' id='Denormalize.path' export='no' variable-parameter='no'>
        <type>
          <type-name name='STRING' href='#STRING'/>
        </type>
      </parameter-decl>
      <result-type>
        <type-name name='STRING' href='#STRING'/>
      </result-type>
    </formal-parameters>
  </procedure>
  <import-decl name='-RT0' id='-RT0' export='no' module='RT0'/>
  <import-decl name='-Object' id='-Object' export='no' module='Object'/>
  <import-decl name='-Exception' id='-Exception' export='no' module='Exception'/>
  <module-ref name='IO'>
    <ref-target type='html' relative-uri='../IO.html'/>
  </module-ref>
</interface-description>
