|
|
Boost-Commit : |
Subject: [Boost-commit] svn:boost r59418 - in sandbox/filesystem-v3/libs/filesystem: doc example
From: bdawes_at_[hidden]
Date: 2010-02-01 09:38:56
Author: bemandawes
Date: 2010-02-01 09:38:55 EST (Mon, 01 Feb 2010)
New Revision: 59418
URL: http://svn.boost.org/trac/boost/changeset/59418
Log:
Tutorial work-in-progress
Text files modified:
sandbox/filesystem-v3/libs/filesystem/doc/reference.html | 4
sandbox/filesystem-v3/libs/filesystem/doc/tutorial.html | 233 +++++++++++++++++++++++++--------------
sandbox/filesystem-v3/libs/filesystem/example/tut4.cpp | 3
3 files changed, 151 insertions(+), 89 deletions(-)
Modified: sandbox/filesystem-v3/libs/filesystem/doc/reference.html
==============================================================================
--- sandbox/filesystem-v3/libs/filesystem/doc/reference.html (original)
+++ sandbox/filesystem-v3/libs/filesystem/doc/reference.html 2010-02-01 09:38:55 EST (Mon, 01 Feb 2010)
@@ -946,7 +946,7 @@
!empty()</code>, beginning
with the first <i>filename</i> after <i>root-path</i>. Otherwise, <code>path()</code>.</p>
</blockquote>
-<pre>path filename() const;</pre>
+<pre>path <a name="path-filename">filename</a>() const;</pre>
<blockquote>
<p><i>Returns:</i> <code>empty() ? path() : *--end()</code></p>
</blockquote>
@@ -3185,7 +3185,7 @@
<p>Distributed under the Boost Software License, Version 1.0. See
<a href="http://www.boost.org/LICENSE_1_0.txt">www.boost.org/LICENSE_1_0.txt</a></p>
<p>Revised
-<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B %Y" startspan -->20 January 2010<!--webbot bot="Timestamp" endspan i-checksum="32134" --></p>
+<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B %Y" startspan -->01 February 2010<!--webbot bot="Timestamp" endspan i-checksum="40539" --></p>
</body>
Modified: sandbox/filesystem-v3/libs/filesystem/doc/tutorial.html
==============================================================================
--- sandbox/filesystem-v3/libs/filesystem/doc/tutorial.html (original)
+++ sandbox/filesystem-v3/libs/filesystem/doc/tutorial.html 2010-02-01 09:38:55 EST (Mon, 01 Feb 2010)
@@ -96,23 +96,18 @@
and then built. You are encouraged to modify and experiment with them as the
tutorial progresses. Just invoke the <code>bld</code> script again to rebuild.</p>
-<p>If something didn't work right, here are some troubleshooting suggestions:</p>
-
-<blockquote>
-
-<p><b>Windows:</b></p>
+<p>If something didn't work right, here are troubleshooting suggestions:</p>
<ul>
- <li><code>'bjam' is not recognized as an internal or external command,
- operable program or batch file</code>. The bjam program isn't being found.
+ <li>The <code>bjam</code> program executable isn't being found.
Check your path environmental variable if it should have been found,
otherwise see
<a href="http://www.boost.org/more/getting_started/windows.html">Boost
- Getting Started</a>.</li>
+ Getting Started</a>.<br>
+ </li>
<li>Look at <code>bjam.log</code> to try to spot an indication of the
problem.</li>
</ul>
-</blockquote>
<h2>tut1.cpp - Reporting the size of a file</h2>
@@ -164,11 +159,13 @@
<td align="center" style="font-size: 10pt"><i><b>Microsoft Windows</b></i></td>
</tr>
<tr>
- <td width="50%" style="font-size: 10pt">
- <pre><span style="background-color: #FFFF00">$ ./tut1 tut1.cpp
-tut1.cpp: 570</span></pre>
+ <td width="50%" style="font-size: 10pt" valign="top">
+ <pre>$ ./tut1 tut1.cpp
+tut1.cpp: 570</pre>
+ <pre>$ ls -l tut1.cpp
+-rwxrwxrwx 1 root root 570 2010-02-01 07:31 tut1.cpp</pre>
</td>
- <td style="font-size: 10pt">
+ <td style="font-size: 10pt" valign="top">
<pre>>tut1 tut1.cpp
tut1.cpp: 593
>dir tut1.cpp
@@ -184,18 +181,25 @@
used <code>"\r\n"</code> line endings.</p>
<p>Now try again, but give a path that doesn't exist:</p>
- <table align="center" border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" bgcolor="#D7EEFF" width="90%">
+ <table align="center" border="1" cellpadding="5" cellspacing="0"
+ style="border-collapse: collapse" bordercolor="#111111" bgcolor="#D7EEFF" width="90%">
<tr>
<td align="center" width="50%" style="font-size: 10pt"><i><b>Ubuntu Linux </b></i></td>
<td align="center" style="font-size: 10pt"><i><b>Microsoft Windows</b></i></td>
</tr>
<tr>
- <td width="50%" style="font-size: 10pt">
- <pre>$ ./tut1 foo</pre>
+ <td width="50%" style="font-size: 10pt" valign="top">
+ <pre>$ ./tut1 foo
+terminate called after throwing an instance of 'boost::exception_detail::
+clone_impl<boost::exception_detail::error_info_injector<boost::
+filesystem::filesystem_error> >'
+ what(): boost::filesystem::file_size: No such file or directory: "foo"
+Aborted</pre>
</td>
- <td style="font-size: 10pt">
+ <td style="font-size: 10pt" valign="top">
<pre>>tut1 foo</pre>
- </td>
+ <p><b><i>An exception is thrown; the exact form of the response depends on
+ Windows system options.</i></b></td>
</tr>
</table>
@@ -211,11 +215,17 @@
</tr>
<tr>
<td width="50%" style="font-size: 10pt">
- <pre>$ ./tut1 .</pre>
+ <pre>$ ./tut1 .
+terminate called after throwing an instance of 'boost::exception_detail::
+clone_impl<boost::exception_detail::error_info_injector<boost::
+filesystem::filesystem_error> >'
+ what(): boost::filesystem::file_size: Operation not permitted "."
+Aborted</pre>
</td>
- <td style="font-size: 10pt">
+ <td style="font-size: 10pt" valign="top">
<pre>>tut1 .</pre>
- </td>
+ <p><b><i>An exception is thrown; the exact form of the response depends on
+ Windows system options.</i></b></td>
</tr>
</table>
@@ -226,14 +236,17 @@
<h2>tut2.cpp - Using status queries to determine file existence and type</h2>
-<p>Boost.filesystem includes status query functions such as <code>exists</code>,
-<code>is_directory</code>, and <code>is_regular_file</code>. These all return
+<p>Boost.Filesystem includes status query functions such as <code>
+exists</code>,
+<code>is_directory</code>, and <code>
+is_regular_file</code>. These return
<code>bool</code>'s, and will return <code>true</code> if the condition
-described by their name is met. They return <code>false</code> when any element
+described by their name is met. Otherwise they return <code>false</code>,
+including when any element
of the path argument can't be found.</p>
<p>tut2.cpp uses several of the status query functions to cope with non-existent
-files and with different file types. </p>
+files and with different kinds of files:</p>
<table align="center" border="1" cellpadding="3" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" bgcolor="#D7EEFF" width="90%">
<tr>
@@ -275,10 +288,15 @@
<td align="center" style="font-size: 10pt"><i><b>Microsoft Windows</b></i></td>
</tr>
<tr>
- <td width="50%" style="font-size: 10pt">
- <pre><span style="background-color: #FFFF00">$ ./tut2 ..</span></pre>
+ <td width="50%" style="font-size: 10pt" valign="top">
+ <pre>$ ./tut2 tut2.cpp
+tut2.cpp: 1037
+$ ./tut2 foo
+foo: does not exist
+$ ./tut2 .
+.: is a directory</pre>
</td>
- <td style="font-size: 10pt">
+ <td style="font-size: 10pt" valign="top">
<pre>>tut2 tut2.cpp
tut2.cpp: 1079
@@ -291,7 +309,7 @@
</tr>
</table>
-<p>Although tut2 works, the output is less than
+<p>Although tut2 works OK, the output is less than
satisfactory for a directory since we'd typically like to see the directory's contents. Move
on to <code>tut3.cpp</code> to see how to iterate over directories.</p>
@@ -364,7 +382,7 @@
<td align="center" style="font-size: 10pt"><i><b>Microsoft Windows</b></i></td>
</tr>
<tr>
- <td width="50%" style="font-size: 10pt">
+ <td width="50%" style="font-size: 10pt" valign="top">
<pre>$ ./tut3 ~/boost/trunk
/home/beman/boost/trunk: is a directory containing:
/home/beman/boost/trunk/tools
@@ -373,7 +391,6 @@
/home/beman/boost/trunk/doc
/home/beman/boost/trunk/bootstrap.sh
/home/beman/boost/trunk/index.html
- /home/beman/boost/trunk/bin.v2
/home/beman/boost/trunk/bootstrap.bat
/home/beman/boost/trunk/boost.css
/home/beman/boost/trunk/INSTALL
@@ -391,11 +408,10 @@
/home/beman/boost/trunk/status
/home/beman/boost/trunk/CMakeLists.txt</pre>
</td>
- <td style="font-size: 10pt">
+ <td style="font-size: 10pt" valign="top">
<pre>>tut3 c:\boost\trunk
c:\boost\trunk: is a directory containing:
c:\boost\trunk\.svn
- c:\boost\trunk\bin.v2
c:\boost\trunk\boost
c:\boost\trunk\boost-build.jam
c:\boost\trunk\boost.css
@@ -421,20 +437,101 @@
</tr>
</table>
+<p>Not bad, but we can make further improvements:</p>
+
+ <ul>
+ <li>The listing would be much easier to read if only the filename was
+ displayed, rather than the full path.<br>
+ </li>
+ <li>The Linux listing isn't sorted. That's because the ordering of
+ directory iteration is unspecified. Ordering depends on the underlying
+ operating system API and file system specifics. So we need to sort the
+ results ourselves. </li>
+ </ul>
+
<h2>tut4.cpp - Using a path decomposition
-function and sorting results</h2>
+function, plus sorting results</h2>
-<p>It might be clearer to output just the filename, without the parent path. Class
-<code>path</code> has a decomposition function to extract the filename, so
-that's easy to try. Just change</p>
-<blockquote>
- <pre>cout << " " << *it << '\n';</pre>
-</blockquote>
-<p>to</p>
-<blockquote>
- <pre>cout << " " << it->path().filename() << '\n'; </pre>
-</blockquote>
-<p>Here is the output from <code>tut4.cpp</code>, which makes that change:</p>
+ <p>blah, blah</p>
+
+<p> </p>
+
+<table align="center" border="1" cellpadding="3" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" bgcolor="#D7EEFF" width="90%">
+ <tr>
+ <td style="font-size: 10pt">
+ <pre>tut4.cpp</pre>
+ <blockquote style="font-size: 10pt">
+ <pre>int main(int argc, char* argv[])
+{
+ path p (argv[1]); // p reads clearer than argv[1] in the following code
+
+ cout << p << ": "; // utilize the path narrow stream inserter
+
+ if ( exists(p) ) // does p actually exist?
+ {
+ if ( is_regular_file(p) ) // is p a regular file?
+ cout << file_size(p) << '\n';
+
+ else if ( is_directory(p) ) // is p a directory?
+ {
+ cout << "is a directory containing:\n";
+
+ typedef vector<path> vec; // store paths,
+ vec v; // so we can sort them later
+
+ for ( directory_iterator it (p); // initialize it to the first element
+ it != directory_iterator(); // test for the past-the-end element
+ ++it ) // increment
+ {
+ path fn = it->path().filename(); // extract the filename from the path
+ v.push_back(fn); // push into vector for later sorting
+ }
+
+ sort(v.begin(), v.end()); // sort, since directory iteration
+ // is not ordered on some file systems
+
+ for (vec::const_iterator it (v.begin()); it != v.end(); ++it)
+ {
+ cout << " " << *it << '\n';
+ }
+ }
+
+ else
+ cout << "exists, but is neither a regular file nor a directory\n";
+ }
+ else
+ cout << "does not exist\n";
+
+ return 0;
+}</pre>
+ </blockquote>
+ </td>
+ </tr>
+</table>
+
+ <p>The key change between <code>tut3.cpp</code> and <code>tut4.cpp</code> is
+ what happens in the directory iteration loop. We changed:</p>
+ <blockquote>
+ <pre>cout << " " << *it << '\n'; // *it returns a directory_entry,</pre>
+ </blockquote>
+ <p>to:</p>
+ <blockquote>
+ <pre>path fn = it->path().filename(); // extract the filename from the path
+v.push_back(fn); // push into vector for later sorting</pre>
+ </blockquote>
+ <p><code>path()</code>
+ is a <code>directory_entry</code> observer function. <code>
+ filename()</code> is one of
+ several path decomposition functions. It extracts the filename portion (<code>"foo.txt"</code>)
+ from a path (<code>"/bar/foo.txt"</code>). These decomposition functions are
+ explored in the <a href="#path-iteration-etc">Path iterators, observers,
+ composition, decomposition and query</a> portion of this tutorial.</p>
+ <p>We wrote the above as two lines of code for clarity. It could have been
+ written more concisely as:</p>
+ <blockquote>
+ <pre>v.push_back(it->path().filename()); // we only care about the filename</pre>
+ </blockquote>
+ <p>Here is the output from a test of <code>tut4.cpp</code>:</p>
<table align="center" border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" bgcolor="#D7EEFF" width="90%">
<tr>
@@ -495,7 +592,10 @@
</tr>
</table>
-<h2>path_info.cpp - Path iterators, observers, composition, decomposition and query</h2>
+ <hr>
+
+<h2>path_info.cpp
+<a name="path-iteration-etc"></a>- Path iterators, observers, composition, decomposition and query</h2>
<p>The <code>path_info</code> program is handy for learning how class <code>path</code>
iterators,
@@ -752,45 +852,6 @@
</tr>
</table>
-<h3>Directory iteration tweak - tut4.cpp</h3>
-
-<table align="center" border="1" cellpadding="3" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" bgcolor="#D7EEFF" width="90%">
- <tr>
- <td style="font-size: 10pt">
- <pre>tut4.cpp</pre>
- <blockquote>
- <pre>int main(int argc, char* argv[])
-{
- path p (argv[1]);
-
- cout << p << ": ";
- if ( exists(p) )
- {
- if ( is_regular_file(p) )
- cout << file_size(p) << '\n';
- else if ( is_directory(p) )
- {
- cout << "is a directory containing:\n";
- for ( directory_iterator it (p); it != directory_iterator (); ++it )
- {
- <span style="background-color: #88FFA3">cout << " " << it-></span><span style="background-color: #88FFA3">path().filename</span><span style="background-color: #88FFA3">() << '\n';</span>
- }
- }
- else
- cout << "exists, but is neither a regular file nor a directory\n";<span style="background-color: #88FFA3">
-</span> }
- else
- cout << "does not exist\n";
-
- return 0;
-}</pre>
- </blockquote>
- </td>
- </tr>
-</table>
-
-<h3>Error handling - tut5.cpp</h3>
-
<hr>
<h3><a name="Class-path">Class path</a></h3>
@@ -873,7 +934,7 @@
<p>Distributed under the Boost Software License, Version 1.0. See
<a href="http://www.boost.org/LICENSE_1_0.txt">www.boost.org/LICENSE_1_0.txt</a></p>
<p>Revised
-<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B %Y" startspan -->31 January 2010<!--webbot bot="Timestamp" endspan i-checksum="32137" --></p>
+<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B %Y" startspan -->01 February 2010<!--webbot bot="Timestamp" endspan i-checksum="40539" --></p>
</body>
Modified: sandbox/filesystem-v3/libs/filesystem/example/tut4.cpp
==============================================================================
--- sandbox/filesystem-v3/libs/filesystem/example/tut4.cpp (original)
+++ sandbox/filesystem-v3/libs/filesystem/example/tut4.cpp 2010-02-01 09:38:55 EST (Mon, 01 Feb 2010)
@@ -42,7 +42,8 @@
it != directory_iterator(); // test for the past-the-end element
++it ) // increment
{
- v.push_back(it->path().filename()); // we only care about the filename
+ path fn = it->path().filename(); // extract the filename from the path
+ v.push_back(fn); // push into vector for later sorting
}
sort(v.begin(), v.end()); // sort, since directory iteration
Boost-Commit list run by bdawes at acm.org, david.abrahams at rcn.com, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk