Class: Webgen::Path

Inherits:
Object
  • Object
show all
Includes:
Comparable
Defined in:
lib/webgen/path.rb,
lib/webgen/deprecated.rb

Overview

General Information

A Path object provides information about a path that is used to create a node as well as methods for accessing its content. In contrast, output paths are always strings and just specify the location where a specific node should be written to.

Note the path and source_path attributes of a Path object:

  • The source_path specifies a path string that was directly created by a Source object. Each Path object must have such a valid source path sothat webgen can infer the Path the lead to the creation of a Node object later.

  • In contrast, the path attribute specifies the path that is used to create the canonical name (and by default the output path) of a Node object. Normally it is the same as the source_path but can differ (e.g. when fragment nodes are created for page file nodes).

A Path object can represent one of three different things: a directory, a file or a fragment. If the path ends with a slash character, then the path object represents a directory, if the path contains a hash character anywhere, then the path object represents a fragment and else it represents a file. Have a look at the webgen manual to see the exact format of a path!

Relation to Source classes

A webgen source class needs to derive a specialized path class from this class and implement an approriate #changed? method that returns true if the path’s content has changed since the last webgen run.

Defined Under Namespace

Classes: SourceIO

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(path, source_path = path, &ioblock) ⇒ Path

Create a new Path object for path. The optional source_path parameter specifies the path string that lead to the creation of this path. The optional block needs to return an IO object for getting the content of the path.

The path needs to be in a well defined format which can be looked up in the webgen manual.



123
124
125
126
127
128
129
 
# File 'lib/webgen/path.rb', line 123

def initialize(path, source_path = path, &ioblock)
  @meta_info = {}
  @io = block_given? ? SourceIO.new(&ioblock) : nil
  @source_path = source_path
  @passive = false
  analyse(path)
end

Instance Attribute Details

#basename ⇒ Object

The canonical name of the path without the extension.



101
102
103
 
# File 'lib/webgen/path.rb', line 101

def basename
  @basename
end

#ext ⇒ Object

The extension of the path.



104
105
106
 
# File 'lib/webgen/path.rb', line 104

def ext
  @ext
end

#meta_info ⇒ Object

Extracted meta information for the path.



107
108
109
 
# File 'lib/webgen/path.rb', line 107

def meta_info
  @meta_info
end

#parent_path ⇒ Object (readonly)

The string specifying the parent path



98
99
100
 
# File 'lib/webgen/path.rb', line 98

def parent_path
  @parent_path
end

#passive=(value) ⇒ Object (writeonly)

Specifies whether this path should be used during the “tree update” phase of a webgen run or only later during node resolution.



111
112
113
 
# File 'lib/webgen/path.rb', line 111

def passive=(value)
  @passive = value
end

#path ⇒ Object (readonly)

The full path for which this Path object was created.



92
93
94
 
# File 'lib/webgen/path.rb', line 92

def path
  @path
end

#source_path ⇒ Object (readonly)

A string specifying the path that lead to the creation of this path.



95
96
97
 
# File 'lib/webgen/path.rb', line 95

def source_path
  @source_path
end

Class Method Details

.lcn(cn, lang) ⇒ Object

Utility method for creating the lcn from the cn and the language lang.



186
187
188
189
190
191
192
 
# File 'lib/webgen/path.rb', line 186

def self.lcn(cn, lang)
  if lang.nil?
    cn
  else
    cn.split('.').insert((cn =~ /^\./ ? 2 : 1), lang.to_s).join('.')
  end
end

.make_absolute(base, path) ⇒ Object

Make the given path absolute by prepending the absolute directory path base if necessary. Also resolves all ‘..’ and ‘.’ references in path.

Raises:

  • (ArgumentError) 


74
75
76
77
 
# File 'lib/webgen/path.rb', line 74

def self.make_absolute(base, path)
  raise(ArgumentError, 'base has to be an absolute path, ie. needs to start with a slash') unless base =~ /\//
  Pathname.new(path =~ /^\// ? path : File.join(base, path)).cleanpath.to_s
end

.match(path, pattern) ⇒ Object

Return true if the given path matches the given pattern (trailing slashes of directories are not respected). For information on which patterns are supported, have a look at the documentation of File.fnmatch.



82
83
84
85
86
 
# File 'lib/webgen/path.rb', line 82

def self.match(path, pattern)
  path = path.to_s.chomp('/') unless path == '/'
  pattern = pattern.to_s.chomp('/') unless pattern == '/'
  File.fnmatch(pattern, path, File::FNM_DOTMATCH|File::FNM_CASEFOLD|File::FNM_PATHNAME)
end

Instance Method Details

#<=>(other) ⇒ Object

Compare the #path of this object to other.path



231
232
233
 
# File 'lib/webgen/path.rb', line 231

def <=>(other)
  @path <=> other.path
end

#==(other) ⇒ Object Also known as: eql?

Equality – Return true if other is a Path object with the same #path or if other is a String equal to the #path. Else return false.



219
220
221
222
223
224
225
226
227
 
# File 'lib/webgen/path.rb', line 219

def ==(other)
  if other.kind_of?(Path)
    other.path == @path
  elsif other.kind_of?(String)
    other == @path
  else
    false
  end
end

#acn ⇒ Object

The absolute canonical name of this path.



200
201
202
203
204
205
206
 
# File 'lib/webgen/path.rb', line 200

def acn
  if @path =~ /#/
    self.class.new(@parent_path).acn + cn
  else
    @parent_path + cn
  end
end

#alcn ⇒ Object

The absolute localized canonical name of this path.



209
210
211
212
213
214
215
 
# File 'lib/webgen/path.rb', line 209

def alcn
  if @path =~ /#/
    self.class.new(@parent_path).alcn + lcn
  else
    @parent_path + lcn
  end
end

#changed? ⇒ Boolean

Has the content of this path changed since the last webgen run? This default implementation always returns true, a specialized sub class needs to override this behaviour!

Returns:

  • (Boolean) 


167
168
169
 
# File 'lib/webgen/path.rb', line 167

def changed?
  true
end

#cn ⇒ Object

The canonical name created from the path (namely from the parts basename and extension).



181
182
183
 
# File 'lib/webgen/path.rb', line 181

def cn
  @basename + (@ext.length > 0 ? '.' + @ext : '') + (@basename != '/' && @path =~ /.\/$/ ? '/' : '')
end

#cnbase ⇒ Object 



24
25
26
27
 
# File 'lib/webgen/deprecated.rb', line 24

def cnbase
  warn("Deprecation warning (~ #{caller.first}): this method will be removed in one of the next releases - use Path#basename instead!")
  @basename
end

#cnbase=(value) ⇒ Object 



29
30
31
32
 
# File 'lib/webgen/deprecated.rb', line 29

def cnbase=(value)
  warn("Deprecation warning (~ #{caller.first}): this method will be removed in one of the next releases - use Path#basename= instead!")
  basename = value
end

#dup ⇒ Object

Duplicate the path object.



159
160
161
162
163
 
# File 'lib/webgen/path.rb', line 159

def dup
  temp = super
  temp.instance_variable_set(:@meta_info, @meta_info.dup)
  temp
end

#hash ⇒ Object

:nodoc:



235
236
237
 
# File 'lib/webgen/path.rb', line 235

def hash #:nodoc:
  @path.hash
end

#inspect ⇒ Object

:nodoc:



244
245
246
 
# File 'lib/webgen/path.rb', line 244

def inspect #:nodoc:
  "#<Path: #{@path}>"
end

#io ⇒ Object

The SourceIO object associated with the path.



172
173
174
175
176
177
178
 
# File 'lib/webgen/path.rb', line 172

def io
  if @io
    @io
  else
    raise "No IO object defined for the path #{self}"
  end
end

#lcn ⇒ Object

The localized canonical name created from the path.



195
196
197
 
# File 'lib/webgen/path.rb', line 195

def lcn
  self.class.lcn(cn, @meta_info['lang'])
end

#mount_at(mp, prefix = nil) ⇒ Object

Mount this path at the mount point mp, optionally stripping prefix from the parent path, and return the new path object.

The parameters mp and prefix have to be absolute directory paths, ie. they have to start and end with a slash and must not contain any hash characters!

– Can’t use self.class.new(…) here because the semantics of the sub constructors is not know ++

Raises:

  • (ArgumentError) 


140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
 
# File 'lib/webgen/path.rb', line 140

def mount_at(mp, prefix = nil)
  raise(ArgumentError, "The mount point (#{mp}) must be a valid directory path") if mp =~ /^[^\/]|#|[^\/]$/
  raise(ArgumentError, "The strip prefix (#{prefix}) must be a valid directory path") if !prefix.nil? && prefix =~ /^[^\/]|#|[^\/]$/

  temp = dup
  strip_re = /^#{Regexp.escape(prefix.to_s)}/
  temp.instance_variable_set(:@path, temp.path.sub(strip_re, ''))
  reanalyse = (@path == '/' || temp.path == '')
  temp.instance_variable_set(:@path, File.join(mp, temp.path))
  temp.instance_variable_set(:@source_path, temp.path) if @path == @source_path
  if reanalyse
    temp.send(:analyse, temp.path)
  else
    temp.instance_variable_set(:@parent_path, File.join(mp, temp.parent_path.sub(strip_re, '')))
  end
  temp
end

#passive? ⇒ Boolean

Is this path only used later during node resolution? Defaults to false, i.e. used during the “tree update” phase.

Returns:

  • (Boolean) 


115
 
# File 'lib/webgen/path.rb', line 115

def passive?; @passive; end

#to_s ⇒ Object Also known as: to_str

:nodoc:



239
240
241
 
# File 'lib/webgen/path.rb', line 239

def to_s #:nodoc:
  @path.dup
end