From ef67262a3ff449c1b489eab0d673a0ced8d45285 Mon Sep 17 00:00:00 2001
From: Evan Prodromou <evan@status.net>
Date: Mon, 18 Apr 2011 06:16:32 -0400
Subject: [PATCH] Externalize document-finding code so plugins can use it

---
 actions/doc.php |  71 ++-------------------------
 lib/docfile.php | 127 ++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 132 insertions(+), 66 deletions(-)
 create mode 100644 lib/docfile.php

diff --git a/actions/doc.php b/actions/doc.php
index 20cf9e2810..95f76fb9dd 100644
--- a/actions/doc.php
+++ b/actions/doc.php
@@ -147,80 +147,19 @@ class DocAction extends Action
     {
         if (Event::handle('StartLoadDoc', array(&$this->title, &$this->output))) {
 
-            $this->filename = $this->getFilename();
+            $paths = DocFile::defaultPaths();
 
-            if (empty($this->filename)) {
+            $docfile = DocFile::forTitle($this->title, $paths);
+
+            if (empty($docfile)) {
                 // TRANS: Client exception thrown when requesting a document from the documentation that does not exist.
                 // TRANS: %s is the non-existing document.
                 throw new ClientException(sprintf(_('No such document "%s".'), $this->title), 404);
             }
 
-            $c = file_get_contents($this->filename);
-
-            $this->output = common_markup_to_html($c);
+            $this->output = $docfile->toHTML();
 
             Event::handle('EndLoadDoc', array($this->title, &$this->output));
         }
     }
-
-    function getFilename()
-    {
-        $localDef = null;
-        $local    = null;
-
-        $site = StatusNet::currentSite();
-
-        if (!empty($site) && file_exists(INSTALLDIR.'/local/doc-src/'.$site.'/'.$this->title)) {
-            $localDef = INSTALLDIR.'/local/doc-src/'.$site.'/'.$this->title;
-
-            $local = glob(INSTALLDIR.'/local/doc-src/'.$site.'/'.$this->title.'.*');
-            if ($local === false) {
-                // Some systems return false, others array(), if dir didn't exist.
-                $local = array();
-            }
-        } else {
-            if (file_exists(INSTALLDIR.'/local/doc-src/'.$this->title)) {
-                $localDef = INSTALLDIR.'/local/doc-src/'.$this->title;
-            }
-
-            $local = glob(INSTALLDIR.'/local/doc-src/'.$this->title.'.*');
-            if ($local === false) {
-                $local = array();
-            }
-        }
-
-        if (count($local) || isset($localDef)) {
-            return $this->negotiateLanguage($local, $localDef);
-        }
-
-        if (file_exists(INSTALLDIR.'/doc-src/'.$this->title)) {
-            $distDef = INSTALLDIR.'/doc-src/'.$this->title;
-        }
-
-        $dist = glob(INSTALLDIR.'/doc-src/'.$this->title.'.*');
-        if ($dist === false) {
-            $dist = array();
-        }
-
-        if (count($dist) || isset($distDef)) {
-            return $this->negotiateLanguage($dist, $distDef);
-        }
-
-        return null;
-    }
-
-    function negotiateLanguage($filenames, $defaultFilename=null)
-    {
-        // XXX: do this better
-
-        $langcode = common_language();
-
-        foreach ($filenames as $filename) {
-            if (preg_match('/\.'.$langcode.'$/', $filename)) {
-                return $filename;
-            }
-        }
-
-        return $defaultFilename;
-    }
 }
diff --git a/lib/docfile.php b/lib/docfile.php
new file mode 100644
index 0000000000..ca03370d29
--- /dev/null
+++ b/lib/docfile.php
@@ -0,0 +1,127 @@
+<?php
+/**
+ * StatusNet - the distributed open-source microblogging tool
+ * Copyright (C) 2011, StatusNet, Inc.
+ *
+ * Utility for finding and parsing documentation files
+ * 
+ * PHP version 5
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ *
+ * @category  Documentation
+ * @package   StatusNet
+ * @author    Evan Prodromou <evan@status.net>
+ * @copyright 2011 StatusNet, Inc.
+ * @license   http://www.fsf.org/licensing/licenses/agpl-3.0.html AGPL 3.0
+ * @link      http://status.net/
+ */
+
+if (!defined('STATUSNET')) {
+    // This check helps protect against security problems;
+    // your code file can't be executed directly from the web.
+    exit(1);
+}
+
+/**
+ * Utility for finding and parsing documentation files
+ *
+ * @category  Documentation
+ * @package   StatusNet
+ * @author    Evan Prodromou <evan@status.net>
+ * @copyright 2011 StatusNet, Inc.
+ * @license   http://www.fsf.org/licensing/licenses/agpl-3.0.html AGPL 3.0
+ * @link      http://status.net/
+ */
+
+class DocFile
+{
+    protected $filename;
+    protected $contents;
+
+    function __construct($filename)
+    {
+        $this->filename = $filename;
+    }
+
+    static function forTitle($title, $paths)
+    {
+        if (is_string($paths)) {
+            $paths = array($paths);
+        }
+
+        $filename = null;
+
+        foreach ($paths as $path) {
+
+            $def = $path.'/'.$title;
+            if (!file_exists($def)) {
+                $def = null;
+            }
+
+            $lang = glob($path.'/'.$title.'.*');
+
+            if ($lang === false) {
+                $lang = array();
+            }
+
+            if (!empty($lang) || !empty($def)) {
+                $filename = self::negotiateLanguage($lang, $def);
+                break;
+            }
+        }
+
+        if (empty($filename)) {
+            return null;
+        } else {
+            return new DocFile($filename);
+        }
+    }
+
+    function toHTML()
+    {
+        if (empty($this->contents)) {
+            $this->contents = file_get_contents($this->filename);
+        }
+
+        $this->output = common_markup_to_html($this->contents);
+    }
+
+    static function defaultPaths()
+    {
+        $paths = array(INSTALLDIR.'/local/doc-src/',
+                       INSTALLDIR.'/doc-src/');
+
+        $site = StatusNet::currentSite();
+        
+        if (!empty($site)) {
+            array_unshift($paths, INSTALLDIR.'/local/doc-src/'.$site.'/');
+        }
+    }
+
+    static function negotiateLanguage($filenames, $defaultFilename=null)
+    {
+        // XXX: do this better
+
+        $langcode = common_language();
+
+        foreach ($filenames as $filename) {
+            if (preg_match('/\.'.$langcode.'$/', $filename)) {
+                return $filename;
+            }
+        }
+
+        return $defaultFilename;
+    }
+}