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.2 $=~/\d+/g);sprintf "%d."."%02d" x $#r,@r};

our $INTERFACE_VERSION = v2.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::Util;
  SuikaWiki::DB::Util->error_handler->{-error_handler} = sub {
    my ($self, $err_type, $err_msg, $err) = @_;
    $err_msg = caller (3) . '-->' . caller (2) . '-->' . caller (1)
             . ($err->{method} ? '->'.$err->{method} : '')
             . ': '
             . (defined $err->{file} ? $err->{file} . ': ' : '')  
             . (defined $err->{prop} ? $err->{prop} . ': ' : '')
             . (defined $err->{key} ? join ('//', @{$err->{key}}) . ': ' : '')
             . $err_msg;
    if ($self->{config}->{path_to}->{db__content__error_log}) {
      open LOG, '>>', $self->{config}->{path_to}->{db__content__error_log};
        print LOG scalar (gmtime), " @{[$$]} {$err_type->{level}}: ",
                  $err_msg, "\n";
      close LOG;
    }
    if ($err_type->{level} eq 'fatal' || $err_type->{level} eq 'stop') {
      require Carp;
      local $Carp::Verbose = 1;
      Carp::croak $err_msg;
    }
  };
  
  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) = @_;
  sprintf '%vd-%s', $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
in v-string format.

=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/18 07:08:34 $
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.3	our $VERSION = do{my @r=(q$Revision: 1.2 $=~/\d+/g);sprintf "%d."."%02d" x $#r,@r};
11	wakaba	1.2
12			our $INTERFACE_VERSION = v2.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::Util;
113			SuikaWiki::DB::Util->error_handler->{-error_handler} = sub {
114			my ($self, $err_type, $err_msg, $err) = @_;
115			$err_msg = caller (3) . '-->' . caller (2) . '-->' . caller (1)
116			. ($err->{method} ? '->'.$err->{method} : '')
117			. ': '
118			. (defined $err->{file} ? $err->{file} . ': ' : '')
119			. (defined $err->{prop} ? $err->{prop} . ': ' : '')
120			. (defined $err->{key} ? join ('//', @{$err->{key}}) . ': ' : '')
121			. $err_msg;
122			if ($self->{config}->{path_to}->{db__content__error_log}) {
123			open LOG, '>>', $self->{config}->{path_to}->{db__content__error_log};
124			print LOG scalar (gmtime), " @{[$$]} {$err_type->{level}}: ",
125			$err_msg, "\n";
126			close LOG;
127			}
128			if ($err_type->{level} eq 'fatal' \|\| $err_type->{level} eq 'stop') {
129	wakaba	1.3	require Carp;
130			local $Carp::Verbose = 1;
131			Carp::croak $err_msg;
132	wakaba	1.1	}
133			};
134
135			require SuikaWiki::DB::Logical;
136			$self->{db} = new SuikaWiki::DB::Logical;
137
138			$self->__raise_event (name => 'database_loaded');
139			}
140
141	wakaba	1.3	=item $wiki->view_in_mode (%opt)
142
143			Doing main process in accordance to the mode.
144
145			Actually, this method only raises an event of 'view_in_mode'.
146			So that "doing main process" code should be registered as an event procedure
147			of 'view_in_mode'.
148
149			=cut
150
151			sub view_in_mode ($%) {
152			my ($self, %opt) = @_;
153			$self->__raise_event (name => 'view_in_mode', argv => [\%opt]);
154			}
155
156	wakaba	1.1	sub __raise_event ($%) {
157			my ($self, %o) = @_;
158			for (@{$self->{event}->{$o{name}}\|\|[]}) {
159	wakaba	1.2	&{$_} ($self, @{$o{argv}\|\|[]});
160	wakaba	1.1	## TODO: canceling
161			}
162			1;
163			}
164
165	wakaba	1.2	=item $string = $wiki->version
166
167			Returns version string of the WikiEngine implementation.
168			This value is combination of the SuikaWiki Interface version and
169			implementation's version.
170
171			=cut
172
173			sub version ($) {
174			my ($self) = @_;
175			sprintf '%vd-%s', $self->{interface_version}, $self->{implementation_version};
176			}
177
178	wakaba	1.1	=item $wiki->exit
179
180			Exits wiki
181
182			=cut
183
184			sub exit ($) {
185			my $self = shift;
186			if ($self->__raise_event (name => 'close')) {
187			$self->{db}->close if ref $self->{db};
188			undef $self->{db};
189			}
190			}
191
192			sub DESTROY ($) {
193			my $self = shift;
194			if (ref $self->{db}) {
195			$self->exit;
196			}
197			}
198
199			=back
200
201			=head1 PUBLIC PROPERTIES
202
203			=over 4
204
205	wakaba	1.2	=item $wiki->{config}
206
207			Persistent wiki configureation parameters
208			(that is not changed with the situation when is who accessing in what way)
209
210			=over 4
211
212			=item ->{charset}->{internal} = <IANA charset name (in lower case)>
213
214			Character encoding scheme used in wiki implementation
215
216			=item ->{charset}->{output} = <IANA charset name (in lower case)>
217
218			Default character encoding scheme used to output content
219
220			=item ->{entity}->{expires}->{$rulename} = {delta => $seconds}
221
222			How long outputed entity will be fresh.
223
224			=item ->{lock}
225	wakaba	1.1
226			Default (prototype) properties to give SuikaWiki::DB::Util::Lock
227
228	wakaba	1.2	=item ->{page}->{ $name }
229
230			WikiPage which has feature of $name
231
232			=item ->{path_to}->{ $name }
233	wakaba	1.1
234			Filesystem path (or path fragment) to $name
235
236	wakaba	1.2	=back
237
238	wakaba	1.1	=item $wiki->{db}
239
240			Wiki main database
241
242			=item @{$wiki->{event}->{ $event_name }}
243
244			Event handling procedures
245
246	wakaba	1.2	Standarized event names:
247
248			=over 4
249
250			=item database_loaded
251
252			When WikiDatabase manager is loaded. This event handler is typically
253			used to set database property module for SuikaWiki::DB::Logical.
254
255			=item plugin_manager_loaded
256
257			When WikiPlugin manager is loaded. Note that plugins themselves are not
258			loaded yet.
259
260			=item setting_initial_variables
261
262			On the process to set per-access variables.
263			This event is raised before other core modules such as WikiDatabase
264			or WikiPlugin are loaded.
265
266			=back
267
268			=item $wiki->{implementation_name} (default 'SuikaWiki')
269
270			Product name of the WikiEngine.
271
272			For interoperability, only alphanumeric characters and limited symbols
273			(those allowed in RFC 2616 token) should be used as parts of product name.
274
275			=item $wiki->{implementation_version} (default "impl$VERSION")
276
277			WikiEngine implementation's version in string.
278
279			For interoperability, only alphanumeric characters and limited symbols
280			(those allowed in RFC 2616 token) should be used as parts of product name.
281
282			=item $wiki->{interface_version} (Read only)
283
284			SuikaWiki Interface version implemented by this wiki implementation
285			in v-string format.
286
287			=item $wiki->{var}
288
289			Non-persistent wiki variable options
290			(that might vary with context such as caller's argument values)
291
292			=over 4
293
294			=item ->{client}->{used_for_negotiation} = [<HTTP field name>s]
295
296			HTTP (request) header field names used to select variable content.
297			This value will be used to generate HTTP Vary header field.
298
299			=item ->{client}->{user_agent_name} = <HTTP User-Agent field body value>
300
301			User agent name provided by such ways as User-Agent field (in HTTP)
302			or HTTP_USER_AGENT meta variable (in HTTP-CGI).
303
304			=item ->{db}->{lock_prop} = sub ($prop)
305
306			Function returning hash reference of lock options
307			(that will be passed to SuikaWiki::DB::Util::Lock->new).
308
309			$prop, an argument to the function, is a database property name.
310
311			=item ->{db}->{read_only}->{ $prop } = 1/0
312
313			Whether the database property named as $prop is opened in read only
314			mode or not. Special property name of '#default' is used to set
315			the default value referred when {read_only}->{$prop} is not specified
316			explicily.
317
318			Note that this value must be set before the instance of database property
319			is loaded.
320
321			=item ->{input}
322
323			Instance of input parameter interface (such as SuikaWiki::Input::HTTP)
324
325			=item ->{mode} = mode name
326
327			Wiki mode name
328
329			=item ->{page} = [page]
330
331			WikiPage being referred
332
333			=back
334
335			=item $wiki->{view}
336
337			WikiView implementation (an instance of SuikaWiki::View::Implementation)
338
339	wakaba	1.1	=cut
340
341			=head1 LICENSE
342
343			Copyright 2003 Wakaba <[email protected]>
344
345			This program is free software; you can redistribute it and/or
346			modify it under the same terms as Perl itself.
347
348			=cut
349
350	wakaba	1.3	1; # $Date: 2003/10/18 07:08:34 $