--- deliantra/server/lib/cf.pm	2006/09/12 23:45:16	1.68
+++ deliantra/server/lib/cf.pm	2006/10/01 11:41:37	1.72
@@ -7,10 +7,14 @@
 use Safe;
 use Safe::Hole;
 
+use YAML::Syck ();
 use Time::HiRes;
 use Event;
 $Event::Eval = 1; # no idea why this is required, but it is
 
+# work around bug in YAML::Syck - bad news for perl6, will it be as broken wrt. unicode?
+$YAML::Syck::ImplicitUnicode = 1;
+
 use strict;
 
 _init_vars;
@@ -23,6 +27,32 @@
 our $TICK_WATCHER;
 our $NEXT_TICK;
 
+our %CFG;
+
+#############################################################################
+
+=head2 GLOBAL VARIABLES
+
+=over 4
+
+=item $cf::LIBDIR
+
+The perl library directory, where extensions and cf-specific modules can
+be found. It will be added to C<@INC> automatically.
+
+=item $cf::TICK
+
+The interval between server ticks, in seconds.
+
+=item %cf::CFG
+
+Configuration for the server, loaded from C</etc/crossfire/config>, or
+from wherever your confdir points to.
+
+=back
+
+=cut
+
 BEGIN {
    *CORE::GLOBAL::warn = sub {
       my $msg = join "", @_;
@@ -53,25 +83,43 @@
 my %command;
 my %extcmd;
 
-#############################################################################
-# utility functions
+=head2 UTILITY FUNCTIONS
+
+=over 4
+
+=cut
 
 use JSON::Syck (); # TODO# replace by JSON::PC once working
 
+=item $ref = cf::from_json $json
+
+Converts a JSON string into the corresponding perl data structure.
+
+=cut
+
 sub from_json($) {
    $JSON::Syck::ImplicitUnicode = 1; # work around JSON::Syck bugs
    JSON::Syck::Load $_[0]
 }
 
+=item $json = cf::to_json $ref
+
+Converts a perl data structure into its JSON representation.
+
+=cut
+
 sub to_json($) {
    $JSON::Syck::ImplicitUnicode = 0;  # work around JSON::Syck bugs
    JSON::Syck::Dump $_[0]
 }
 
+=back
+
+=cut
+
 #############################################################################
-# "new" plug-in system
 
-=head3 EVENTS AND OBJECT ATTACHMENTS
+=head2 EVENTS AND OBJECT ATTACHMENTS
 
 =over 4
 
@@ -381,15 +429,15 @@
 
 =back
 
-=head2 methods valid for all pointers
+=cut
 
-=over 4
+#############################################################################
 
-=item $object->valid
+=head2 METHODS VALID FOR ALL CORE OBJECTS
 
-=item $player->valid
+=over 4
 
-=item $map->valid
+=item $object->valid, $player->valid, $map->valid
 
 Just because you have a perl object does not mean that the corresponding
 C-level object still exists. If you try to access an object that has no
@@ -706,7 +754,12 @@
 ;
 
 #############################################################################
-# core extensions - in perl
+
+=head2 CORE EXTENSIONS
+
+Functions and methods that extend core crossfire objects.
+
+=over 4
 
 =item cf::player::exists $login
 
@@ -756,8 +809,21 @@
    $self->send ("ext " . to_json \%msg);
 }
 
+=back
+
+=cut
+
 #############################################################################
-# map scripting support
+
+=head2 SAFE SCRIPTING
+
+Functions that provide a safe environment to compile and execute
+snippets of perl code without them endangering the safety of the server
+itself. Looping constructs, I/O operators and other built-in functionality
+is not available in the safe scripting environment, and the number of
+functions and methods that cna be called is greatly reduced.
+
+=cut
 
 our $safe = new Safe "safe";
 our $safe_hole = new Safe::Hole;
@@ -768,6 +834,16 @@
 
 # here we export the classes and methods available to script code
 
+=pod
+
+The following fucntions and emthods are available within a safe environment:
+
+  cf::object contr pay_amount pay_player
+  cf::object::player player
+  cf::player peaceful
+
+=cut
+
 for (
    ["cf::object"         => qw(contr pay_amount pay_player)],
    ["cf::object::player" => qw(player)],
@@ -779,6 +855,18 @@
       for @funs;
 }
 
+=over 4
+
+=item @retval = safe_eval $code, [var => value, ...]
+
+Compiled and executes the given perl code snippet. additional var/value
+pairs result in temporary local (my) scalar variables of the given name
+that are available in the code snippet. Example:
+
+   my $five = safe_eval '$first + $second', first => 1, second => 4;
+
+=cut
+
 sub safe_eval($;@) {
    my ($code, %vars) = @_;
 
@@ -810,6 +898,21 @@
    wantarray ? @res : $res[0]
 }
 
+=item cf::register_script_function $function => $cb
+
+Register a function that can be called from within map/npc scripts. The
+function should be reasonably secure and should be put into a package name
+like the extension.
+
+Example: register a function that gets called whenever a map script calls
+C<rent::overview>, as used by the C<rent> extension.
+
+   cf::register_script_function "rent::overview" => sub {
+     ...
+   };
+
+=cut
+
 sub register_script_function {
    my ($fun, $cb) = @_;
 
@@ -817,6 +920,10 @@
    *{"safe::$fun"} = $safe_hole->wrap ($cb);
 }
 
+=back
+
+=cut
+
 #############################################################################
 
 =head2 EXTENSION DATABASE SUPPORT
@@ -924,7 +1031,18 @@
 #############################################################################
 # the server's main()
 
+sub load_cfg {
+   open my $fh, "<:utf8", cf::confdir . "/config"
+      or return;
+
+   local $/;
+   *CFG = YAML::Syck::Load <$fh>;
+
+   use Data::Dumper; warn Dumper \%CFG;
+}
+
 sub main {
+   load_cfg;
    db_load;
    load_extensions;
    Event::loop;