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.



118
119
120
121
122
123
124
 
# File 'lib/webgen/path.rb', line 118

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.



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

def basename
  @basename
end

#ext ⇒ Object

The extension of the path.



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

def ext
  @ext
end

#meta_info ⇒ Object

Extracted meta information for the path.



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

def meta_info
  @meta_info
end

#parent_path ⇒ Object (readonly)

The string specifying the parent path



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

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.



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

def passive=(value)
  @passive = value
end

#path ⇒ Object (readonly)

The full path for which this Path object was created.



87
88
89
 
# File 'lib/webgen/path.rb', line 87

def path
  @path
end

#source_path ⇒ Object (readonly)

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



90
91
92
 
# File 'lib/webgen/path.rb', line 90

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.



181
182
183
184
185
186
187
 
# File 'lib/webgen/path.rb', line 181

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) 


69
70
71
72
 
# File 'lib/webgen/path.rb', line 69

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.



77
78
79
80
81
 
# File 'lib/webgen/path.rb', line 77

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



226
227
228
 
# File 'lib/webgen/path.rb', line 226

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.



214
215
216
217
218
219
220
221
222
 
# File 'lib/webgen/path.rb', line 214

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.



195
196
197
198
199
200
201
 
# File 'lib/webgen/path.rb', line 195

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.



204
205
206
207
208
209
210
 
# File 'lib/webgen/path.rb', line 204

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!



162
163
164
 
# File 'lib/webgen/path.rb', line 162

def changed?
  true
end

#cn ⇒ Object

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



176
177
178
 
# File 'lib/webgen/path.rb', line 176

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.



154
155
156
157
158
 
# File 'lib/webgen/path.rb', line 154

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

#hash ⇒ Object

:nodoc:



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

def hash #:nodoc:
  @path.hash
end

#inspect ⇒ Object

:nodoc:



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

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

#io ⇒ Object

The SourceIO object associated with the path.



167
168
169
170
171
172
173
 
# File 'lib/webgen/path.rb', line 167

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.



190
191
192
 
# File 'lib/webgen/path.rb', line 190

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) 


135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
 
# File 'lib/webgen/path.rb', line 135

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.



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

def passive?; @passive; end

#to_s ⇒ Object Also known as: to_str

:nodoc:



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

def to_s #:nodoc:
  @path.dup
end