                                                                                                                                                        


<?php
//-->-->-->-->-->-->-->-->
//--Name:
//--   fnHyperLinkPlainText.php  - markup up URLs with HTML hyperlinks
//--
//--Description:
//--   The purpose of this function is to insert HTML hyperlinks into a plain
//--   text string in meaningful and appropriate places. The regular 
//--   expression patterns essentially 'guess' as to what consists of 
//--   a hyperlink. Links to local resources are denoted with the 
//--   'link://' pseudo protocol specifier.
//--
//--Usage:
//--   
//--  Here are some plain text formats which should be hyper-linked by 
//--  the current function:
//--
//--  If the url is prefixed with an exclamation mark, then the target
//--  should open in a new window
//-- 
//--     http://somehost.dom/some/resouce.ext
//--     link://some/local/resource.ext
//--     www.somehost.dom/some/resouce.ext
//--       These strings are transformed into HTML hyperlinks which have a
//--       display text of the URL itself
//--
//--     "Hyper-link display text" http://somehost.dom/some/resouce.ext
//--     'Hyper-link display text' http://somehost.dom/some/resouce.ext
//--     "Hyper-link display text" www.somehost.dom/some/resouce.ext
//--     'Hyper-link display text' www.somehost.dom/some/resouce.ext
//--     'Hyper-link display text' link://local/resource.ext
//--     "Hyper-link display text" link://local/resource.ext
//--        These patterns are transformed into HTML hyperlinks which 
//--        a display text of the string which is enclosed within the 
//--        quote characters, and which point to the URL which is 
//--        specified in the second part of the pattern.         
//--
//--     [http://somehost.dom/some/resouce.ext]
//--     [link://some/local/resource.ext]
//--     [www.somehost.dom/some/resouce.ext]
//--        These patterns are transformed into HTML hyperlinks which have
//--        a display text of the characters "[*]" (A star enclosed in 
//--        brackets. I imagine I will enhance this transformation to display
//--        a sequential number inside of the brackets in order to mimic a 
//--        more 'academic' style of footnoting or referencing. This idea
//--        comes from the 'Oddmuse Wiki' http://www.oddmuse.org
//--
//--    
//-- 
//--   The structures -->> and --<< are supposed to prevent any formatting 
//--   of the source text. This should be achieved using an HTML <pre> tag
//--   and by preventing any of the other transformation scripts from acting
//--   on those sections of text. 
//--
//--   
//--Notes:
//--   
//--   Many of the above patterns were inspired by the various 'Wiki'
//--   engines that are currently (2004) available on the Internet. These
//--   Wiki's use a very wide variety of different patterns in order to 
//--   mark-up URLs. My main motivation in choosing the above patterns was
//--   to ensure that the patterns when viewed in a plain text editor did
//--   not appear like 'code'. This is to say that I wanted the patterns to
//--   be very easy to read and edit by the user who is neither familiar with
//--   the various document markup languages, nor has experience with 
//--   the Web Wiki systems.
//-- 
//--   What does the 'link://' schema mean
//--   -----------------------------------
//--   The link:// pseudo URI schema has the purpose of allowing unambiguous
//--   references to resource in the local web-server space. By default, this
//--   schema refers to 'relative' local paths. This means that 
//--     link://wagga-job.html
//--   refers to a file in the 'current' web directory, which is to say, in 
//--   the same web directory as the document which contains this reference.
//--   In order to refer to an 'absolute' local resource, it is necessary to
//--   to use three forward slash characters, as in
//--     link:///wagga-job.html
//--   If this text was contained in a text file on a web-server with the 
//--   domain name www.wagga.org  then the above reference would be transformed
//--   into an HTML hyperlink which would refer to the document
//--     http://www.wagga.org/wagga-job.html
//--
//--
//--   
//--   The 'unformatted' blocks of text present a slight problem to implement
//--   using the PHP regular expression system. There appears no way to 
//--   simply apply pattern transformations only when text is between certain
//--   tags. One way may be to use the 'callback' feature of the PHP regular
//--   expressions.
//-- 
//--   I also want to implement 'reference' or 'footnote' style hyperlinks,
//--   where the text document has a line of text containing something like
//--
//--     This was the last day (See: "Woodridge")
//--   somewhere in the body of the text, and then at the bottom of the text
//--   file, there should be something like
//--   
//--     REF: Woodridge http://www.woodridge.org
//--   The reference note could also contain explanatory text about the 
//--   reference. This system should be straightforward to implement since
//--   the php preg_replace function accepts two arrays as its arguments.
//--
//--
//--See Also:
//--  fnMessageToHtml, fnJournalToHtml, 
//--  fnFaqToHtml, fnCvToHtml, fnDocumentToHtml
//--
//-- 
//--Author:
//--   matth3wbishop@yahoo.com
//--   http://www.geocities.com/matth3wbishop/



function fnHyperlinkPlainText($sPlainText)
{
  $sReturn = $sPlainText;


  //-- Hyperlink email addresses with a 'mailto:' link
  $sReturn = 
    preg_replace(
     '#(\S+@\S+)#im', '<a href="mailto:$1">$1</a>', $sReturn);


  //-- Hyperlink this format:
  //--   "Hyper-link display text" http://somehost.dom/some/resouce.ext
  //-- This assumes that the double quote character " may have already been
  //-- 'entitized' by some previous code or other process.
  $sReturn = 
    preg_replace(
     '#\s(&quot;|"|\')(.+?)(&quot;|"|\')\s{0,20}(http://\S{2,})#im', 
     ' <a href="$4">$2</a>', $sReturn);

  //-- Hyperlink this format:
  //--   "Hyper-link display text" !http://somehost.dom/some/resouce.ext
  //-- This assumes that the double quote character " may have already been
  //-- 'entitized' by some previous code or other process.
  $sReturn = 
    preg_replace(
     '#\s(&quot;|"|\')(.+?)(&quot;|"|\')\s*!(http://\S{2,})#im', 
     ' <a href="$4" target = "_blank">$2</a>', $sReturn);

  //-- Hyperlink this format:
  //--   "Hyper-link display text" www.somehost.dom/some/resouce.ext
  $sReturn = 
    preg_replace(
     '#(&quot;|"|\')(.+?)(&quot;|"|\')\s*(www\.\S{2,})#im', 
     ' <a href="http://$4" target = "_blank">$2</a>', $sReturn);

  //-- Hyperlink this format:
  //--   "Hyper-link display text" !www.somehost.dom/some/resouce.ext
  $sReturn = 
    preg_replace(
     '#(&quot;|"|\')(.+?)(&quot;|"|\')\s*!(www\.\S{2,})#im', 
     ' <a href="http://$4">$2</a>', $sReturn);


  //-- Hyperlink this format:
  //--   "Hyper-link display text" link://local/resource.ext
  //-- In this case the resource specified is assumed to be on the 
  //-- local web-server relative to the web-servers 'document root'
  $sReturn = 
    preg_replace(
     '#(&quot;|"|\')(.+?)(&quot;|"|\')\s*link://(\S{2,})#im', 
     ' <a href="$4">$2</a>', $sReturn);

  //-- Hyperlink this format:
  //--   "Hyper-link display text" !link://local/resource.ext
  //-- In this case the resource specified is assumed to be on the 
  //-- local web-server relative to the web-servers 'document root'
  $sReturn = 
    preg_replace(
     '#(&quot;|"|\')(.+?)(&quot;|"|\')\s*!link://(\S{2,})#im', 
     ' <a href="$4" target = "_blank">$2</a>', $sReturn);

  //-- Ascii menu items are similar to ascii icons, but they
  //-- are designed to point to locale resources

  //-- Create 'ascii icons' which are html entities which are 
  //-- displayed in a large font and which should also be HTML hyperlinks
  //-- The idea of this is to provide simple visual clues to a user
  //-- of a webpage about various functions
  //--

  //-- First allow more readable names for the ascii icons, instead
  //-- of the 'raw' html entity names. These are like 'aliases' for 
  //-- the HTML entity names.
  //-- 
  $sReturn = 
    preg_replace(
     '#(ascii|text)-icon:\s{0,10}search#im', 
     ' ascii-icon:sect', $sReturn);

  $sReturn = 
    preg_replace(
     '#(ascii|text)-icon:\s{0,10}web-view#im', 
     ' ascii-icon:omega', $sReturn);


  $sReturn = 
    preg_replace(
     '#(ascii|text)-icon:\s{0,10}edit#im', 
     ' ascii-icon:epsilon', $sReturn);

  $sReturn = 
    preg_replace(
     '#(ascii|text)-icon:\s{0,10}folders#im', 
     ' ascii-icon:delta', $sReturn);

  $sReturn = 
    preg_replace(
     '#(ascii|text)-icon:\s{0,10}copy#im', 
     ' ascii-icon:harr', $sReturn);

  $sReturn = 
    preg_replace(
     '#(ascii|text)-icon:\s{0,10}line-numbers#im', 
     ' ascii-icon:Xi', $sReturn);

  //-- Hyperlink this format
  //--    ascii-icon:{html-entity-name} http://www.somewhere.com]
  //-- where the {html-entity-name} is any valid HTML entity with out 
  //-- the & and ; leading and trailing delimiters
  //--
  $sReturn = 
    preg_replace(
     '#(text|ascii)-icon:\s{0,5}(\S{2,20}){0,3}\s+(http://\S{2,})#im', 
     ' <a href="$3" style="text-decoration: none;">'.
     '<big><big><big>&$2;</big></big></big></a>', $sReturn);

  //-- Hyperlink this format
  //--    [http://www.somewhere.com] 
  $sReturn = 
    preg_replace(
     '#\[(http://[^\]]{2,})\]#im', ' <a href="$1">[*]</a>', $sReturn);


  //-- Hyperlink this format
  //--    ascii-icon:{html-entity-name} www.somewhere.com 
  //-- where the {html-entity-name} is any valid HTML entity with out 
  //-- the & and ; leading and trailing delimiters
  //--

  $sReturn = 
    preg_replace(
     '#(text|ascii)-icon:\s{0,5}(\S{2,20}){0,3}\s+(www\.\S{2,})#im', 
     ' <a href="http://$3" style="text-decoration: none;">'.
     '<big><big><big>&$2;</big></big></big></a>', $sReturn);

  //-- Hyperlink this format
  //--    [www.somewhere.com] 
  $sReturn = 
    preg_replace(
     '#\[(www\.[^\]]{2,})\]#im', ' <a href="http://$1">[*]</a>', $sReturn);


  //-- Hyperlink this format
  //--    ascii-icon:{html-entity-name} link://www.somewhere.com
  //-- where the {html-entity-name} is any valid HTML entity with out 
  //-- the & and ; leading and trailing delimiters
  //--

  $sReturn = 
    preg_replace(
     '#(text|ascii)-icon:\s{0,5}(\S{2,20}){0,3}\s+link://(\S+)#im', 
     ' <a href="$3" style="text-decoration: none;">'.
     '<big><big><big>&$2;</big></big></big></a>', $sReturn);

  //-- Hyperlink this format
  //--    [link://www.somewhere.com] 
  $sReturn = 
    preg_replace(
     '#\[link://([^\]]{1,})\]#im', ' <a href="$1">[*]</a>', $sReturn);


  //-- Hyperlink URLs beginning with 'www.' This doesn't work if the 
  //-- URL begins at the first character of the file.
  $sReturn = 
    preg_replace(
     '#\s(www\.\S{2,})#im', ' <a href="http://$1">$1</a>', $sReturn);


  //-- Hyperlink URLs beginning with http:// 
  $sReturn = 
    preg_replace(
     '#\s(http://\S{2,})#im', ' <a href="$1">$1</a>', $sReturn);

  //-- Hyperlink URLs beginning with link://
  //-- The resource referenced is assumed to be on the local web-server 
  $sReturn = 
    preg_replace(
     '#\slink://(\S{1,})#im', ' <a href="$1">$1</a>', $sReturn);



  return $sReturn;
} //-- function fnHyperlinkPlainText
     

//--<--<--<--<--<--<--<--<
?>
                                                                                                                                                        