# $File: //depot/OurNet-BBS/BBS.pm $ $Author: autrijus $
# $Revision: #38 $ $Change: 1919 $ $DateTime: 2001/09/28 12:33:00 $

=head1 NAME

OurNet::BBS - Component Object Model for BBS systems

=head1 VERSION

This document describes version 1.64 of OurNet::BBS, released
February 7, 2002.

=head1 SYNOPSIS

    use strict;
    use OurNet::BBS;

    my $BBS = OurNet::BBS->new({
	backend	=> 'MELIX',		# use the Melix BBS backend
	bbsroot	=> '/home/melix',	# where to find the BBS data
    });

    my $brd = $BBS->{boards}{sysop};	# the sysop board
    my $mtime;

    printf (
        "This BBS has %d boards, %d groups.\n",
        scalar keys(%{$BBS->{boards}}),
        scalar keys(%{$BBS->{groups}}),
    );

    eval { $mtime = $brd->{articles}->mtime };
    die "Error: cannot read board $board -- $@\n" if $@;

    printf (
        "The $board board has %d articles, %d top-level archive entries.\n",
        $#{$brd->{articles}}, $#{$brd->{archives}},
    );

    # A simple Sysop board article monitor
    print "Watching for new articles...\n";

    while (1) {
        print "=== wait here ($mtime) ===\n";
        sleep 5 until ($brd->{articles}->refresh);

        foreach my $article (@{$brd->{articles}}) {
            print "Found article: $article->{title}\n" 
		if $article->btime > $mtime;
        }

        $mtime = $brd->{articles}->mtime;
    }

=head1 DESCRIPTION

OurNet-BBS is a cross-protocol distributed network, built as an
abstraction layer over telnet BBS-based systems used in Hong Kong,
China and Taiwan. It implements a flexible object model for
different BBS backends, along with an asymmetric authentication
and remote procedure call protocol.

This project aims to become a I<protocol agnostic> middle ware
solution for identity-based information storage & retrieval,
much like the Project Jabber's goal toward instant messaging,
or Project JXTA's aim toward distributed services.

If you are new to the telnet-bbs platform, please download a
copy of Melix BBS software (in English, Traditional Chinese
and Simplified Chinese) at L<http://melix.elixus.org/>.

For some of its practical uses, search for B<OurNet::BBSApp>
on CPAN, and the sample scripts in the F<eg/> directory in this
module's distribution.

=head1 HISTORY

=over 4

=item v1.64 Thu Feb  7 05:31:37 CST 2002

Better parsing of NNTP-style B<BBSAgent> articles.

The B<bbsboard> utilitiy now respects the board's {permit} settings.

Reconnection is supported in B<OurNet::Client>.

New C<-s> (non-forking) flag for B<bbscomd>.

New C<-G> flag for B<bbscomd> to allow login as any user.

Hash components now has the C<KEYS> method.

Major overhaul in B<UserGroup> work to provide consistent behaviour.

Introduces experimental B<Firebird3> backend (User and Board only).

Relaxed Makefile.PL requirements; no install of B<MailBox> by default.

Removed B<ExtUtils> so it has to be fetched from CPAN manually.

The F<eg/> directory now contains some sample scripts.

Prefers the use of hashref by-name new() syntax in examples and tests.

The hashref constructor syntax is accepted by B<OurNet> backend.

Split documentation about roadmap to B<OurNet::BBS::Roadmap>.

=item v1.63, Mon Dec 10 20:21:38 CST 2001

Added three simple diagrams in B<OurNet::BBS::Tutorial>.

A longer timeout (60 sec) is now used by B<BBSAgent>.

Fixed installation glitches reported by pudge.

Remove unused B<MELIX> toplevel fields C<usershmkey> and C<maxuser>.

Group semantic in B<MAPLE3> and B<MELIX> finally worked.

The dependency to B<Test::More> 0.31+ is now handled.

Better diagnostics from the test process.

Updated document to cut down sales-talk and beef up spelling.

New ciphers B<Crypt::DES_EDE3> and B<Crypt::Rijndael_PP> are supported.

The B<NNTP> backend now handles C<id> and C<title> predicably.

Fixed a B<bbscomd> bug of not detecting wrong passphrases.

Secure communication via B<CIPH_PGP> is restored.

If the gnupg keyring is suddenly unavailable, B<Server> can now accomodate.

The auto-installer B<ExtUtils::AutoInstall> is now less buggy.

MIME QuotedPrint handling of B<bbsboard>/B<bbsmail> has been improved.

=item v1.62, Mon Oct 15 07:48:58 CST 2001

No longer depends on B<GnuPG::Interface> to run.

The B<OurNet> protocol has been updated to C<0.4> with callback support.

Assigning a coderef directly (but not inside refs) via B<OurNet> now works.

New, write-only B<External> backend to utilize F<sendmail> and the like.

Tainting check should now work on B<bbsboard> and B<bbsmail>.

GC stability on perl v5.6.x is much better.

A revised, more flexible F<Makefile.PL>.

=item v1.61, Fri Sep 28 00:53:46 CST 2001

Adds a read-only, experimental B<Cola> backend.

Implements re-authentication for B<Server>.

Bundles F<bbsboard> and F<bbsmail> utilities.

The B<BBSAgent> backend now has a F<logfile> property for debugging use.

Permission model and group support for B<CVIC>.

Fixes various B<Base> namespace pollution bugs.

Public key-based login is working now.

Additional B<Server> options could be set in C<%OurNet::BBS::Server::Options>.

Introduced the B<Bundle::OurNet> namespace.

=item v1.6, Mon Sep  3 23:07:36 CST 2001

Changed B<Server> and B<Client>'s default port from 7978 to 7979.

Complete ArticleGroup permission model for B<MELIX>.

A <-g> options now enables F<bbscomd> to accept guest-privileged connections.

Delete board / articles now works in file-based backends.

Changed B<DBI> to B<RAM>; it has nothing to do with DBI anyway.

Integrated the new set of design documents into manpage.

=item v1.6-delta, Mon Aug 28 01:47:18 CST 2001

Session support for B<MELIX> backend.

Purged B<LWP> support from tree; nobody's using it anyway.

Fixed context problems of B<NNTP> and B<OurNet> backends.

The B<OurNet> protocol could now pass back arguments by reference.

Passes tests on Win32 now.

Post-back of B<BBSAgent> and B<SessionGroup> fixed.

=item v1.6-gamma, Thu Aug 16 17:37:12 CST 2001

The test cases in C<t/> are now numbered, and OurNet-based tests
added. For the first time, all tests pass.

Implemented C<{'owner'}> fetch for B<CVIC> groups.

The chrono-ahead algorithm now works correctly for all backends,
so there will no longer be duplicate C<Message-ID>s.

Fixed the B<MAPLE3> backend's incestuous relationship with B<MELIX>.

Upgraded the B<Authen> protocol to v0.3. Setting the flag
C<$OurNet::BBS::BYPASS_NEGOTIATION> now bypasses handshaking
altogether.

=item v1.6-beta, Tue Aug 14 03:31:10 CST 2001

A streamlined C<t/stdtest> base now applies to all three 
file-based backends.

The C<{''} = ...> STORE-as-PUSH semantics is fully supported.

Group metadata unified into hash-based C<{owner|title|id}>.

Compatibility for perl 5.7.x, including line disciplines.

The long-timed 'extra test' heisenbug has been eliminated.

=item v1.6-alpha, Sun Aug 12 19:03:08 CST 2001

Added the HISTORY section in manpage.

Rewritten B<Base> to be C<overload>-based.

Eliminated B<ArrayProxy> and pseudohashes.

Uses B<Test::More> instead of B<Test>.

Improved MIME and mail address parsing regexes.

A much faster and robust B<NNTP> backend.

The B<DBI> backend rewritten to indicate style change.

=item v1.56, Mon Jul 23 02:12:06 2001

File access via B<FileGroup> components.

Group support for B<MAPLE3> with a twisted API.

Proper permission control for nearly all components.

Unix-style mailbox support via the B<MailBox> backend.

CR/LF bug on Win32 eliminated.

=item v1.55, Wed Jun 20 06:17:16 2001

The full B<OurNet> authentication model.

Fixed B<UserGroup> for B<MAPLE*> backends.

A new Message-ID formula.

Fixed core dump in various, but not all, places.

Massive speed increase.

=item v1.54, Wed Jun 13 11:43:12 2001

This version implements the new B<OurNet> (formerly known as B<PlClient>)
asymmetric-key based authentication model, article/board permission model
for M3 backends, numerous bug fixes, win32 support, and much, much more.

=item v1.53, Sat Jun  9 11:09:26 2001

Full F<bbscomd> support; B<PlClient> is now a valid backend. (autrijus)

Finally fixed the internal object model; using multiple backends was
broken due to back-propagation of initvar() variables. (autrijus)

STORE into B<MAPLE*> backends should now update shm correctly. (autrijus)

Improved B<BBSAgent> error handling for fail-safe operations. (clkao)

Fixed hazard caused by remote empty (or deleted) articles. (clkao)

Nickname support for B<MAPLE2>/B<CVIC> is reimplemented. (clkao)

BBSAgent now matches nickname even in pathetic cases. (smartboy)

=item v1.52, Wed Jun  6 05:53:54 2001

Clean-up release to fix many 1.51 glitches, with added documentation
and test cases added.

=item v1.51, Sat Jun  2 07:05:18 2001

Forked out from C<libOurNet> distribution.

Vastly improved support for B<BBSAgent> backend to support F<ebx>,
with many parsing enhancement and templates from smartboy.

=item v1.4-alpha4, Fri Mar 23 03:21:14 2001

Integrated the B<MAPLE3> backend.

=item v1.4-alpha3, Fri Jan 12 04:57:17 2001

First Win32 (ppm) release.

=item v1.4-alpha2, Mon Jan 15 07:39:00 2001

Adds B<LWP::Protocol> support and B<Session> components.

=item v1.4-alpha, Fri Jan 12 04:54:29 2001

First CPAN release, featuring the B<BBSAgent> backend.

=item v1.3, Fri Dec 29 05:40:11 2000

Provides simple remote access via B<OurNet::BBS::PlClient>.

=item v1.2, Thu Dec  7 05:02:39 2000

Backend abstraction revised; added B<PTT> backend by gugod.

=item v1.1, Tue Nov 21 19:00:33 2000

Initial commit, with B<CVIC> as the only backend.

=back

=head1 SEE ALSO

L<OurNet::BBS::Tutorial> for a general overview of the B<OurNet::BBS>
model.

L<OurNet::BBS::Roadmap> for the design goals, components, and related
discussions.

L<http://melix.elixus.org/> for development news, new releases, and
binary distributions.

=head1 AUTHORS

Chia-Liang Kao E<lt>clkao@clkao.orgE<gt>,
Autrijus Tang E<lt>autrijus@autrijus.orgE<gt>

=head1 COPYRIGHT

Copyright 2001-2002 by
Chia-Liang Kao E<lt>clkao@clkao.orgE<gt>,
Autrijus Tang E<lt>autrijus@autrijus.orgE<gt>.

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

See L<http://www.perl.com/perl/misc/Artistic.html>

=cut
