lib/SuikaWiki/Name.pm


=head1 NAME

SuikaWiki::Name - SuikaWiki WikiName Implementation

=head1 DESCRIPTION

C<SuikaWiki::Name> implements WikiName related functions used in SuikaWiki.
SuikaWiki cope with two styles of WikiName: internal (array reference) form
and external (string) form.  This module provides "serializer" and "parser"
converting to each form, as well as "resolver" getting absolute WikiName
from relative WikiName and base WikiName.

This module is part of SuikaWiki.

=cut

package SuikaWiki::Name;
use strict;
our $VERSION = do{my @r=(q$Revision: 1.2 $=~/\d+/g);sprintf "%d."."%02d" x $#r,@r};

=head1 METHODS

=over 4

=item $name = SuikaWiki::Name->new ($name, %option)

Constructs a new instance of WikiName.  C<$name> can be either in external
or internal form and either in relative or absolute form.
C<wiki> or C<delimiter> option required when C<$name> is in external form.

Ensure <$name> is interpretable as an array reference when it is a reference
to something.

=cut

sub new ($;%) {
  my $class = shift;
  my ($name, %opt) = @_;
  my $self;
  if (ref $name) {
    $self = bless [@$name], $class;
  } else {
    my $delim = $opt{delimiter_reg} || $opt{delimiter}
             || $opt{wiki}->{config}->{name}->{space}->{separator_reg};
    $self = bless [split $delim, $name], $class;
  }
  $self;
}

=item $string = $name->stringify (%option)

Returns WikiName in external (string) form.
C<delimiter> or C<wiki> option is required.

=cut

sub stringify ($%) {
  my ($self, %opt) = @_;
  my $delim = $opt{delimiter}
           || $opt{wiki}->{config}->{name}->{space}->{separator};
  join $delim, @$self;
}

=item $name->append_component ($component)

Appends WikiName component.  C<$component> is either a reference
interpretable as an array reference or a string.

=cut

sub append_component ($$%) {
  my ($self, $component) = @_;
  push @$self, ref $component ? @$component : $component;
}

=item $name->prepend_component ($component)

Prepends WikiName component.  C<$component> is either a reference
interpretable as an array reference or a string.

=cut

sub prepend_component ($$%) {
  my ($self, $component) = @_;
  unshift @$self, ref $component ? @$component : $component;
}

=item $abs = $name->absolute (base => $base, %option)

Resolves WikiName to absolute form.  New instance is constructed.
Either C<self> and C<parent> options or C<wiki> option required
to specify "self" and "parent" indicator.

=cut

sub absolute ($%) {
  my ($self, %opt) = @_;
  my @abs = @{$opt{base} || []};
  my @rel = @$self;
  my $Self = $opt{self} || $opt{wiki}->{config}->{name}->{space}->{self};
  my $Parent = $opt{parent} || $opt{wiki}->{config}->{name}->{space}->{parent};
  while ($rel[0] eq $Self or $rel[0] eq $Parent) {
    if ($rel[0] eq $Parent) {
      $#abs-- if @abs;
    }
    shift @rel;
  }
  if (@rel == @$self) {
    @abs = @rel;
  } else {
    push @abs, @rel;
  }
  ref ($self)->new (\@abs);
}

=head1 TO DO

More study needed to enable to include delimiter string in WikiName 
(string form) as part of data.

=head1 LICENCE

Copyright 2004 Wakaba <w@suika.fam.cx>.  All rights reserved.

This program is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.

=cut

1; # $Date: 2003/04/29 10:36:17 $
1	wakaba	1.1
2			=head1 NAME
3
4			SuikaWiki::Name - SuikaWiki WikiName Implementation
5
6			=head1 DESCRIPTION
7
8			C<SuikaWiki::Name> implements WikiName related functions used in SuikaWiki.
9			SuikaWiki cope with two styles of WikiName: internal (array reference) form
10			and external (string) form. This module provides "serializer" and "parser"
11			converting to each form, as well as "resolver" getting absolute WikiName
12			from relative WikiName and base WikiName.
13
14			This module is part of SuikaWiki.
15
16			=cut
17
18			package SuikaWiki::Name;
19			use strict;
20			our $VERSION = do{my @r=(q$Revision: 1.2 $=~/\d+/g);sprintf "%d."."%02d" x $#r,@r};
21
22			=head1 METHODS
23
24			=over 4
25
26			=item $name = SuikaWiki::Name->new ($name, %option)
27
28			Constructs a new instance of WikiName. C<$name> can be either in external
29			or internal form and either in relative or absolute form.
30			C<wiki> or C<delimiter> option required when C<$name> is in external form.
31
32			Ensure <$name> is interpretable as an array reference when it is a reference
33			to something.
34
35			=cut
36
37			sub new ($;%) {
38			my $class = shift;
39			my ($name, %opt) = @_;
40			my $self;
41			if (ref $name) {
42			$self = bless [@$name], $class;
43			} else {
44			my $delim = $opt{delimiter_reg} \|\| $opt{delimiter}
45			\|\| $opt{wiki}->{config}->{name}->{space}->{separator_reg};
46			$self = bless [split $delim, $name], $class;
47			}
48			$self;
49			}
50
51			=item $string = $name->stringify (%option)
52
53			Returns WikiName in external (string) form.
54			C<delimiter> or C<wiki> option is required.
55
56			=cut
57
58			sub stringify ($%) {
59			my ($self, %opt) = @_;
60			my $delim = $opt{delimiter}
61			\|\| $opt{wiki}->{config}->{name}->{space}->{separator};
62			join $delim, @$self;
63			}
64
65			=item $name->append_component ($component)
66
67			Appends WikiName component. C<$component> is either a reference
68			interpretable as an array reference or a string.
69
70			=cut
71
72			sub append_component ($$%) {
73			my ($self, $component) = @_;
74			push @$self, ref $component ? @$component : $component;
75			}
76
77			=item $name->prepend_component ($component)
78
79			Prepends WikiName component. C<$component> is either a reference
80			interpretable as an array reference or a string.
81
82			=cut
83
84			sub prepend_component ($$%) {
85			my ($self, $component) = @_;
86			unshift @$self, ref $component ? @$component : $component;
87			}
88
89			=item $abs = $name->absolute (base => $base, %option)
90
91			Resolves WikiName to absolute form. New instance is constructed.
92			Either C<self> and C<parent> options or C<wiki> option required
93			to specify "self" and "parent" indicator.
94
95			=cut
96
97			sub absolute ($%) {
98			my ($self, %opt) = @_;
99			my @abs = @{$opt{base} \|\| []};
100			my @rel = @$self;
101			my $Self = $opt{self} \|\| $opt{wiki}->{config}->{name}->{space}->{self};
102			my $Parent = $opt{parent} \|\| $opt{wiki}->{config}->{name}->{space}->{parent};
103			while ($rel[0] eq $Self or $rel[0] eq $Parent) {
104			if ($rel[0] eq $Parent) {
105			$#abs-- if @abs;
106			}
107			shift @rel;
108			}
109			if (@rel == @$self) {
110			@abs = @rel;
111			} else {
112			push @abs, @rel;
113			}
114			ref ($self)->new (\@abs);
115			}
116
117			=head1 TO DO
118
119			More study needed to enable to include delimiter string in WikiName
120			(string form) as part of data.
121
122			=head1 LICENCE
123
124			Copyright 2004 Wakaba <w@suika.fam.cx>. All rights reserved.
125
126			This program is free software; you can redistribute it and/or
127			modify it under the same terms as Perl itself.
128
129			=cut
130
131			1; # $Date: 2003/04/29 10:36:17 $