Class: Webgen::Path

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

Overview

General Information

A Path object provides information about a path that is used to create one or more nodes as well as methods for accessing the path's content. So a Path object always refers to a source path. 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.

Direct Known Subclasses

Source::FileSystem::Path, Source::TarArchive::Path

Defined Under Namespace

Classes: SourceIO

Constant Summary

FILENAME_RE =
/^(?:(\d+)\.)?(\.?[^.]*?)(?:\.(\w\w\w?)(?=\.))?(?:\.(.*))?$/

Instance Attribute Summary (collapse)

Class Method Summary (collapse)

Instance Method Summary (collapse)

Constructor Details

- (Path) initialize(path, source_path = path, &ioblock)

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.



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

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

- (Object) basename

The canonical name of the path without the extension.



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

def basename
  @basename
end

- (Object) ext

The extension of the path.



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

def ext
  @ext
end

- (Object) meta_info

Extracted meta information for the path.



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

def meta_info
  @meta_info
end

- (Object) parent_path (readonly)

The string specifying the parent path



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

def parent_path
  @parent_path
end

- (Object) passive=(value) (writeonly)

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



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

def passive=(value)
  @passive = value
end

- (Object) path (readonly)

The full path for which this Path object was created.



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

def path
  @path
end

- (Object) source_path (readonly)

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



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

def source_path
  @source_path
end

Class Method Details

+ (Object) lcn(cn, lang)

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



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

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

+ (Object) make_absolute(base, path)

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

Raises:

  • (ArgumentError)


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

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 + (path =~ /.\/$/ ? '/' : '')
end

+ (Object) match(path, pattern)

Return true if the given path matches the given pattern. For information on which patterns are supported, have a look at the documentation of File.fnmatch.



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

def self.match(path, pattern)
  pattern += '/' if path.to_s =~ /\/$/ && pattern !~ /\/$|^$/
  File.fnmatch(pattern, path.to_s, File::FNM_DOTMATCH|File::FNM_CASEFOLD|File::FNM_PATHNAME)
end

Instance Method Details

- (Object) <=>(other)

Compare the #path of this object to other.path



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

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

- (Object) ==(other) 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.



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

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

- (Object) acn

The absolute canonical name of this path.



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

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

- (Object) alcn

The absolute localized canonical name of this path.



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

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

- (Boolean) changed?

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)


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

def changed?
  true
end

- (Object) cn

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



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

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

- (Object) dup

Duplicate the path object.



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

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

- (Object) hash

:nodoc:



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

def hash #:nodoc:
  @path.hash
end

- (Object) inspect

:nodoc:



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

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

- (Object) io

The SourceIO object associated with the path.



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

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

- (Object) lcn

The localized canonical name created from the path.



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

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

- (Object) mount_at(mp, prefix = nil)

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)


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

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

- (Boolean) passive?

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

Returns:

  • (Boolean)


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

def passive?; @passive; end

- (Object) to_s Also known as: to_str

:nodoc:



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

def to_s #:nodoc:
  @path.dup
end