Subversion Info

Rev
406
Last Checked In
2007-07-18 17:01:59 (7 months ago)
Checked in by
bbleything

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 lib/arrow/utils.rb, line 162
162:         def initialize( path=[], cache_lifespan=DefaultCacheLifespan )
163:             @dirs = case path
164:                     when Array
165:                         path.flatten
166:                     when String
167:                         path.split(Separator)
168:                     else
169:                         path.to_a.flatten
170:                     end
171: 
172:             @dirs.each {|dir| dir.untaint}
173: 
174:             @valid_dirs = []
175:             @cache_lifespan = cache_lifespan
176:             @last_stat = Time.at(0)
177:         end
to_yaml_type() click to toggle source

Return the YAML type for this class 

     # File lib/arrow/utils.rb, line 147
147:         def self::to_yaml_type
148:             "!%s/arrowPath" % Arrow::YamlDomain
149:         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 lib/arrow/utils.rb, line 241
241:         def each( &block )
242:             self.valid_dirs.each( &block )
243:         end
to_s() click to toggle source

Return the path as a PathSeparator-separated String. 

     # File lib/arrow/utils.rb, line 247
247:         def to_s
248:             return self.valid_dirs.join( Separator )
249:         end
to_yaml( opts={} ) click to toggle source

Return the path as YAML text 

     # File lib/arrow/utils.rb, line 253
253:         def to_yaml( opts={} )
254:             require 'yaml'
255:             YAML.quick_emit( self.object_id, opts ) {|out|
256:                 out.seq( self.class.to_yaml_type ){|seq|
257:                     seq.add( self.dirs )
258:                 }
259:             }
260:         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 lib/arrow/utils.rb, line 196
196:         def valid_dirs
197:             if ( @cache_lifespan.nonzero? &&
198:                  ((Time.now - @last_stat) < @cache_lifespan) )
199:                 self.log.debug "Returning cached dirs."
200:                 return @valid_dirs
201:             end
202: 
203:             @valid_dirs = @dirs.find_all do |dir|
204:                 if dir.tainted?
205:                     self.log.info "Discarding tainted directory entry %p" % [ dir ]
206:                     next
207:                 end
208: 
209:                 begin
210:                     stat = File.stat(dir)
211:                     if stat.directory? && stat.readable?
212:                         true
213:                     else
214:                         self.log.debug "Discarded unreadable or non-directory %s" %
215:                             dir
216:                         false
217:                     end
218:                 rescue Errno::ENOENT => err
219:                     self.log.notice "Discarded invalid directory %p: %s" %
220:                         [ dir, err.message ]
221:                     false
222:                 rescue ::SecurityError => err
223:                     self.log.error "Discarded unsafe directory %p: %s" %
224:                         [ dir, err.message ]
225:                 end
226:             end
227:             @last_stat = Time.now
228: 
229:             return @valid_dirs
230:         end

secsequence

--- SEC00182

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 lib/arrow/utils.rb, line 162</span>\n\
      162:         <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\
      163:             <span class=\"ruby-ivar\">@dirs</span> = <span class=\"ruby-keyword kw\">case</span> <span class=\"ruby-identifier\">path</span>\n\
      164:                     <span class=\"ruby-keyword kw\">when</span> <span class=\"ruby-constant\">Array</span>\n\
      165:                         <span class=\"ruby-identifier\">path</span>.<span class=\"ruby-identifier\">flatten</span>\n\
      166:                     <span class=\"ruby-keyword kw\">when</span> <span class=\"ruby-constant\">String</span>\n\
      167:                         <span class=\"ruby-identifier\">path</span>.<span class=\"ruby-identifier\">split</span>(<span class=\"ruby-constant\">Separator</span>)\n\
      168:                     <span class=\"ruby-keyword kw\">else</span>\n\
      169:                         <span class=\"ruby-identifier\">path</span>.<span class=\"ruby-identifier\">to_a</span>.<span class=\"ruby-identifier\">flatten</span>\n\
      170:                     <span class=\"ruby-keyword kw\">end</span>\n\
      171: \n\
      172:             <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\
      173: \n\
      174:             <span class=\"ruby-ivar\">@valid_dirs</span> = []\n\
      175:             <span class=\"ruby-ivar\">@cache_lifespan</span> = <span class=\"ruby-identifier\">cache_lifespan</span>\n\
      176:             <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\
      177:         <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 <a href="String.html">String</a> 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 lib/arrow/utils.rb, line 147</span>\n\
      147:         <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\
      148:             <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\">YamlDomain</span>\n\
      149:         <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 lib/arrow/utils.rb, line 241</span>\n\
      241:         <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\
      242:             <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\
      243:         <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 lib/arrow/utils.rb, line 247</span>\n\
      247:         <span class=\"ruby-keyword kw\">def</span> <span class=\"ruby-identifier\">to_s</span>\n\
      248:             <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\
      249:         <span class=\"ruby-keyword kw\">end</span>"
    m_desc: |-
      <p>
      Return the path as a <tt>PathSeparator</tt>-separated <a
      href="String.html">String</a>.
      </p>
    params: ()
  - visibility: public
    aref: M000012
    name: to_yaml
    sourcecode: "     <span class=\"ruby-comment cmt\"># File lib/arrow/utils.rb, line 253</span>\n\
      253:         <span class=\"ruby-keyword kw\">def</span> <span class=\"ruby-identifier\">to_yaml</span>( <span class=\"ruby-identifier\">opts</span>={} )\n\
      254:             <span class=\"ruby-identifier\">require</span> <span class=\"ruby-value str\">'yaml'</span>\n\
      255:             <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\
      256:                 <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\
      257:                     <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\
      258:                 }\n\
      259:             }\n\
      260:         <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 lib/arrow/utils.rb, line 196</span>\n\
      196:         <span class=\"ruby-keyword kw\">def</span> <span class=\"ruby-identifier\">valid_dirs</span>\n\
      197:             <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\
      198:                  ((<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\
      199:                 <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\
      200:                 <span class=\"ruby-keyword kw\">return</span> <span class=\"ruby-ivar\">@valid_dirs</span>\n\
      201:             <span class=\"ruby-keyword kw\">end</span>\n\
      202: \n\
      203:             <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\
      204:                 <span class=\"ruby-keyword kw\">if</span> <span class=\"ruby-identifier\">dir</span>.<span class=\"ruby-identifier\">tainted?</span>\n\
      205:                     <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\
      206:                     <span class=\"ruby-keyword kw\">next</span>\n\
      207:                 <span class=\"ruby-keyword kw\">end</span>\n\
      208: \n\
      209:                 <span class=\"ruby-keyword kw\">begin</span>\n\
      210:                     <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\
      211:                     <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\
      212:                         <span class=\"ruby-keyword kw\">true</span>\n\
      213:                     <span class=\"ruby-keyword kw\">else</span>\n\
      214:                         <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\
      215:                             <span class=\"ruby-identifier\">dir</span>\n\
      216:                         <span class=\"ruby-keyword kw\">false</span>\n\
      217:                     <span class=\"ruby-keyword kw\">end</span>\n\
      218:                 <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\
      219:                     <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\
      220:                         [ <span class=\"ruby-identifier\">dir</span>, <span class=\"ruby-identifier\">err</span>.<span class=\"ruby-identifier\">message</span> ]\n\
      221:                     <span class=\"ruby-keyword kw\">false</span>\n\
      222:                 <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\
      223:                     <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\
      224:                         [ <span class=\"ruby-identifier\">dir</span>, <span class=\"ruby-identifier\">err</span>.<span class=\"ruby-identifier\">message</span> ]\n\
      225:                 <span class=\"ruby-keyword kw\">end</span>\n\
      226:             <span class=\"ruby-keyword kw\">end</span>\n\
      227:             <span class=\"ruby-ivar\">@last_stat</span> = <span class=\"ruby-constant\">Time</span>.<span class=\"ruby-identifier\">now</span>\n\
      228: \n\
      229:             <span class=\"ruby-keyword kw\">return</span> <span class=\"ruby-ivar\">@valid_dirs</span>\n\
      230:         <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: 406 $"
- name: SVNId
  desc: |+
    
    SVN Id
    
  value: "%q$Id: utils.rb 406 2007-07-18 17:01:59Z bbleything $"
- name: Separator
  desc: |+
    
    The character to split path Strings on, and join on when converting back to
    a <a href="String.html">String</a>.
    
  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.