Changeset 14794


Ignore:
Timestamp:
May 11, 2011, 5:49:40 PM (8 years ago)
Author:
rme
Message:

Document native-translated-namestring and with-filename-cstrs.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/source/doc/src/using.xml

    r14746 r14794  
    16241624        to the directory containing the current heap image.</para>
    16251625    </sect2>
    1626    
    1627    
     1626    <sect2 id="pathname-namestrings">
     1627      <title>Pathname Namestrings</title>
     1628      <para>
     1629        The syntax of namestrings is implementation-defined in Common Lisp.
     1630        Portable programs cannot assume much of anything about them.  (See
     1631        section 19.1.1 of the Common Lisp standard for more information.)
     1632      </para>
     1633      <para>
     1634        When translating a namestring into a pathname object, most
     1635        implementations seem to follow the convention that a dot
     1636        character in the namestring separates the
     1637        <literal>pathname-name</literal> and
     1638        the <literal>pathname-type</literal>.  When there is more
     1639        than one dot in involved, or when dots appear at the beginning
     1640        or end of the namestrings, what to do is less clear: does
     1641        ".emacs" describe a pathname whose name is
     1642        <literal>nil</literal> and whose type is <literal>emacs</literal>
     1643        or something else?  Similarly, given "a.b.c", the question
     1644        is which parts are parsed as the pathname name, and which are
     1645        parsed as the pathname type?
     1646      </para>
     1647      <para>
     1648        When generating a namestring from a pathname object (as happens,
     1649        for example, when printing a pathname), &CCL;
     1650        tries to avoid some potential ambiguity by escaping characters
     1651        that might otherwise be used to separate pathname components.
     1652        The character used to quote or escape the separators is a
     1653        backlash on Unix systems, and a #\&gt; character on Windows.
     1654        So, for example, "a\\.b.c"
     1655        has name "a.b" and type "c", whereas "a.b\\.c" has name
     1656        "a" and type "b.c".
     1657      </para>
     1658      <para>
     1659        To get a native namestring suitable for passing to an
     1660        operating system command, use the function
     1661        <literal>ccl:native-translated-namestring</literal>.
     1662      </para>
     1663
     1664    <sect3>
     1665      <title>Working with native namestrings</title>
     1666      <refentry id="f_native-translated-namestring">
     1667        <indexterm zone="f_native-translated-namestring">
     1668          <primary>native-translated-namestring</primary>
     1669        </indexterm>
     1670       
     1671        <refnamediv>
     1672          <refname>native-translated-namestring</refname>
     1673          <refpurpose>
     1674            Return a namestring that uses the conventions of the
     1675            native operating system.
     1676          </refpurpose>
     1677          <refclass>Function</refclass>
     1678        </refnamediv>
     1679       
     1680        <refsynopsisdiv>
     1681          <synopsis><function>native-translated-namestring</function> pathname-designator</synopsis>
     1682        </refsynopsisdiv>
     1683       
     1684        <refsect1><title>Description</title>
     1685        <para>
     1686          This function returns a namestring that represents a pathname
     1687          using the native conventions of the operating system.
     1688          Any quoting or escaping of special characters will be removed.
     1689        </para>
     1690        <para>
     1691          For example, suppose that <varname>p</varname> is a pathname made
     1692          by <literal>(make-pathname :name "a.b" :type "c")</literal>.
     1693          Then, <literal>(native-translated-namestring p)</literal> evaluates
     1694          to "a.b.c".  By contrast, <literal>(namestring p)</literal> evaluates
     1695          to "a\\.b.c".
     1696        </para>
     1697        </refsect1>
     1698      </refentry>
     1699
     1700      <refentry id="m_with-filename-cstrs">
     1701        <indexterm zone="m_with-filename-cstrs">
     1702          <primary>with-filename-cstrs</primary>
     1703        </indexterm>
     1704       
     1705        <refnamediv>
     1706          <refname>with-filename-cstrs</refname>
     1707          <refpurpose>
     1708            Suitably encode strings to be used as filenames for foreign code.
     1709          </refpurpose>
     1710          <refclass>Macro</refclass>
     1711        </refnamediv>
     1712       
     1713        <refsynopsisdiv>
     1714          <synopsis><function>with-filename-cstrs</function> ( {(var value)}* ) {form}*</synopsis>
     1715        </refsynopsisdiv>
     1716       
     1717        <refsect1><title>Description</title>
     1718        <para>
     1719          Executes <varname>forms</varname> in an environemt in which each
     1720          <varname>var</varname> is bound to a stack-allocated foreign
     1721          pointer which refers to a C-style string suitable for passing
     1722          to foreign code which expects a filename argument.
     1723        </para>
     1724        <para>
     1725          For example, one might use this macro in the following way:
     1726  <programlisting>
     1727(with-filename-cstrs ((s (native-translated-namestring pathname)))
     1728  (#_unlink s))
     1729  </programlisting>
     1730        </para>
     1731        <para>
     1732          Various operating systems have different conventions for how
     1733          they expect native pathname strings to be encoded.  Darwin
     1734          expects then to be decomposed UTF-8.  The Unicode variants
     1735          to Windows file-handling functions expect UTF-16.  Other
     1736          systems just treat them as opaque byte sequences.  This macro
     1737          ensures that the correct encoding is used, whatever
     1738          the host operating system.
     1739        </para>
     1740        </refsect1>
     1741      </refentry>
     1742    </sect3>
     1743  </sect2>
    16281744    <sect2 id="pathnames-on-darwin">
    16291745      <title>OS X (Darwin)</title>
Note: See TracChangeset for help on using the changeset viewer.