Home My Page Projects Code Snippets Project Openings SML/NJ
 Summary Activity Forums Tracker Lists Tasks Docs Surveys News SCM Files

# SCM Repository

[smlnj] Diff of /sml/trunk/src/cm/Doc/manual.tex
 [smlnj] / sml / trunk / src / cm / Doc / manual.tex

# Diff of /sml/trunk/src/cm/Doc/manual.tex

revision 653, Wed Jun 7 07:59:06 2000 UTC revision 672, Mon Jun 19 04:40:29 2000 UTC
# Line 288  Line 288
288  \section{Naming objects in the file system}  \section{Naming objects in the file system}
289
290  \subsection{Motivation}  \subsection{Motivation}
\label{sec:implicit}
291
292  File naming has been an area notorious for its problems and was the  File naming has been an area notorious for its problems and was the
293  cause of most of the gripes from CM's users.  With this in mind, CM  cause of most of the gripes from CM's users.  With this in mind, CM
# Line 312  Line 311
311  \subsection{Basic rules}  \subsection{Basic rules}
312  \label{sec:basicrules}  \label{sec:basicrules}
313
314  CM uses its own standard'' syntax for pathnames which happens to be  CM uses its own standard'' syntax for pathnames which for the most
315  the same as the one used by most Unix-like systems: path name  part happens to be the same as the one used by most Unix-like systems:
316  components are separated by {\bf /}'', paths beginning with {\bf  path name components are separated by {\bf /}'', paths beginning
317  /}'' are considered {\em absolute} while other paths are {\em  with {\bf /}'' are considered {\em absolute} while other paths are
318  relative}.  {\em relative}.  There is an important third form of standard paths:
319    {\em anchored} paths.  Anchored paths always start with {\bf \$}''. 320 321 Since this standard syntax does not cover system-specific aspects such Since this standard syntax does not cover system-specific aspects such 322 as volume names, it is also possible to revert to native'' syntax by as volume names, it is also possible to revert to native'' syntax by # Line 324 Line 324 324 that use path names in native syntax are not portable across operating that use path names in native syntax are not portable across operating 325 systems. systems. 326 327 Absolute pathnames are resolved in the usual manner specific to the \begin{description} 328 operating system. However, it is advisable to avoid absolute \item[Absolute pathnames] are resolved in the usual manner 329 pathnames because they are certain to break'' if the corresponding specific to the operating system. However, it is advisable to avoid 330 file moves to a different location. absolute pathnames because they are certain to break'' if the 331 corresponding file moves to a different location. 332 The resolution of relative pathnames is more complicated: \item[Relative pathnames that occur in some CM description file] whose 333 name is {\it path}{\tt /}{\it file}{\tt .cm} will be resolved relative 334 \begin{itemize} to {\it path}, i.e., relative to the directory that contains the 335 \item If the first component of a relative pathname is a description file. 336 {\em configuration anchor} (see Section~\ref{sec:anchors}), then we call \item[Relative pathnames that have been entered interactively,] for 337 the path {\em implicitly anchored}. In this case\footnote{as long as example as an argument to one of CM's interface functions, CM.Anchor.implict\_anchors is enabled, which currently is the default (see Section~\ref{sec:api})} the whole name will be resolved relative to the value associated with that anchor. For example, if the path is {\tt foo/bar/baz} and {\tt foo} is known as an anchor mapped to {\tt /usr/local}, then the full name of the actual file system object referred to is {\tt /usr/local/foo/bar/baz}. Note that the {\tt foo} component is not stripped away during the resolution process; different anchors that map to the same directory still remain different. \\ {\bf Warning:} Implicitly anchored paths are now considered obsolete! Support for them will disappear soon in future versions of CM. \item Otherwise, if the relative name appears in some description file whose name is {\it path}{\tt /}{\it file}{\tt .cm}, then it will be resolved relative to {\it path}, i.e., relative to the directory that contains the description file. \item If a non-anchored relative path is entered interactively, for example as an argument to one of CM's interface functions, then it 338 will be resolved in the OS-specific manner, i.e., relative to the will be resolved in the OS-specific manner, i.e., relative to the 339 current working directory. However, CM will internally represent the current working directory. However, CM will internally represent the 340 name in such a way that it remembers the corresponding working name in such a way that it remembers the corresponding working # Line 361 Line 344 344 working directory. As a result, two names specified using identical working directory. As a result, two names specified using identical 345 strings but at different times when different working directories were strings but at different times when different working directories were 346 in effect will be kept distinct and continue to refer to the file in effect will be kept distinct and continue to refer to the file 347 system location that they referred to when they were first seen. system locations that they referred to when they were first seen. 348 \end{itemize} \item[Anchored paths] consist of an anchor name (of non-zero length) 349 and a non-empty list of additional arcs. The name is enclosed by 350 \subsection{Explicitly anchored paths} the path's leading {\bf \$} on the left and the path's first {\bf /}
351    on the right.  The list of arcs follows the first {\bf /}.  As with
352  When path anchors are used, their use should be syntactically  all standard paths, the arcs themselves are also separated by {\bf /}.
353  obvious.  Therefore, the use of {\em explicitly anchored paths} is now  An error is signalled if the anchor name is not known to CM.
354  preferred over their implicit counterparts.  If $a$ is a know anchor name currently bound to some directory name
355    $d$, then the standard path {\tt \$}$a${\tt /}$p$(where$p$is a list 356 To specify an explicitly anchored path, the first component of a of arcs) refers to$d${\tt /}$p$. The frequently occuring case where 357 standard'' path must start with a dollar symbol {\bf \$}.  The  $a$ coincides with the first arc of $p$ can be abbreviated as {\tt
358  string between {\bf \$} and the first {\bf /} is taken to be the name \$/}$p$.
359  of the anchor and the string after that {\bf /} is the path relative  \end{description}
to the anchor.  An error is signalled whenever the anchor name does
not correspond to an existing anchor.

Note that any implicitly anchored'' path {\tt foo/bar/baz} (as
described above) can always be re-written as\linebreak {\tt
\$foo/foo/bar/baz}. Moreover, the explicit form is slightly more expressive as it permits names such as {\tt \$a/b/c} where the anchor
name and the first arc do not coincide.

One can abbreviate the frequent case where they do coincide without
resorting to implicit syntax by writing\linebreak {\tt \$/foo/bar/baz} instead of the lengthier {\tt \$foo/foo/bar/baz}.

Another (somewhat controversial) shorthand is the following: if an
explicitly anchored path has only one component and the component
coincides with the anchor name, then one can abbreviate it further by
writing just {\tt \$foo} instead of {\tt \$/foo} or even {\tt
\\$foo/foo}.
360
361  \subsection{Anchor configuration}  \subsection{Anchor configuration}
362  \label{sec:anchors}  \label{sec:anchors}
# Line 552  Line 517
517      val parse_caching : int controller      val parse_caching : int controller
518      val warn_obsolete : bool controller      val warn_obsolete : bool controller
519      val conserve_memory : bool controller      val conserve_memory : bool controller
val implicit_anchors : bool controller
520    end    end
521  \end{verbatim}  \end{verbatim}
522
# Line 603  Line 567
567  The default ({\em false}) can be overridden at startup by the  The default ({\em false}) can be overridden at startup by the
568  environment variable {\tt CM\_CONSERVE\_MEMORY}.  environment variable {\tt CM\_CONSERVE\_MEMORY}.
569
The {\tt CM.Control.implicit\_anchors} controller has been added
temporarily while support for {\em implicitly anchored paths} (see
Section~\ref{sec:implicit}) is being faded out.  If set to {\tt
false}, CM will check for implicitly anchored paths and issue an
error; this is the default.  Changing the value to {\tt true} (e.g.,
by setting the environment variable {\tt CM\_IMPLICIT\_ANCHORS at
startup}) causes implicit anchors to be accepted.

570  \subsubsection*{Path anchors}  \subsubsection*{Path anchors}
571
572  Structure {\tt CM} also provides functions to explicitly manipulate  Structure {\tt CM} also provides functions to explicitly manipulate
# Line 2328  Line 2284
2284          val warn_obsolete : bool controller          val warn_obsolete : bool controller
2285          val debug : bool controller          val debug : bool controller
2286          val conserve_memory : bool controller          val conserve_memory : bool controller
val implicit_anchors : bool controller
2287      end      end
2288
2289      structure Library : sig      structure Library : sig
# Line 2448  Line 2403
2403  description files \\  description files \\
2404  {\tt conserve\_memory} & {\tt CONSERVE\_MEMORY} & {\tt bool} & {\tt  {\tt conserve\_memory} & {\tt CONSERVE\_MEMORY} & {\tt bool} & {\tt
2405  false} & same & avoid repeated I/O operations by keeping certain  false} & same & avoid repeated I/O operations by keeping certain
2406  information in main memory \\  information in main memory
{\tt implicit\_anchors} & {\tt IMPLICIT\_ANCHORS} & {\tt bool} & {\tt
true} & same & recognize implicitly anchored paths
2407  \end{tabular}  \end{tabular}
2408  \end{small}  \end{small}
2409  \end{center}  \end{center}

Legend:
 Removed from v.653 changed lines Added in v.672