[Rt-commit] rt branch, 4.0/convenient-rt-init, created. rt-4.0.11rc1-29-g042ac27

[Thomas Sibley]

The branch, 4.0/convenient-rt-init has been created
        at  042ac27969a8d38038aee9db16cb96c2b79eb5d2 (commit)

- Log -----------------------------------------------------------------
commit a356872c01c7a8a684eac81208482ae1717381d3
Author: Thomas Sibley <trs at bestpractical.com>
Date:   Mon Apr 8 15:12:25 2013 -0700

    Clarify what RT.pm's documentation is about

diff --git a/lib/RT.pm b/lib/RT.pm
index 1a59e43..87e2f0d 100644
--- a/lib/RT.pm
+++ b/lib/RT.pm
@@ -83,7 +83,11 @@ RT - Request Tracker
 
 =head1 SYNOPSIS
 
-A fully featured request tracker package
+A fully featured request tracker package.
+
+This documentation describes the point-of-entry for RT's Perl API.  To learn
+more about what RT is and what it can do for you, visit
+L<https://bestpractical.com/rt>.
 
 =head1 DESCRIPTION
 

commit 042ac27969a8d38038aee9db16cb96c2b79eb5d2
Author: Thomas Sibley <trs at bestpractical.com>
Date:   Mon Apr 8 15:12:44 2013 -0700

    Convenient initialization via "use RT -init;"
    
    This allows external code to turn the annoying boilerplate of:
    
        use RT;
        RT->LoadConfig;
        RT->Init;
    
    into
    
        use RT -init;
    
    as long as it doesn't do anything funky between loading RT, calling
    LoadConfig and calling Init.

diff --git a/lib/RT.pm b/lib/RT.pm
index 87e2f0d..875525a 100644
--- a/lib/RT.pm
+++ b/lib/RT.pm
@@ -93,6 +93,44 @@ L<https://bestpractical.com/rt>.
 
 =head2 INITIALIZATION
 
+If you're using RT's Perl libraries, you need to initialize RT before using any
+of the modules.
+
+You have the option of handling the timing of config loading and the actual
+init sequence yourself with:
+
+    use RT;
+    RT->LoadConfig;
+    RT->Init;
+
+or you can let RT do it all:
+
+    use RT -init;
+
+This second method is particular useful when writing one-liners to interact with RT:
+
+    perl -MRT=-init -e '...'
+
+The first method is necessary if you need to delay or conditionalize
+initialization or if you want to fiddle with C<< RT->Config >> between loading
+the config files and initializing the RT environment.
+
+=cut
+
+{
+    my $DID_IMPORT_INIT;
+    sub import {
+        my $class  = shift;
+        my $action = shift || '';
+
+        if ($action eq "-init" and not $DID_IMPORT_INIT) {
+            $class->LoadConfig;
+            $class->Init;
+            $DID_IMPORT_INIT = 1;
+        }
+    }
+}
+
 =head2 LoadConfig
 
 Load RT's config file.  First, the site configuration file

-----------------------------------------------------------------------