folio 0.3.0 → 0.4.0

data/doc/log/changelog.xml

@@ -0,0 +1,129 @@
+<?xml version="1.0"?>
+<log>
+<entry>
+  <date>Tue Sep 16 13:18:40 -0400 2008</date>
+  <author> trans <transfire@gmail.com></author>
+  <revison>77b1389e5bccf8b5052152a8d75cc0c00b1d1b52</revison>
+  <type></type>
+  <message>added more spec fictures</message>
+</entry>
+<entry>
+  <date>Tue Sep 16 13:18:06 -0400 2008</date>
+  <author> trans <transfire@gmail.com></author>
+  <revison>8a2eb973587d99ef4978191eececf6d0f588b90a</revison>
+  <type></type>
+  <message>improved error messages</message>
+</entry>
+<entry>
+  <date>Tue Sep 16 13:16:36 -0400 2008</date>
+  <author> trans <transfire@gmail.com></author>
+  <revison>7e0c67bf84574d0343ce78330959f5bf5335247f</revison>
+  <type></type>
+  <message>added LinkNotFound error</message>
+</entry>
+<entry>
+  <date>Tue Sep 16 13:16:03 -0400 2008</date>
+  <author> trans <transfire@gmail.com></author>
+  <revison>8b72d67261db24f2b40597c34827a35441d76c30</revison>
+  <type></type>
+  <message>remarked out Folio shortcut #[] method for time being</message>
+</entry>
+<entry>
+  <date>Tue Sep 16 11:53:43 -0400 2008</date>
+  <author> trans <transfire@gmail.com></author>
+  <revison>b1ed5ded2ec3798397461004186bb7b59b9d1ef9</revison>
+  <type></type>
+  <message>added spec for link.rb</message>
+</entry>
+<entry>
+  <date>Tue Sep 16 11:42:22 -0400 2008</date>
+  <author> trans <transfire@gmail.com></author>
+  <revison>5d2f4d23c060c92d5e7e843079379f43e4d881e0</revison>
+  <type></type>
+  <message>removed relpath</message>
+</entry>
+<entry>
+  <date>Tue Sep 16 11:41:04 -0400 2008</date>
+  <author> trans <transfire@gmail.com></author>
+  <revison>b9a38c5a8370aa7e4cf57bba80bdafbc39cdb674</revison>
+  <type></type>
+  <message>renamed spec_prompt.rb to spec_shell.rb</message>
+</entry>
+<entry>
+  <date>Tue Sep 16 11:30:40 -0400 2008</date>
+  <author> trans <transfire@gmail.com></author>
+  <revison>da2eb57bccd4400e0b272836ad9cf23ce23d6b19</revison>
+  <type>major</type>
+  <message>Renamed Prompt to Shell. </message>
+</entry>
+<entry>
+  <date>Thu Sep 11 12:50:59 -0400 2008</date>
+  <author> trans <transfire@gmail.com></author>
+  <revison>e8dadfff85bbf3dc5cf8cced5be17b0789b04650</revison>
+  <type></type>
+  <message>moved test directory to spec directory</message>
+</entry>
+<entry>
+  <date>Thu Sep 11 12:44:48 -0400 2008</date>
+  <author> trans <transfire@gmail.com></author>
+  <revison>94d3c4989d012173606ddbc37ddf0a8bc702b661</revison>
+  <type></type>
+  <message>turned tests into specs</message>
+</entry>
+<entry>
+  <date>Thu Sep 11 12:44:07 -0400 2008</date>
+  <author> trans <transfire@gmail.com></author>
+  <revison>2454fe9d762aee096db7143dacc398582269690e</revison>
+  <type></type>
+  <message>fixed tests by adding #== to FileObject class</message>
+</entry>
+<entry>
+  <date>Wed Sep 10 16:30:28 -0400 2008</date>
+  <author> trans <transfire@gmail.com></author>
+  <revison>c07c7bd87c0109db8019cac1be89b217855397b5</revison>
+  <type></type>
+  <message>custom rdoc-template</message>
+</entry>
+<entry>
+  <date>Wed Sep 10 15:10:48 -0400 2008</date>
+  <author> trans <transfire@gmail.com></author>
+  <revison>b4cb8082c81719d5fa0788f0566fe28656f1533d</revison>
+  <type></type>
+  <message>added TODO and VERSION files</message>
+</entry>
+<entry>
+  <date>Wed Sep 10 15:06:56 -0400 2008</date>
+  <author> trans <transfire@gmail.com></author>
+  <revison>9a926a12a0b061c3ec9bfbd23f5387e65c1e7201</revison>
+  <type>major</type>
+  <message>Added XDG methods to Prompt class. </message>
+</entry>
+<entry>
+  <date>Wed Sep 10 14:16:35 -0400 2008</date>
+  <author> trans <transfire@gmail.com></author>
+  <revison>474f3f77720a102e47bcd699ae5700b7a40e741b</revison>
+  <type></type>
+  <message>moved METADATA to meta/</message>
+</entry>
+<entry>
+  <date>Sat Sep 06 12:59:40 -0400 2008</date>
+  <author> trans <transfire@gmail.com></author>
+  <revison>9714d9df4d409a4013acb6530ea3e3ce7b53acb5</revison>
+  <type></type>
+  <message>added .gitignore file</message>
+</entry>
+<entry>
+  <date>Sat Sep 06 12:58:25 -0400 2008</date>
+  <author> trans <transfire@gmail.com></author>
+  <revison>168a1faaf6148677bfdeec36793d4d141cf2a6d8</revison>
+  <type></type>
+  <message>reorganized project for reap changes</message>
+</entry>
+<entry>
+  <date>Thu Sep 04 17:03:44 -0400 2008</date>
+  <author> trans <transfire@gmail.com></author>
+  <revison>20c00238d1401c2b4385f0a6109c2c001b922008</revison>
+  <type>major</type>
+  <message>Started Repository. </message>
+</entry>
+</log>

data/doc/log/changelog.xsl

@@ -0,0 +1,33 @@
+<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
+
+  <xsl:output cdata-section-elements="script"/>
+
+  <xsl:template match="/">
+    <html>
+      <head>
+        <title>Changelog</title>
+        <link REL='SHORTCUT ICON' HREF="../img/ruby-sm.png" />
+        <style>
+          td { font-family: sans-serif;  padding: 0px 10px; }
+        </style>
+      </head>
+      <body>
+      <div class="container">
+        <h1>Changelog</h1>
+        <table style="width: 100%;">
+          <xsl:apply-templates />
+        </table>
+      </div>
+      </body>
+    </html>
+  </xsl:template>
+
+  <xsl:template match="entry">
+      <tr>
+        <td><b><pre><xsl:value-of select="msg"/></pre></b></td>
+        <td><xsl:value-of select="author"/></td>
+        <td><xsl:value-of select="date"/></td>
+      </tr>
+  </xsl:template>
+
+</xsl:stylesheet>

data/doc/log/notes.xml

@@ -0,0 +1,35 @@
+<notes>
+<set label="FIXME">
+<file src="lib/folio/minitar.rb">
+<note line="421" type="FIXME">FIXME: what if an exception is raised in the block?</note>
+<note line="458" type="FIXME">FIXME: what if an exception is raised in the block?</note>
+</file>
+</set>
+<set label="TODO">
+<file src="lib/folio/fileutils.rb">
+<note line="10" type="TODO">TODO: Rename to linkstage or something less likely to name clash?</note>
+<note line="22" type="TODO">TODO: dryrun test here or before folder creation?</note>
+</file>
+<file src="lib/folio/filetest.rb">
+<note line="33" type="TODO">TODO: Make more robust. Probably needs to be fixed for Windows.</note>
+<note line="52" type="TODO">TODO: Make more robust.</note>
+</file>
+<file src="lib/folio/fileobject.rb">
+<note line="204" type="TODO">TODO: I don&apos;t like the name of this.</note>
+</file>
+<file src="lib/folio/document.rb">
+<note line="40" type="TODO">TODO: how to handle unkinking (b/c file no longer exists)</note>
+</file>
+<file src="lib/folio/ziputils.rb">
+<note line="7" type="TODO">TODO: Much of this shells out. It would be best to internalize.</note>
+<note line="29" type="TODO">TODO: support gzip and bzip2 as well.</note>
+<note line="141" type="TODO">TODO: Write unified untar_gzip function.</note>
+</file>
+<file src="lib/folio/shell.rb">
+<note line="66" type="TODO">TODO: Should there be methods like this for each
+type, and raise an error if not the right type?</note>
+<note line="131" type="TODO">TODO: Ultimately merge #glob and #multiglob.</note>
+<note line="196" type="TODO">TODO: Is #out_of_date? this the same as #uptodate?</note>
+</file>
+</set>
+</notes>

data/{NEWS → doc/note/release-0.3.0.txt}

@@ -7,5 +7,5 @@ This is the third release since the initial idea.
 Techincally this is still "alpha" code as it needs
 many more tests. Nontheless, the library is a rather
 strightforward wrapper around Ruby internals, so it
-already fairly usable.
+is already very usable.
 

data/doc/spec/index.html

@@ -0,0 +1,552 @@
+<html>
+<head>
+  <title>Specifications</title>
+
+  <style>
+    #container{ margin: 0 auto; width: 800px; }
+    /* Debug borders */
+    p, li, dt, dd, div, pre, h1, h2, h3, h4, h5, h6 {
+    /*
+      border: 1px solid red;
+    */
+    }
+    body { font-size: 0.9em; margin: 1em 5% 1em 5%; }
+    a { color: blue; text-decoration: underline; }
+    a:visited { color: fuchsia; }
+    em { font-style: italic; }
+    strong { font-weight: bold; }
+    tt { color: navy; }
+    h1, h2, h3, h4, h5, h6 {
+      color: #527bbd;
+      font-family: sans-serif;
+      margin-top: 1.2em;
+      margin-bottom: 0.5em;
+      line-height: 1.3;
+    }
+    h1 { border-bottom: 2px solid silver; }
+    h2 { border-bottom: 2px solid silver; padding-top: 0.5em; }
+    hr { border: 1px solid silver; }
+    p { color: #555;
+        text-align: justify;
+        margin-top: 0.5em;
+        margin-bottom: 0.5em;
+        line-height: 1.4em;
+    }
+    pre { padding: 10; margin: 0; }
+
+    span#author {
+      color: #527bbd;
+      font-family: sans-serif;
+      font-weight: bold;
+      font-size: 1.1em;
+    }
+    span#email {
+    }
+    span#revision {
+      font-family: sans-serif;
+    }
+
+    div#footer {
+      font-family: sans-serif;
+      font-size: small;
+      border-top: 2px solid silver;
+      padding-top: 0.5em;
+      margin-top: 4.0em;
+    }
+
+    div#footer-text {
+      float: left;
+      padding-bottom: 0.5em;
+    }
+
+    div#footer-badges {
+      float: right;
+      padding-bottom: 0.5em;
+    }
+
+    div.content { /* Block element content. */
+      padding: 0;
+    }
+
+    /* Block element titles. */
+    h1.title {
+      font-family: sans-serif;
+      font-weight: bold;
+      text-align: left;
+      font-size: 3em;
+      margin-top: 1.0em;
+      margin-bottom: 0.5em;
+    }
+
+    /* Block element titles. */
+    div.title, caption.title {
+      font-family: sans-serif;
+      font-weight: bold;
+      text-align: left;
+      margin-top: 1.0em;
+      margin-bottom: 0.5em;
+    }
+    div.title + * {
+      margin-top: 0;
+    }
+
+    td div.title:first-child {
+      margin-top: 0.0em;
+    }
+    div.content div.title:first-child {
+      margin-top: 0.0em;
+    }
+    div.content + div.title {
+      margin-top: 0.0em;
+    }
+
+    div.sidebarblock > div.content {
+      background: #ffffee;
+      border: 1px solid silver;
+      padding: 0.5em;
+    }
+
+    img { border-style: none; }
+
+    dl { margin-top: 0.8em; margin-bottom: 0.8em; }
+    dt { margin-top: 0.5em; margin-bottom: 0; font-style: italic; }
+    dd > *:first-child { margin-top: 0; }
+    ul, ol { list-style-position: outside; }
+
+    thead { font-family: sans-serif; font-weight: bold; }
+    tfoot { font-weight: bold; }
+  </style>
+
+  <!-- JQuery is needed -->
+  <script src="../assets/scripts/jquery.js" type="text/javascript" language="javascript"></script>
+
+  
+
+  <link href="../assets/styles/spec.css" type="text/css" rel="stylesheet">
+</head>
+
+<body>
+
+  <!-- Side Table of Contents -->
+  <div id="sidebar" style="position: fixed; top: 10; right: 10; background: white;">
+    <a href="javascript: toc_toggle();">
+      <img src="img/icon/book.jpg" height="30px;" style="border: none;" alt="TOC" align="right"/>
+    </a>
+
+    <div id="toc_side" class="toc">
+    </div>
+  </div>
+
+  <div id="container">
+    <div id="header">
+      <img src="img/icon/book.jpg" align="left" style="padding-right: 10px;" alt=""/>
+
+      <h1 class="title">Specifications</h1>
+
+      <h1>Table of Contents</h1>
+
+      <div class="toc">
+      </div>
+    </div>
+
+    <div id="content">
+      <h1>Document Unit Testing</h1>
+<p>
+Load the Folio library.
+</p>
+<pre>
+  require 'folio'
+</pre>
+<p>
+Instantiate document object.
+</p>
+<pre>
+  @foo = Folio.file('fixtures/foo.txt')
+</pre>
+<p>
+Confirm it is a a document.
+</p>
+<pre>
+  @foo.assert.document?
+</pre>
+<p>
+Confirm it is equal to another document initialized identically.
+</p>
+<pre>
+  @foo.assert == Folio.file('fixtures/foo.txt')
+</pre>
+<p>
+Confirm it is equal to the same file initialized from a different working
+directory.
+</p>
+<pre>
+  f = nil
+  Dir.chdir('fixtures') do
+    f = Folio.file('foo.txt')
+  end
+  @foo.assert == f
+</pre>
+<p>
+Document can be read.
+</p>
+<pre>
+  @foo.read.assert == &quot;THIS IS FOO!\n&quot;
+</pre>
+<p>
+The #readlines methods read the document into an array of lines.
+</p>
+<pre>
+  @foo.readlines.assert == [&quot;THIS IS FOO!\n&quot;]
+</pre>
+<p>
+We can also open the document for reading using the more traditional open()
+method.
+</p>
+<pre>
+  t = nil
+  @foo.open('r'){ |f| t = f.read }
+  t.assert == &quot;THIS IS FOO!\n&quot;
+</pre>
+<p>
+The #parent method return the Directory object in which the document is
+contained.
+</p>
+<pre>
+  @foo.parent.assert == Folio.file('fixtures')
+</pre>
+<p>
+A document can be written to as well using the #write method.
+</p>
+<pre>
+  out = Folio.doc('fixtures/out.txt')
+  out.write('Hello')
+  File.read(out.to_s).assert == 'Hello'
+</pre>
+
+
+
+
+
+<h1>General Usage of Folio Link Object</h1>
+<p>
+Require the Folio library.
+</p>
+<pre>
+  require 'folio'
+</pre>
+<p>
+Instantiate a soft link.
+</p>
+<pre>
+  @foo = Folio.file('fixtures/foo_softlink.txt')
+</pre>
+<p>
+It is a link.
+</p>
+<pre>
+  @foo.link?.assert == true
+</pre>
+<p>
+It is equal to a link defined identically.
+</p>
+<pre>
+  @foo.assert == Folio.file('fixtures/foo_softlink.txt')
+</pre>
+<p>
+The link is not equal to the target document.
+</p>
+<pre>
+  @foo.assert! == Folio.file('fixtures/foo.txt')
+</pre>
+<p>
+But it is equal to a same link instantiated from a differnt working
+directory.
+</p>
+<pre>
+  f = nil
+  Dir.chdir('fixtures') do
+    f = Folio.file('foo_softlink.txt')
+  end
+  @foo.assert == f
+</pre>
+<p>
+Reads the linked document correctly.
+</p>
+<pre>
+  @foo.read == &quot;THIS IS FOO!&quot;
+</pre>
+<p>
+Opens the linked document for reading.
+</p>
+<pre>
+  t = nil
+  @foo.open('r'){ |f| t = f.read }
+  t.assert == &quot;THIS IS FOO!\n&quot;
+</pre>
+<p>
+It provides the parent directory object.
+</p>
+<pre>
+  @foo.parent.assert == Folio.dir('fixtures')
+</pre>
+
+
+
+
+<h1>General Usage of the Folio Shell</h1>
+<p>
+Require the Folio library.
+</p>
+<pre>
+  require 'folio'
+</pre>
+<p>
+Open a new Folio::Shell object.
+</p>
+<pre>
+  @c = Folio.shell('fixtures')
+</pre>
+<p>
+Method #work returns current working directory.
+</p>
+<pre>
+  @c.work.assert == Folio.dir('fixtures')
+</pre>
+<p>
+Method #to_s returns current working dirname.
+</p>
+<pre>
+  @c.to_s.assert == File.join(Dir.pwd, 'fixtures')
+</pre>
+<p>
+Method #entries returns a list of names of the current directory content.
+</p>
+<pre>
+  @c.entries.sort.assert == ['foo.txt', 'foo_softlink.txt', 'out.txt']
+</pre>
+<p>
+Method #files returns an array of file objects in the current directory.
+</p>
+<pre>
+  f = @c.files.to_a
+  f.size.assert == 3
+  f.assert.include?(Folio.file('fixtures/foo_softlink.txt'))
+  f.assert.include?(Folio.file('fixtures/foo.txt'))
+</pre>
+
+<h1>Problem Scenerios</h1>
+<h2>Non-existant paths</h2>
+<p>
+If a path does not exist, how do we know if it is intended to be a file, or
+directory, or what?
+</p>
+<pre>
+  d1 = dir('home/trans')
+  d2 = d1 / 'images'
+</pre>
+<p>
+Optons for resolution include:
+</p>
+<ul>
+<li>Do not support ambiguitous methods.
+
+</li>
+<li>Raise an error if non-existant.
+
+</li>
+<li>Default to a directory when ambiguious.
+
+</li>
+<li>Use a delegator.
+
+</li>
+</ul>
+<p>
+The first solution is the most straightforward. The second is reasonably
+viable as well, but at least it provides some understanble use for such
+methods.
+</p>
+<p>
+The return value of the third feels to quirky. And the last is a complex
+solution that effectively only leaves us with some sort of non-disk
+Pathname object; a solution almost a quirky.
+</p>
+<h2>Removal of file-io object</h2>
+<p>
+If we delete a file object, then the object looses it&#8217;s reference.
+This is especially problematic if we do not allow file objects to have
+non-existant paths.
+</p>
+<pre>
+  d2 = d1.dir('images')
+  d2.rm_r
+</pre>
+<p>
+Options for resolution:
+</p>
+<ul>
+<li>Do not support removal methods.
+
+</li>
+<li>Allow non-existant paths.
+
+</li>
+<li>Use delegator.
+
+</li>
+</ul>
+<p>
+The first solution would mean using a parent directory object to delete
+anything.
+</p>
+<pre>
+  f1 = file('/home/trans/.bashrc')
+  f1.rm              # not allowed
+  f1.parent.rm(f1)   # instead
+</pre>
+<p>
+I do not like this option becuase it means a directory object would behave
+substantially differnt from other file objects. That might not be so bad is
+Shell and Directory could be one and the same, but methods like #ctime
+would still clash.
+</p>
+<p>
+The second option is the simplist. The file object simply takes on a
+&quot;virtual&quot; state. This could lead to errors being thrown, but it
+is not unacceptable.
+</p>
+<pre>
+  f1 = file('/home/trans/.bashrc')
+  f1.rm
+  f1.ctime           # error
+</pre>
+<p>
+The last solution creates an indirection for all file objects. Removing a
+file would redelegate to a virtual pathname object. This is a more
+complicated solution and is really no better than the previous solutution
+&#8212;MethodMissing would be the error. A delegtor solution is a bit more
+interesting when we consider virtual file objects that can mimic a file
+system. However that could be a rather misleading redelgation.
+</p>
+<h2>Looking at the Lager Picture</h2>
+<p>
+Do we really need these objects? Isn&#8217;t the core idea the Folio Shell?
+For the first issue, what is wrong with:
+</p>
+<pre>
+  s1 = shell('home/trans')
+  s2 = s1 / 'images'
+</pre>
+<p>
+Which would clearly raise an error if it were not existant.
+</p>
+<p>
+As for the second. While it might not be quite as concise, it fits the
+shell prompt pattern:
+</p>
+<pre>
+  s1 = shell('/home/trans')
+  s1.rm('.bashrc')
+</pre>
+<p>
+Yea, ok. However, while we could pass around shell objects as a form of
+directory object, this would leave us no way to pass file objects.
+</p>
+<h2>Conclusion</h2>
+<p>
+It is fairly clear that the second solution to the second issue is the
+clearest choice. And that Directory and Shell should in fact stay separate
+objects. The &quot;Larger Picture&quot; should be the general pattern for
+theses cases, however this ought not prevent the use of the file objects as
+well.
+</p>
+<p>
+As for the first issue, the first or second options the better choices. I
+will probably raise the error.
+</p>
+
+
+    </div>
+  </div>
+
+</body>
+
+</html>
+
+<script src="../assets/scripts/spec.js" type="text/javascript" language="javascript"></script>
+
+<script type="text/javascript" language="javascript">
+  /*****************************************************************
+   * $.toc()
+   * by rebecca murphey
+   * rmurphey gmail com
+   *
+   * This function is called on its own and takes as an argument
+   * a list of selectors with which it will build a table of
+   * contents. 
+   *
+   * The first selector will make up the top level of the TOC;
+   * the second selector will make up the second level of the TOC;
+   * etc.
+   *
+   * This function returns a div containing nested unordered lists;
+   * each list item is linked to an anchor tag added before the item
+   * on the page.
+   *
+   * usage: $.toc('h1,h2,h3').prependTo('body');
+   ************************************************************************/
+  (function($) { 
+    $.toc = function(tocList) {
+      $(tocList).addClass('jquery-toc');
+      var tocListArray = tocList.split(',');
+      $.each(tocListArray, function(i,v) { tocListArray[i] = $.trim(v); });
+      var $elements = $('.jquery-toc');
+      $('body').append('<div></div>');
+      var $toc = $('body div:last');
+      var lastLevel = 1;
+      $toc.append('<ul class="jquery-toc-1"></ul>');
+      $elements.each(function() {
+        var $e = $(this);
+        var text = $e.text();
+        var anchor = text.replace(/ /g,'-');
+        $e.before('<a name="' + anchor + '"></a>');
+        var level;
+        $.each(tocListArray, function(i,v) { 
+          if (v.match(' ')) {
+            var vArray = v.split(' '); 
+            var e = vArray[vArray.length - 1];
+          } else { e = v; }
+          if ($e.is(e)) { level = i+1; } 
+        });
+        var className = 'jquery-toc-' + level;
+        var li = '<li><a href="#' + anchor + '">' + text + '</a></li>';
+        if (level == lastLevel) {
+          $('ul.' + className + ':last',$toc).append(li);
+        } else if (level > lastLevel) {
+          var parentLevel = level - 1;
+          var parentClassName = 'jquery-toc-' + parentLevel;
+          $('ul.' + parentClassName + ':last',$toc).
+            append('<ul class="' + className + '"></ul>');
+          $('ul.' + className + ':last',$toc).append(li);
+        } else if (level < lastLevel) {
+          $('ul.' + className + ':last',$toc).append(li);
+        }
+        lastLevel = level;
+      });
+      var $toc_ul = $('ul.jquery-toc-1',$toc);
+      $toc.remove();
+      return($toc_ul);
+   }
+  })(jQuery);
+</script>
+
+<script>
+  function toc_toggle() {
+    $('#toc_side').toggle();
+  };
+
+  $.toc('#content h1,h2,h3,h4').appendTo('.toc');
+
+  toc_toggle();
+</script>
+