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.4 $=~/\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 (wiki => $self);
  
  $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;
}

sub ___raise_event ($$$) {
  my ($self, $name, $argv) = @_;
  my $event = {cancel => 0, name => $name, $name => $argv};
  for (@{$self->{event}->{$name}}) {
    $_->($self, $event);
    return 0 if $event->{cancel};
  }
  return 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};
}

sub close_db ($) {
  my $self = shift;
  $self->{db}->close if ref $self->{db};
  delete $self->{db};
}

sub close_view ($) {
  my $self = shift;
  $self->{view}->exit if ref $self->{view};
  delete $self->{view};
}

sub close_plugin ($) {
  my $self = shift;
  $self->{plugin}->exit if ref $self->{plugin};
  delete $self->{plugin};
}

sub close_input ($) {
  my $self = shift;
  $self->{input}->exit if ref $self->{input};
  delete $self->{input};
}

=item $wiki->exit

Exits wiki

=cut

sub exit ($) {
  my $self = shift;
  return 0 unless $self->___raise_event (name => 'close');
  $self->close_db;
  $self->close_view;
  $self->close_input;
  $self->close_plugin;
  $self->{exited} = 1;
  1;
}

sub DESTROY ($) {
  my $self = shift;
  $self->exit unless $self->{exited};
}

=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 ->{debug}->{$category} = 1/0 (Default 0)

Debug mode

Categories:

=over 4

=item db

WikiDatabase related features

=back

=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 ->{error} = [{description => Error 1}, {description => Error 2},...]

Trapped errors.

=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 <w@suika.fam.cx>

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

=cut

1; # $Date: 2003/11/25 12:42:47 $
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.5	our $VERSION = do{my @r=(q$Revision: 1.4 $=~/\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	wakaba	1.5	$self->{plugin} = SuikaWiki::Plugin->new (wiki => $self);
57	wakaba	1.1
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.5	sub ___raise_event ($$$) {
143			my ($self, $name, $argv) = @_;
144			my $event = {cancel => 0, name => $name, $name => $argv};
145			for (@{$self->{event}->{$name}}) {
146			$_->($self, $event);
147			return 0 if $event->{cancel};
148			}
149			return 1;
150			}
151
152	wakaba	1.2	=item $string = $wiki->version
153
154			Returns version string of the WikiEngine implementation.
155			This value is combination of the SuikaWiki Interface version and
156			implementation's version.
157
158			=cut
159
160			sub version ($) {
161			my ($self) = @_;
162	wakaba	1.4	$self->{interface_version} . '-' . $self->{implementation_version};
163	wakaba	1.2	}
164
165	wakaba	1.5	sub close_db ($) {
166			my $self = shift;
167			$self->{db}->close if ref $self->{db};
168			delete $self->{db};
169			}
170
171			sub close_view ($) {
172			my $self = shift;
173			$self->{view}->exit if ref $self->{view};
174			delete $self->{view};
175			}
176
177			sub close_plugin ($) {
178			my $self = shift;
179			$self->{plugin}->exit if ref $self->{plugin};
180			delete $self->{plugin};
181			}
182
183			sub close_input ($) {
184			my $self = shift;
185			$self->{input}->exit if ref $self->{input};
186			delete $self->{input};
187			}
188
189	wakaba	1.1	=item $wiki->exit
190
191			Exits wiki
192
193			=cut
194
195			sub exit ($) {
196			my $self = shift;
197	wakaba	1.5	return 0 unless $self->___raise_event (name => 'close');
198			$self->close_db;
199			$self->close_view;
200			$self->close_input;
201			$self->close_plugin;
202			$self->{exited} = 1;
203			1;
204	wakaba	1.1	}
205
206			sub DESTROY ($) {
207			my $self = shift;
208	wakaba	1.5	$self->exit unless $self->{exited};
209	wakaba	1.1	}
210
211			=back
212
213			=head1 PUBLIC PROPERTIES
214
215			=over 4
216
217	wakaba	1.2	=item $wiki->{config}
218
219			Persistent wiki configureation parameters
220			(that is not changed with the situation when is who accessing in what way)
221
222			=over 4
223
224			=item ->{charset}->{internal} = <IANA charset name (in lower case)>
225
226			Character encoding scheme used in wiki implementation
227
228			=item ->{charset}->{output} = <IANA charset name (in lower case)>
229
230			Default character encoding scheme used to output content
231
232	wakaba	1.5	=item ->{debug}->{$category} = 1/0 (Default 0)
233
234			Debug mode
235
236			Categories:
237
238			=over 4
239
240			=item db
241
242			WikiDatabase related features
243
244			=back
245
246	wakaba	1.2	=item ->{entity}->{expires}->{$rulename} = {delta => $seconds}
247
248			How long outputed entity will be fresh.
249
250			=item ->{lock}
251	wakaba	1.1
252			Default (prototype) properties to give SuikaWiki::DB::Util::Lock
253
254	wakaba	1.2	=item ->{page}->{ $name }
255
256			WikiPage which has feature of $name
257
258			=item ->{path_to}->{ $name }
259	wakaba	1.1
260			Filesystem path (or path fragment) to $name
261
262	wakaba	1.2	=back
263
264	wakaba	1.1	=item $wiki->{db}
265
266			Wiki main database
267
268			=item @{$wiki->{event}->{ $event_name }}
269
270			Event handling procedures
271
272	wakaba	1.2	Standarized event names:
273
274			=over 4
275
276			=item database_loaded
277
278			When WikiDatabase manager is loaded. This event handler is typically
279			used to set database property module for SuikaWiki::DB::Logical.
280
281			=item plugin_manager_loaded
282
283			When WikiPlugin manager is loaded. Note that plugins themselves are not
284			loaded yet.
285
286			=item setting_initial_variables
287
288			On the process to set per-access variables.
289			This event is raised before other core modules such as WikiDatabase
290			or WikiPlugin are loaded.
291
292			=back
293
294			=item $wiki->{implementation_name} (default 'SuikaWiki')
295
296			Product name of the WikiEngine.
297
298			For interoperability, only alphanumeric characters and limited symbols
299			(those allowed in RFC 2616 token) should be used as parts of product name.
300
301			=item $wiki->{implementation_version} (default "impl$VERSION")
302
303			WikiEngine implementation's version in string.
304
305			For interoperability, only alphanumeric characters and limited symbols
306			(those allowed in RFC 2616 token) should be used as parts of product name.
307
308			=item $wiki->{interface_version} (Read only)
309
310			SuikaWiki Interface version implemented by this wiki implementation
311
312			=item $wiki->{var}
313
314			Non-persistent wiki variable options
315			(that might vary with context such as caller's argument values)
316
317			=over 4
318
319			=item ->{client}->{used_for_negotiation} = [<HTTP field name>s]
320
321			HTTP (request) header field names used to select variable content.
322			This value will be used to generate HTTP Vary header field.
323
324			=item ->{client}->{user_agent_name} = <HTTP User-Agent field body value>
325
326			User agent name provided by such ways as User-Agent field (in HTTP)
327			or HTTP_USER_AGENT meta variable (in HTTP-CGI).
328
329			=item ->{db}->{lock_prop} = sub ($prop)
330
331			Function returning hash reference of lock options
332			(that will be passed to SuikaWiki::DB::Util::Lock->new).
333
334			$prop, an argument to the function, is a database property name.
335
336			=item ->{db}->{read_only}->{ $prop } = 1/0
337
338			Whether the database property named as $prop is opened in read only
339			mode or not. Special property name of '#default' is used to set
340			the default value referred when {read_only}->{$prop} is not specified
341			explicily.
342
343			Note that this value must be set before the instance of database property
344			is loaded.
345
346	wakaba	1.5	=item ->{error} = [{description => Error 1}, {description => Error 2},...]
347
348			Trapped errors.
349
350	wakaba	1.2	=item ->{input}
351
352			Instance of input parameter interface (such as SuikaWiki::Input::HTTP)
353
354			=item ->{mode} = mode name
355
356			Wiki mode name
357
358			=item ->{page} = [page]
359
360			WikiPage being referred
361
362			=back
363
364			=item $wiki->{view}
365
366			WikiView implementation (an instance of SuikaWiki::View::Implementation)
367
368	wakaba	1.1	=cut
369
370			=head1 LICENSE
371
372			Copyright 2003 Wakaba <w@suika.fam.cx>
373
374			This program is free software; you can redistribute it and/or
375			modify it under the same terms as Perl itself.
376
377			=cut
378
379	wakaba	1.5	1; # $Date: 2003/11/25 12:42:47 $