lib/SuikaWiki/Implementation.pm


=head1 NAME

SuikaWiki::Implementation --- SuikaWiki : Wiki Core Implementation

=cut

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

our $INTERFACE_VERSION = '2.9.1';

=head1 METHODS

=over 4

=item $wiki = SuikaWiki::Implementation->new ()

Constructs new instance of wiki implementation

=cut

sub new ($;%) {
  my $self = bless {
    implementation_name => 'SuikaWiki',
    implementation_version => 'impl'.$VERSION,
    interface_version => $INTERFACE_VERSION,
  }, shift;
  
  $self;
}

=item $wiki->init_variables

Initialize per-access variables.  This method should be called
before other init_* methods are to be called.

=cut

sub init_variables ($) {
  my $self = shift;
  $self->{var} = {};
  $self->__raise_event (name => 'setting_initial_variables');
}

=item $wiki->init_plugin

Prepares to use wiki plugins

=cut

sub init_plugin ($) {
  my $self = shift;
  require SuikaWiki::Plugin;
  $self->{plugin} = SuikaWiki::Plugin->new;
  
  $self->__raise_event (name => 'plugin_manager_loaded');
}

=item $wiki->init_view

Prepares to use wikiview

=cut

sub init_view ($) {
  my $self = shift;
  require SuikaWiki::View::Implementation;
  $self->{view} = SuikaWiki::View::Implementation->new (wiki => $self);

  $self->__raise_event (name => 'view_implementation_loaded');
}

=item $wiki->init_db

Prepares to use wiki database

=cut

sub init_db ($) {
  my $self = shift;
  return if ref $self->{db};  ## Already initialized
  $self->{config}->{lock}
    = {-directory => $self->{config}->{path_to}->{db__lock__dir},
       -retry     => 20,
       -error_handler => sub {
                    my ($self, %o) = @_;
                    if ($self->{config}->{path_to}->{db__content__error_log}) {
                      open LOG, '>>', $self->{config}->{path_to}
                                           ->{db__content__error_log};
                        print LOG scalar (gmtime),
                                  "\@@{[time]} @{[$$]} {$o{level}}: LOCK: ",
                                  $o{msg}, "\n";
                      close LOG;
                    }
                    if ($o{level} eq 'fatal') {
                      die $o{msg};
                    }
       },
      };
  $self->{var}->{db}->{lock_prop} = sub {
    my $prop = shift;
    my %lock = %{$self->{config}->{lock}};
    $lock{-name} = $prop;
    $lock{-share} = defined $self->{var}->{db}->{read_only}->{$prop}
                  ? $self->{var}->{db}->{read_only}->{$prop}
                  : $self->{var}->{db}->{read_only}->{'#default'};
    \%lock;
  };
  
  require SuikaWiki::DB::Logical;
  $self->{db} = new SuikaWiki::DB::Logical;
  
  $self->__raise_event (name => 'database_loaded');
}

=item $wiki->view_in_mode (%opt)

Doing main process in accordance to the mode.

Actually, this method only raises an event of 'view_in_mode'.
So that "doing main process" code should be registered as an event procedure
of 'view_in_mode'.

=cut

sub view_in_mode ($%) {
  my ($self, %opt) = @_;
  $self->__raise_event (name => 'view_in_mode', argv => [\%opt]);
}

sub __raise_event ($%) {
  my ($self, %o) = @_;
  for (@{$self->{event}->{$o{name}}||[]}) {
    &{$_} ($self, @{$o{argv}||[]});
    ## TODO: canceling
  }
  1;
}

=item $string = $wiki->version

Returns version string of the WikiEngine implementation.
This value is combination of the SuikaWiki Interface version and
implementation's version.

=cut

sub version ($) {
  my ($self) = @_;
  $self->{interface_version} . '-' . $self->{implementation_version};
}

=item $wiki->exit

Exits wiki

=cut

sub exit ($) {
  my $self = shift;
  if ($self->__raise_event (name => 'close')) {
    $self->{db}->close if ref $self->{db};
    undef $self->{db};
  }
}

sub DESTROY ($) {
  my $self = shift;
  if (ref $self->{db}) {
    $self->exit;
  }
}

=back

=head1 PUBLIC PROPERTIES

=over 4

=item $wiki->{config}

Persistent wiki configureation parameters
(that is not changed with the situation when is who accessing in what way)

=over 4

=item ->{charset}->{internal} = <IANA charset name (in lower case)>

Character encoding scheme used in wiki implementation

=item ->{charset}->{output} = <IANA charset name (in lower case)>

Default character encoding scheme used to output content

=item ->{entity}->{expires}->{$rulename} = {delta => $seconds}

How long outputed entity will be fresh.

=item ->{lock}

Default (prototype) properties to give SuikaWiki::DB::Util::Lock

=item ->{page}->{ $name }

WikiPage which has feature of $name

=item ->{path_to}->{ $name }

Filesystem path (or path fragment) to $name

=back

=item $wiki->{db}

Wiki main database

=item @{$wiki->{event}->{ $event_name }}

Event handling procedures

Standarized event names:

=over 4

=item database_loaded

When WikiDatabase manager is loaded.  This event handler is typically
used to set database property module for SuikaWiki::DB::Logical.

=item plugin_manager_loaded

When WikiPlugin manager is loaded.  Note that plugins themselves are not
loaded yet.

=item setting_initial_variables

On the process to set per-access variables.
This event is raised before other core modules such as WikiDatabase
or WikiPlugin are loaded.

=back

=item $wiki->{implementation_name} (default 'SuikaWiki')

Product name of the WikiEngine.

For interoperability, only alphanumeric characters and limited symbols
(those allowed in RFC 2616 token) should be used as parts of product name.

=item $wiki->{implementation_version} (default "impl$VERSION")

WikiEngine implementation's version in string.

For interoperability, only alphanumeric characters and limited symbols
(those allowed in RFC 2616 token) should be used as parts of product name.

=item $wiki->{interface_version} (Read only)

SuikaWiki Interface version implemented by this wiki implementation

=item $wiki->{var}

Non-persistent wiki variable options
(that might vary with context such as caller's argument values)

=over 4

=item ->{client}->{used_for_negotiation} = [<HTTP field name>s]

HTTP (request) header field names used to select variable content.
This value will be used to generate HTTP Vary header field.

=item ->{client}->{user_agent_name} = <HTTP User-Agent field body value>

User agent name provided by such ways as User-Agent field (in HTTP) 
or HTTP_USER_AGENT meta variable (in HTTP-CGI).

=item ->{db}->{lock_prop} = sub ($prop)

Function returning hash reference of lock options
(that will be passed to SuikaWiki::DB::Util::Lock->new).

$prop, an argument to the function, is a database property name.

=item ->{db}->{read_only}->{ $prop } = 1/0

Whether the database property named as $prop is opened in read only
mode or not.  Special property name of '#default' is used to set
the default value referred when {read_only}->{$prop} is not specified
explicily.

Note that this value must be set before the instance of database property
is loaded.

=item ->{input}

Instance of input parameter interface (such as SuikaWiki::Input::HTTP)

=item ->{mode} = mode name

Wiki mode name

=item ->{page} = [page]

WikiPage being referred

=back

=item $wiki->{view}

WikiView implementation (an instance of SuikaWiki::View::Implementation)

=cut

=head1 LICENSE

Copyright 2003 Wakaba <[email protected]>

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

=cut

1; # $Date: 2003/10/30 07:45:46 $
1	wakaba	1.1
2			=head1 NAME
3
4			SuikaWiki::Implementation --- SuikaWiki : Wiki Core Implementation
5
6			=cut
7
8			package SuikaWiki::Implementation;
9			use strict;
10	wakaba	1.4	our $VERSION = do{my @r=(q$Revision: 1.3 $=~/\d+/g);sprintf "%d."."%02d" x $#r,@r};
11	wakaba	1.2
12	wakaba	1.4	our $INTERFACE_VERSION = '2.9.1';
13	wakaba	1.1
14			=head1 METHODS
15
16			=over 4
17
18			=item $wiki = SuikaWiki::Implementation->new ()
19
20			Constructs new instance of wiki implementation
21
22			=cut
23
24			sub new ($;%) {
25	wakaba	1.2	my $self = bless {
26			implementation_name => 'SuikaWiki',
27			implementation_version => 'impl'.$VERSION,
28			interface_version => $INTERFACE_VERSION,
29			}, shift;
30	wakaba	1.1
31			$self;
32			}
33
34	wakaba	1.2	=item $wiki->init_variables
35
36			Initialize per-access variables. This method should be called
37			before other init_* methods are to be called.
38
39			=cut
40
41			sub init_variables ($) {
42			my $self = shift;
43			$self->{var} = {};
44			$self->__raise_event (name => 'setting_initial_variables');
45			}
46
47	wakaba	1.1	=item $wiki->init_plugin
48
49			Prepares to use wiki plugins
50
51			=cut
52
53			sub init_plugin ($) {
54			my $self = shift;
55			require SuikaWiki::Plugin;
56			$self->{plugin} = SuikaWiki::Plugin->new;
57
58			$self->__raise_event (name => 'plugin_manager_loaded');
59			}
60
61			=item $wiki->init_view
62
63			Prepares to use wikiview
64
65			=cut
66
67			sub init_view ($) {
68			my $self = shift;
69			require SuikaWiki::View::Implementation;
70			$self->{view} = SuikaWiki::View::Implementation->new (wiki => $self);
71
72			$self->__raise_event (name => 'view_implementation_loaded');
73			}
74
75			=item $wiki->init_db
76
77			Prepares to use wiki database
78
79			=cut
80
81			sub init_db ($) {
82			my $self = shift;
83	wakaba	1.3	return if ref $self->{db}; ## Already initialized
84	wakaba	1.1	$self->{config}->{lock}
85			= {-directory => $self->{config}->{path_to}->{db__lock__dir},
86			-retry => 20,
87			-error_handler => sub {
88			my ($self, %o) = @_;
89			if ($self->{config}->{path_to}->{db__content__error_log}) {
90			open LOG, '>>', $self->{config}->{path_to}
91			->{db__content__error_log};
92			print LOG scalar (gmtime),
93			"\@@{[time]} @{[$$]} {$o{level}}: LOCK: ",
94			$o{msg}, "\n";
95			close LOG;
96			}
97			if ($o{level} eq 'fatal') {
98			die $o{msg};
99			}
100			},
101			};
102			$self->{var}->{db}->{lock_prop} = sub {
103			my $prop = shift;
104			my %lock = %{$self->{config}->{lock}};
105			$lock{-name} = $prop;
106			$lock{-share} = defined $self->{var}->{db}->{read_only}->{$prop}
107			? $self->{var}->{db}->{read_only}->{$prop}
108			: $self->{var}->{db}->{read_only}->{'#default'};
109			\%lock;
110			};
111
112			require SuikaWiki::DB::Logical;
113			$self->{db} = new SuikaWiki::DB::Logical;
114
115			$self->__raise_event (name => 'database_loaded');
116			}
117
118	wakaba	1.3	=item $wiki->view_in_mode (%opt)
119
120			Doing main process in accordance to the mode.
121
122			Actually, this method only raises an event of 'view_in_mode'.
123			So that "doing main process" code should be registered as an event procedure
124			of 'view_in_mode'.
125
126			=cut
127
128			sub view_in_mode ($%) {
129			my ($self, %opt) = @_;
130			$self->__raise_event (name => 'view_in_mode', argv => [\%opt]);
131			}
132
133	wakaba	1.1	sub __raise_event ($%) {
134			my ($self, %o) = @_;
135			for (@{$self->{event}->{$o{name}}\|\|[]}) {
136	wakaba	1.2	&{$_} ($self, @{$o{argv}\|\|[]});
137	wakaba	1.1	## TODO: canceling
138			}
139			1;
140			}
141
142	wakaba	1.2	=item $string = $wiki->version
143
144			Returns version string of the WikiEngine implementation.
145			This value is combination of the SuikaWiki Interface version and
146			implementation's version.
147
148			=cut
149
150			sub version ($) {
151			my ($self) = @_;
152	wakaba	1.4	$self->{interface_version} . '-' . $self->{implementation_version};
153	wakaba	1.2	}
154
155	wakaba	1.1	=item $wiki->exit
156
157			Exits wiki
158
159			=cut
160
161			sub exit ($) {
162			my $self = shift;
163			if ($self->__raise_event (name => 'close')) {
164			$self->{db}->close if ref $self->{db};
165			undef $self->{db};
166			}
167			}
168
169			sub DESTROY ($) {
170			my $self = shift;
171			if (ref $self->{db}) {
172			$self->exit;
173			}
174			}
175
176			=back
177
178			=head1 PUBLIC PROPERTIES
179
180			=over 4
181
182	wakaba	1.2	=item $wiki->{config}
183
184			Persistent wiki configureation parameters
185			(that is not changed with the situation when is who accessing in what way)
186
187			=over 4
188
189			=item ->{charset}->{internal} = <IANA charset name (in lower case)>
190
191			Character encoding scheme used in wiki implementation
192
193			=item ->{charset}->{output} = <IANA charset name (in lower case)>
194
195			Default character encoding scheme used to output content
196
197			=item ->{entity}->{expires}->{$rulename} = {delta => $seconds}
198
199			How long outputed entity will be fresh.
200
201			=item ->{lock}
202	wakaba	1.1
203			Default (prototype) properties to give SuikaWiki::DB::Util::Lock
204
205	wakaba	1.2	=item ->{page}->{ $name }
206
207			WikiPage which has feature of $name
208
209			=item ->{path_to}->{ $name }
210	wakaba	1.1
211			Filesystem path (or path fragment) to $name
212
213	wakaba	1.2	=back
214
215	wakaba	1.1	=item $wiki->{db}
216
217			Wiki main database
218
219			=item @{$wiki->{event}->{ $event_name }}
220
221			Event handling procedures
222
223	wakaba	1.2	Standarized event names:
224
225			=over 4
226
227			=item database_loaded
228
229			When WikiDatabase manager is loaded. This event handler is typically
230			used to set database property module for SuikaWiki::DB::Logical.
231
232			=item plugin_manager_loaded
233
234			When WikiPlugin manager is loaded. Note that plugins themselves are not
235			loaded yet.
236
237			=item setting_initial_variables
238
239			On the process to set per-access variables.
240			This event is raised before other core modules such as WikiDatabase
241			or WikiPlugin are loaded.
242
243			=back
244
245			=item $wiki->{implementation_name} (default 'SuikaWiki')
246
247			Product name of the WikiEngine.
248
249			For interoperability, only alphanumeric characters and limited symbols
250			(those allowed in RFC 2616 token) should be used as parts of product name.
251
252			=item $wiki->{implementation_version} (default "impl$VERSION")
253
254			WikiEngine implementation's version in string.
255
256			For interoperability, only alphanumeric characters and limited symbols
257			(those allowed in RFC 2616 token) should be used as parts of product name.
258
259			=item $wiki->{interface_version} (Read only)
260
261			SuikaWiki Interface version implemented by this wiki implementation
262
263			=item $wiki->{var}
264
265			Non-persistent wiki variable options
266			(that might vary with context such as caller's argument values)
267
268			=over 4
269
270			=item ->{client}->{used_for_negotiation} = [<HTTP field name>s]
271
272			HTTP (request) header field names used to select variable content.
273			This value will be used to generate HTTP Vary header field.
274
275			=item ->{client}->{user_agent_name} = <HTTP User-Agent field body value>
276
277			User agent name provided by such ways as User-Agent field (in HTTP)
278			or HTTP_USER_AGENT meta variable (in HTTP-CGI).
279
280			=item ->{db}->{lock_prop} = sub ($prop)
281
282			Function returning hash reference of lock options
283			(that will be passed to SuikaWiki::DB::Util::Lock->new).
284
285			$prop, an argument to the function, is a database property name.
286
287			=item ->{db}->{read_only}->{ $prop } = 1/0
288
289			Whether the database property named as $prop is opened in read only
290			mode or not. Special property name of '#default' is used to set
291			the default value referred when {read_only}->{$prop} is not specified
292			explicily.
293
294			Note that this value must be set before the instance of database property
295			is loaded.
296
297			=item ->{input}
298
299			Instance of input parameter interface (such as SuikaWiki::Input::HTTP)
300
301			=item ->{mode} = mode name
302
303			Wiki mode name
304
305			=item ->{page} = [page]
306
307			WikiPage being referred
308
309			=back
310
311			=item $wiki->{view}
312
313			WikiView implementation (an instance of SuikaWiki::View::Implementation)
314
315	wakaba	1.1	=cut
316
317			=head1 LICENSE
318
319			Copyright 2003 Wakaba <[email protected]>
320
321			This program is free software; you can redistribute it and/or
322			modify it under the same terms as Perl itself.
323
324			=cut
325
326	wakaba	1.4	1; # $Date: 2003/10/30 07:45:46 $