Merge branch 'feature/request-sf83' into develop

Implements SourceForge feature request #83 -
https://sourceforge.net/p/codesnip/feature-requests/83/

Author: DelphiDabbler

Src/FmMain.pas

@@ -1402,8 +1402,8 @@ procedure TMainForm.InitForm;
     // Set window caption
     Application.Title := TAppInfo.ProgramCaption;
     Caption := TAppInfo.ProgramCaption;
-    if TWebInfo.UsingLocalHost then
-      Caption := Caption + ' [' + TWebInfo.LocalHost + ']';
+    if TWebInfo.UsingTestServer then
+      Caption := Caption + ' [' + TWebInfo.TestServerHost + ']';
 
     // Restore window settings
     fWindowSettings := TMainWindowSettings.CreateStandAlone(Self); // auto-freed

Src/Web.UInfo.pas

@@ -3,7 +3,7 @@
  * v. 2.0. If a copy of the MPL was not distributed with this file, You can
  * obtain one at http://mozilla.org/MPL/2.0/
  *
- * Copyright (C) 2009-2014, Peter Johnson (www.delphidabbler.com).
+ * Copyright (C) 2009-2016, Peter Johnson (www.delphidabbler.com).
  *
  * $Rev$
  * $Date$
@@ -35,12 +35,13 @@   TWebServiceInfo = record
     ///  <summary>MIME type of media used by web service.</summary>
     MediaType: string;
     ///  <summary>Constructs a record with given field values.</summary>
-    ///  <param name="AScriptURLTplt">string [in] Template for web service's
-    ///  URI.</param>
-    ///  <param name="AUserAgent">string [in] User agent to use when accessing
-    ///  web service.</param>
-    ///  <param name="AMediaType">string [in] Optional. Media type used by web
-    ///  service.</param>
+    ///  <param name="AScriptURLTplt"><c>string</c> [in] Template for web
+    ///  service's URI. Must contain a single '%s' placeholder for web host.
+    ///  </param>
+    ///  <param name="AUserAgent"><c>string</c> [in] User agent to use when
+    ///  accessing web service.</param>
+    ///  <param name="AMediaType"><c>string</c> [in] Optional. Media type used
+    ///  by web service.</param>
     constructor Create(const AScriptURLTplt, AUserAgent: string;
       const AMediaType: string = 'text/*');
   end;
@@ -67,25 +68,31 @@   TWebProxyInfo = record
   TWebInfo = class(TNoConstructObject)
   strict private
     const
-      ///  <summary>Remote DelphiDabbler web server.</summary>
-      RemoteHost = 'delphidabbler.com';
+      ///  <summary>Name of server that hosts tested and released web services
+      ///  that are used by CodeSnip.</summary>
+      ///  <remarks>There is also a test server that can be used by CodeSnip
+      ///  where new and updated web services are tested - see
+      ///  <c>TestServerHost</c> below.</remarks>
+      ProductionServerHost = 'delphidabbler.com';
       ///  <summary>URL of DelphiDabbler website.</summary>
-      WebsiteURL = 'http://' + RemoteHost;
+      WebsiteURL = 'http://' + ProductionServerHost;
       ///  <summary>Template for URL of Code Snippets news feed.</summary>
       ///  <remarks>'%d' placeholder must be replaced by the required number of
-      ///  days into the past the news feed should cover.</remarks>
+      ///  days into the past the news feed should cover. Passing <c>0</c> as
+      ///  the number of days results in all news items being returned.
+      ///  </remarks>
       NewsFeedTplt = WebSiteURL + '/feeds/site-news-feed?id=codesnip&days=%d';
   strict private
-    ///  <summary>Returns the name of the host server to be used.</summary>
-    ///  <remarks>This is the remote web server unless the '-localhost# switch
-    ///  was passed on the command line when localhost server is returned.
-    ///  </remarks>
+    ///  <summary>Returns the name of the server that hosts web services that
+    ///  are used by CodeSnip.</summary>
+    ///  <remarks>By default is the production server (as specified by the
+    ///  <c>ProductionServerHost</c> constant). CodeSnip will instead use a
+    ///  test server (as returned by the <c>TestServerHost</c> method) if the
+    ///  name and port of the test server is passed on the command line via the
+    ///  <c>--test-server</c> command line option.</remarks>
     class function Host: string;
   public
     const
-      ///  <summary>Local web server.</summary>
-      ///  <remarks>Used for test purposes.</remarks>
-      LocalHost = 'localhost:8080';
       ///  <summary>URL of home page on DelphiDabbler website.</summary>
       DelphiDabblerHomeURL = WebsiteURL + '/';
       ///  <summary>URL of home page of the CodeSnip project.</summary>
@@ -94,37 +101,59 @@   TWebInfo = class(TNoConstructObject)
       DatabaseURL = WebsiteURL + '/url/csdb';
       ///  <summary>URL used to make donations towards the CodeSnip project.
       ///  </summary>
-      ///  <summary>This URL redirects to the correct page on PayPal.</summary>
+      ///  <remarks>This URL redirects to the correct page on PayPal.</remarks>
       DonateURL = WebsiteURL + '/url/donate-cs';
       ///  <summary>URL used to view and report CodeSnip bugs.</summary>
+      ///  <remarks>This URL will redirect to the actual bug tracker which may
+      ///  be on an external site such as SourceForge or GitHub.</remarks>
       BugTrackerURL = WebsiteURL + '/url/codesnip-bugs';
       ///  <summary>URL of CodeSnip's FAQ web page.</summary>
+      ///  <remarks>This URL will redirect to the FAQ location which may be on
+      ///  an external site such as GitHub or SourceForge.</remarks>
       FAQsURL = WebsiteURL + '/url/codesnip-faq';
   public
+    ///  <summary>Returns the name of the server that hosts web services used by
+    ///  CodeSnip when under testing. This server receives updated web services
+    ///  before they are released to the production server.</summary>
+    ///  <remarks>
+    ///  <para>The name of this server must be passed on the command line via
+    ///  the <c>--test-server</c> option. If this option is not specified then
+    ///  <c>TestServerHost</c> returns the empty string.</para>
+    ///  <para>The format of the command line switch is
+    ///  <c>--test-server=server-name</c> or
+    ///  <c>--test-server=server-name:port</c> where <c>server-name</c> is the
+    ///  name of the test server and <c>port</c> is the port number it is
+    ///  operating on, for example <c>--test-server=localhost:8080</c> or
+    ///  <c>--test-server=test.delphidabbler.com</c>. The
+    ///  port number and its preceding ':' character can be omitted if the
+    ///  server is on port 80.</para>
+    ///  <para>The server must be using the <c>http://</c> protocol.</para>
+    ///  </remarks>
+    class function TestServerHost: string;
     ///  <summary>Builds the URL of the CodeSnip news feed.</summary>
-    ///  <param name="Age">Word [in] Maximum age, in days, of news items to be
-    ///  included in the feed.</param>
-    ///  <returns>string. Required URL.</returns>
+    ///  <param name="Age"><c>Word</c> [in] Maximum age, in days, of news items
+    ///  to be included in the feed.</param>
+    ///  <returns><c>string</c>. Required URL.</returns>
     class function NewsFeedURL(const Age: Word): string;
     ///  <summary>Builds the URL of a web service.</summary>
-    ///  <param name="URLTplt">string. [in] Template of URL of web service
-    ///  script. Must contain a '%s' placeholder for host name.</param>
-    ///  <returns>string. Required URL.</returns>
+    ///  <param name="URLTplt"><c>string</c>. [in] Template of URL of web
+    ///  service script. Must contain a '%s' placeholder for host name.</param>
+    ///  <returns><c>string</c>. Required URL.</returns>
     class function WebServiceURL(const URLTplt: string): string;
     ///  <summary>Gets information about any required web proxy.</summary>
     ///  <remarks>The web proxy information is read from settings.</remarks>
     class function WebProxyInfo: TWebProxyInfo;
-    ///  <summary>Checks if the program is using the web server on localhost.
-    ///  </summary>
-    ///  <returns>Boolean. True if localhost is being used, False if the remote,
-    ///  production, server is being used.</returns>
+    ///  <summary>Checks if the program is using a test web server.</summary>
+    ///  <returns><c>Boolean</c>. <c>True</c> if a test web server is being
+    ///  used, <c>False</c> if the production web server is being used.
+    ///  </returns>
     ///  <remarks>
-    ///  <para>True is returned iff the '-localhost' switch was passed on the
-    ///  command line.</para>
-    ///  <para>Localhost should only be used by developers with access to a
-    ///  suitable test server running as 'locahost'.</para>
+    ///  <para><c>True</c> is returned iff a valid <c>--test-server</c> command
+    ///  line option was supplied.</para>
+    ///  <para><c>--test-server</c> should only be specified by developers with
+    ///  access to a suitable test server.</para>
     ///  </remarks>
-    class function UsingLocalHost: Boolean;
+    class function UsingTestServer: Boolean;
   end;
 
 
@@ -142,20 +171,43 @@ implementation
 
 class function TWebInfo.Host: string;
 begin
-  if UsingLocalHost then
-    Result := LocalHost
+  if UsingTestServer then
+    Result := TestServerHost
   else
-    Result := RemoteHost;
+    Result := ProductionServerHost;
 end;
 
 class function TWebInfo.NewsFeedURL(const Age: Word): string;
 begin
   Result := Format(NewsFeedTplt, [Age]);
 end;
 
-class function TWebInfo.UsingLocalHost: Boolean;
+class function TWebInfo.TestServerHost: string;
+const
+  TestServerSwitch = '--test-server';
+  Separator = '=';
+var
+  Idx: Integer;
+  ParamName: string;
+  ParamValue: string;
+begin
+  for Idx := 1 to ParamCount do
+  begin
+    if not StrContainsStr(Separator, ParamStr(Idx)) then
+      Continue;
+    StrSplit(ParamStr(Idx), Separator, ParamName, ParamValue);
+    if not StrSameStr(TestServerSwitch, ParamName) then
+      Continue;
+    if ParamValue = EmptyStr then
+      Continue;
+    Exit(ParamValue);
+  end;
+  Result := EmptyStr;
+end;
+
+class function TWebInfo.UsingTestServer: Boolean;
 begin
-  Result := FindCmdLineSwitch('localhost', True);
+  Result := TestServerHost <> EmptyStr;
 end;
 
 class function TWebInfo.WebProxyInfo: TWebProxyInfo;