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.1 $=~/\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;
  $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') {
      die $err_msg;
    }
  };
  
  require SuikaWiki::DB::Logical;
  $self->{db} = new SuikaWiki::DB::Logical;
  
  $self->__raise_event (name => 'database_loaded');
}

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