Subversion Info

Rev
437
Last Checked In
2008-03-28 00:49:20 (2 weeks ago)
Checked in by
deveiant

Parent

Object

Included Modules

Class Index

Quicksearch

Path

A class for representing directory search paths.

Constants

SVNRev
SVN Revision
SVNId
SVN Id
Separator
The character to split path Strings on, and join on when converting back to a String.
DefaultCacheLifespan
How many seconds to cache directory stat information, in seconds.

Attributes

cache_lifespan[RW]
How long (in seconds) to cache the list of good directories. Setting this to 0 turns off caching.
dirs[RW]
The raw list of directories contained in the path, including invalid (non-existent or unreadable) ones.

Public Class Methods

new( path=[], cache_lifespan=DefaultCacheLifespan ) click to toggle source

Create a new Arrow::Path object for the specified path, which can be either a String containing directory names separated by File::PATH_SEPARATOR, an Array of directory names, or an object which returns such an Array when #to_a is called on it. If cache_lifespan is non-zero, the Array of valid directories will be cached for cache_lifespan seconds to save calls to stat(). 

     # File /Users/ged/source/ruby/Arrow/lib/arrow/utils.rb, line 112
112:         def initialize( path=[], cache_lifespan=DefaultCacheLifespan )
113:             @dirs = case path
114:                     when Array
115:                         path.flatten
116:                     when String
117:                         path.split(Separator)
118:                     else
119:                         path.to_a.flatten
120:                     end
121: 
122:             @dirs.each {|dir| dir.untaint}
123: 
124:             @valid_dirs = []
125:             @cache_lifespan = cache_lifespan
126:             @last_stat = Time.at(0)
127:         end
to_yaml_type() click to toggle source

Return the YAML type for this class 

    # File /Users/ged/source/ruby/Arrow/lib/arrow/utils.rb, line 97
97:         def self::to_yaml_type
98:             "!%s/arrowPath" % Arrow::YAML_DOMAIN
99:         end

Public Instance Methods

each( &block ) click to toggle source

Enumerable interface method. Iterate over the list of valid dirs in this path, calling the specified block for each. 

     # File /Users/ged/source/ruby/Arrow/lib/arrow/utils.rb, line 191
191:         def each( &block )
192:             self.valid_dirs.each( &block )
193:         end
to_s() click to toggle source

Return the path as a PathSeparator-separated String. 

     # File /Users/ged/source/ruby/Arrow/lib/arrow/utils.rb, line 197
197:         def to_s
198:             return self.valid_dirs.join( Separator )
199:         end
to_yaml( opts={} ) click to toggle source

Return the path as YAML text 

     # File /Users/ged/source/ruby/Arrow/lib/arrow/utils.rb, line 203
203:         def to_yaml( opts={} )
204:             require 'yaml'
205:             YAML.quick_emit( self.object_id, opts ) {|out|
206:                 out.seq( self.class.to_yaml_type ){|seq|
207:                     seq.add( self.dirs )
208:                 }
209:             }
210:         end
valid_dirs() click to toggle source

Fetch the list of directories in the search path, vetted to only contain existent and readable ones. All the enumeration methods use this list. 

     # File /Users/ged/source/ruby/Arrow/lib/arrow/utils.rb, line 146
146:         def valid_dirs
147:             if ( @cache_lifespan.nonzero? &&
148:                  ((Time.now - @last_stat) < @cache_lifespan) )
149:                 self.log.debug "Returning cached dirs."
150:                 return @valid_dirs
151:             end
152: 
153:             @valid_dirs = @dirs.find_all do |dir|
154:                 if dir.tainted?
155:                     self.log.info "Discarding tainted directory entry %p" % [ dir ]
156:                     next
157:                 end
158: 
159:                 begin
160:                     stat = File.stat(dir)
161:                     if stat.directory? && stat.readable?
162:                         true
163:                     else
164:                         self.log.debug "Discarded unreadable or non-directory %s" %
165:                             dir
166:                         false
167:                     end
168:                 rescue Errno::ENOENT => err
169:                     self.log.notice "Discarded invalid directory %p: %s" %
170:                         [ dir, err.message ]
171:                     false
172:                 rescue ::SecurityError => err
173:                     self.log.error "Discarded unsafe directory %p: %s" %
174:                         [ dir, err.message ]
175:                 end
176:             end
177:             @last_stat = Time.now
178: 
179:             return @valid_dirs
180:         end

secsequence

--- SEC00186

seccomment

--- ""

attributes

--- 
- name: cache_lifespan
  rw: RW
  a_desc: |+
    
    How long (in seconds) to cache the list of good directories. Setting this
    to 0 turns off caching.
    
- name: dirs
  rw: RW
  a_desc: |+
    
    The raw list of directories contained in the path, including invalid
    (non-existent or unreadable) ones.

method_list

--- 
- methods: 
  - visibility: public
    aref: M000008
    name: new
    sourcecode: "     <span class=\"ruby-comment cmt\"># File /Users/ged/source/ruby/Arrow/lib/arrow/utils.rb, line 112</span>\n\
      112:         <span class=\"ruby-keyword kw\">def</span> <span class=\"ruby-identifier\">initialize</span>( <span class=\"ruby-identifier\">path</span>=[], <span class=\"ruby-identifier\">cache_lifespan</span>=<span class=\"ruby-constant\">DefaultCacheLifespan</span> )\n\
      113:             <span class=\"ruby-ivar\">@dirs</span> = <span class=\"ruby-keyword kw\">case</span> <span class=\"ruby-identifier\">path</span>\n\
      114:                     <span class=\"ruby-keyword kw\">when</span> <span class=\"ruby-constant\">Array</span>\n\
      115:                         <span class=\"ruby-identifier\">path</span>.<span class=\"ruby-identifier\">flatten</span>\n\
      116:                     <span class=\"ruby-keyword kw\">when</span> <span class=\"ruby-constant\">String</span>\n\
      117:                         <span class=\"ruby-identifier\">path</span>.<span class=\"ruby-identifier\">split</span>(<span class=\"ruby-constant\">Separator</span>)\n\
      118:                     <span class=\"ruby-keyword kw\">else</span>\n\
      119:                         <span class=\"ruby-identifier\">path</span>.<span class=\"ruby-identifier\">to_a</span>.<span class=\"ruby-identifier\">flatten</span>\n\
      120:                     <span class=\"ruby-keyword kw\">end</span>\n\
      121: \n\
      122:             <span class=\"ruby-ivar\">@dirs</span>.<span class=\"ruby-identifier\">each</span> {<span class=\"ruby-operator\">|</span><span class=\"ruby-identifier\">dir</span><span class=\"ruby-operator\">|</span> <span class=\"ruby-identifier\">dir</span>.<span class=\"ruby-identifier\">untaint</span>}\n\
      123: \n\
      124:             <span class=\"ruby-ivar\">@valid_dirs</span> = []\n\
      125:             <span class=\"ruby-ivar\">@cache_lifespan</span> = <span class=\"ruby-identifier\">cache_lifespan</span>\n\
      126:             <span class=\"ruby-ivar\">@last_stat</span> = <span class=\"ruby-constant\">Time</span>.<span class=\"ruby-identifier\">at</span>(<span class=\"ruby-value\">0</span>)\n\
      127:         <span class=\"ruby-keyword kw\">end</span>"
    m_desc: |-
      <p>
      Create a <a href="Path.html#M000008">new</a> <a
      href="Path.html">Arrow::Path</a> object for the specified <tt>path</tt>,
      which can be either a String containing directory names separated by
      File::PATH_SEPARATOR, an Array of directory names, or an object which
      returns such an Array when #to_a is called on it. If
      <tt>cache_lifespan</tt> is non-zero, the Array of valid directories will be
      cached for <tt>cache_lifespan</tt> seconds to save calls to stat().
      </p>
    params: ( path=[], cache_lifespan=DefaultCacheLifespan )
  - visibility: public
    aref: M000007
    name: to_yaml_type
    sourcecode: "    <span class=\"ruby-comment cmt\"># File /Users/ged/source/ruby/Arrow/lib/arrow/utils.rb, line 97</span>\n\
      97:         <span class=\"ruby-keyword kw\">def</span> <span class=\"ruby-keyword kw\">self</span><span class=\"ruby-operator\">::</span><span class=\"ruby-identifier\">to_yaml_type</span>\n\
      98:             <span class=\"ruby-value str\">&quot;!%s/arrowPath&quot;</span> <span class=\"ruby-operator\">%</span> <span class=\"ruby-constant\">Arrow</span><span class=\"ruby-operator\">::</span><span class=\"ruby-constant\">YAML_DOMAIN</span>\n\
      99:         <span class=\"ruby-keyword kw\">end</span>"
    m_desc: |-
      <p>
      Return the YAML type for this class
      </p>
    params: ()
  category: Class
  type: Public
- methods: 
  - visibility: public
    aref: M000010
    name: each
    sourcecode: "     <span class=\"ruby-comment cmt\"># File /Users/ged/source/ruby/Arrow/lib/arrow/utils.rb, line 191</span>\n\
      191:         <span class=\"ruby-keyword kw\">def</span> <span class=\"ruby-identifier\">each</span>( <span class=\"ruby-operator\">&amp;</span><span class=\"ruby-identifier\">block</span> )\n\
      192:             <span class=\"ruby-keyword kw\">self</span>.<span class=\"ruby-identifier\">valid_dirs</span>.<span class=\"ruby-identifier\">each</span>( <span class=\"ruby-operator\">&amp;</span><span class=\"ruby-identifier\">block</span> )\n\
      193:         <span class=\"ruby-keyword kw\">end</span>"
    m_desc: |-
      <p>
      Enumerable interface method. Iterate over the list of valid dirs in this
      path, calling the specified block for <a href="Path.html#M000010">each</a>.
      </p>
    params: ( &amp;block )
  - visibility: public
    aref: M000011
    name: to_s
    sourcecode: "     <span class=\"ruby-comment cmt\"># File /Users/ged/source/ruby/Arrow/lib/arrow/utils.rb, line 197</span>\n\
      197:         <span class=\"ruby-keyword kw\">def</span> <span class=\"ruby-identifier\">to_s</span>\n\
      198:             <span class=\"ruby-keyword kw\">return</span> <span class=\"ruby-keyword kw\">self</span>.<span class=\"ruby-identifier\">valid_dirs</span>.<span class=\"ruby-identifier\">join</span>( <span class=\"ruby-constant\">Separator</span> )\n\
      199:         <span class=\"ruby-keyword kw\">end</span>"
    m_desc: |-
      <p>
      Return the path as a <tt>PathSeparator</tt>-separated String.
      </p>
    params: ()
  - visibility: public
    aref: M000012
    name: to_yaml
    sourcecode: "     <span class=\"ruby-comment cmt\"># File /Users/ged/source/ruby/Arrow/lib/arrow/utils.rb, line 203</span>\n\
      203:         <span class=\"ruby-keyword kw\">def</span> <span class=\"ruby-identifier\">to_yaml</span>( <span class=\"ruby-identifier\">opts</span>={} )\n\
      204:             <span class=\"ruby-identifier\">require</span> <span class=\"ruby-value str\">'yaml'</span>\n\
      205:             <span class=\"ruby-constant\">YAML</span>.<span class=\"ruby-identifier\">quick_emit</span>( <span class=\"ruby-keyword kw\">self</span>.<span class=\"ruby-identifier\">object_id</span>, <span class=\"ruby-identifier\">opts</span> ) {<span class=\"ruby-operator\">|</span><span class=\"ruby-identifier\">out</span><span class=\"ruby-operator\">|</span>\n\
      206:                 <span class=\"ruby-identifier\">out</span>.<span class=\"ruby-identifier\">seq</span>( <span class=\"ruby-keyword kw\">self</span>.<span class=\"ruby-identifier\">class</span>.<span class=\"ruby-identifier\">to_yaml_type</span> ){<span class=\"ruby-operator\">|</span><span class=\"ruby-identifier\">seq</span><span class=\"ruby-operator\">|</span>\n\
      207:                     <span class=\"ruby-identifier\">seq</span>.<span class=\"ruby-identifier\">add</span>( <span class=\"ruby-keyword kw\">self</span>.<span class=\"ruby-identifier\">dirs</span> )\n\
      208:                 }\n\
      209:             }\n\
      210:         <span class=\"ruby-keyword kw\">end</span>"
    m_desc: |-
      <p>
      Return the path as YAML text
      </p>
    params: ( opts={} )
  - visibility: public
    aref: M000009
    name: valid_dirs
    sourcecode: "     <span class=\"ruby-comment cmt\"># File /Users/ged/source/ruby/Arrow/lib/arrow/utils.rb, line 146</span>\n\
      146:         <span class=\"ruby-keyword kw\">def</span> <span class=\"ruby-identifier\">valid_dirs</span>\n\
      147:             <span class=\"ruby-keyword kw\">if</span> ( <span class=\"ruby-ivar\">@cache_lifespan</span>.<span class=\"ruby-identifier\">nonzero?</span> <span class=\"ruby-operator\">&amp;&amp;</span>\n\
      148:                  ((<span class=\"ruby-constant\">Time</span>.<span class=\"ruby-identifier\">now</span> <span class=\"ruby-operator\">-</span> <span class=\"ruby-ivar\">@last_stat</span>) <span class=\"ruby-operator\">&lt;</span> <span class=\"ruby-ivar\">@cache_lifespan</span>) )\n\
      149:                 <span class=\"ruby-keyword kw\">self</span>.<span class=\"ruby-identifier\">log</span>.<span class=\"ruby-identifier\">debug</span> <span class=\"ruby-value str\">&quot;Returning cached dirs.&quot;</span>\n\
      150:                 <span class=\"ruby-keyword kw\">return</span> <span class=\"ruby-ivar\">@valid_dirs</span>\n\
      151:             <span class=\"ruby-keyword kw\">end</span>\n\
      152: \n\
      153:             <span class=\"ruby-ivar\">@valid_dirs</span> = <span class=\"ruby-ivar\">@dirs</span>.<span class=\"ruby-identifier\">find_all</span> <span class=\"ruby-keyword kw\">do</span> <span class=\"ruby-operator\">|</span><span class=\"ruby-identifier\">dir</span><span class=\"ruby-operator\">|</span>\n\
      154:                 <span class=\"ruby-keyword kw\">if</span> <span class=\"ruby-identifier\">dir</span>.<span class=\"ruby-identifier\">tainted?</span>\n\
      155:                     <span class=\"ruby-keyword kw\">self</span>.<span class=\"ruby-identifier\">log</span>.<span class=\"ruby-identifier\">info</span> <span class=\"ruby-value str\">&quot;Discarding tainted directory entry %p&quot;</span> <span class=\"ruby-operator\">%</span> [ <span class=\"ruby-identifier\">dir</span> ]\n\
      156:                     <span class=\"ruby-keyword kw\">next</span>\n\
      157:                 <span class=\"ruby-keyword kw\">end</span>\n\
      158: \n\
      159:                 <span class=\"ruby-keyword kw\">begin</span>\n\
      160:                     <span class=\"ruby-identifier\">stat</span> = <span class=\"ruby-constant\">File</span>.<span class=\"ruby-identifier\">stat</span>(<span class=\"ruby-identifier\">dir</span>)\n\
      161:                     <span class=\"ruby-keyword kw\">if</span> <span class=\"ruby-identifier\">stat</span>.<span class=\"ruby-identifier\">directory?</span> <span class=\"ruby-operator\">&amp;&amp;</span> <span class=\"ruby-identifier\">stat</span>.<span class=\"ruby-identifier\">readable?</span>\n\
      162:                         <span class=\"ruby-keyword kw\">true</span>\n\
      163:                     <span class=\"ruby-keyword kw\">else</span>\n\
      164:                         <span class=\"ruby-keyword kw\">self</span>.<span class=\"ruby-identifier\">log</span>.<span class=\"ruby-identifier\">debug</span> <span class=\"ruby-value str\">&quot;Discarded unreadable or non-directory %s&quot;</span> <span class=\"ruby-operator\">%</span>\n\
      165:                             <span class=\"ruby-identifier\">dir</span>\n\
      166:                         <span class=\"ruby-keyword kw\">false</span>\n\
      167:                     <span class=\"ruby-keyword kw\">end</span>\n\
      168:                 <span class=\"ruby-keyword kw\">rescue</span> <span class=\"ruby-constant\">Errno</span><span class=\"ruby-operator\">::</span><span class=\"ruby-constant\">ENOENT</span> =<span class=\"ruby-operator\">&gt;</span> <span class=\"ruby-identifier\">err</span>\n\
      169:                     <span class=\"ruby-keyword kw\">self</span>.<span class=\"ruby-identifier\">log</span>.<span class=\"ruby-identifier\">notice</span> <span class=\"ruby-value str\">&quot;Discarded invalid directory %p: %s&quot;</span> <span class=\"ruby-operator\">%</span>\n\
      170:                         [ <span class=\"ruby-identifier\">dir</span>, <span class=\"ruby-identifier\">err</span>.<span class=\"ruby-identifier\">message</span> ]\n\
      171:                     <span class=\"ruby-keyword kw\">false</span>\n\
      172:                 <span class=\"ruby-keyword kw\">rescue</span> <span class=\"ruby-operator\">::</span><span class=\"ruby-constant\">SecurityError</span> =<span class=\"ruby-operator\">&gt;</span> <span class=\"ruby-identifier\">err</span>\n\
      173:                     <span class=\"ruby-keyword kw\">self</span>.<span class=\"ruby-identifier\">log</span>.<span class=\"ruby-identifier\">error</span> <span class=\"ruby-value str\">&quot;Discarded unsafe directory %p: %s&quot;</span> <span class=\"ruby-operator\">%</span>\n\
      174:                         [ <span class=\"ruby-identifier\">dir</span>, <span class=\"ruby-identifier\">err</span>.<span class=\"ruby-identifier\">message</span> ]\n\
      175:                 <span class=\"ruby-keyword kw\">end</span>\n\
      176:             <span class=\"ruby-keyword kw\">end</span>\n\
      177:             <span class=\"ruby-ivar\">@last_stat</span> = <span class=\"ruby-constant\">Time</span>.<span class=\"ruby-identifier\">now</span>\n\
      178: \n\
      179:             <span class=\"ruby-keyword kw\">return</span> <span class=\"ruby-ivar\">@valid_dirs</span>\n\
      180:         <span class=\"ruby-keyword kw\">end</span>"
    m_desc: |-
      <p>
      Fetch the list of directories in the search path, vetted to only contain
      existent and readable ones. All the enumeration methods use this list.
      </p>
    params: ()
  category: Instance
  type: Public

sectitle

---

constants

--- 
- name: SVNRev
  desc: |+
    
    SVN Revision
    
  value: "%q$Rev: 437 $"
- name: SVNId
  desc: |+
    
    SVN Id
    
  value: "%q$Id: utils.rb 437 2008-03-28 00:49:20Z deveiant $"
- name: Separator
  desc: |+
    
    The character to split path Strings on, and join on when converting back to
    a String.
    
  value: File::PATH_SEPARATOR
- name: DefaultCacheLifespan
  desc: |+
    
    How many seconds to cache directory stat information, in seconds.
    
  value: "1.5"

[Validate]

Generated with the Darkfish Rdoc Generator.