changeset 27144:3de14d9a2303

Implement new function "web" to open the system web browser. * NEWS: Announce new function. * scripts/web/web.m: Add new function. * scripts/web/module.mk: Add new function to build system. * scripts/help/__unimplemented__.m: Remove entry `web`.
author Kai T. Ohlhus <k.ohlhus@gmail.com>
date Tue, 04 Jun 2019 22:17:42 +0200
parents 64ff1053ffbf
children f8e4e04722ee
files NEWS scripts/help/__unimplemented__.m scripts/web/module.mk scripts/web/web.m
diffstat 4 files changed, 120 insertions(+), 1 deletions(-) [+]
line wrap: on
line diff
--- a/NEWS	Tue Jun 04 22:07:45 2019 +0200
+++ b/NEWS	Tue Jun 04 22:17:42 2019 +0200
@@ -52,6 +52,8 @@
   major feature is the support for cookies to enable RESTful
   communication with the web service.
 
+  Additionally, the system web browser can be opened by the `web` function.
+
 - The interpreter now supports handles to nested functions.
 
 - The graphics properties `"LineWidth"` and `"MarkerSize"` are now
@@ -64,6 +66,7 @@
 - `lightangle`
 - `newline`
 - `verLessThan`
+- `web`
 
 
 ### Deprecated functions and properties
--- a/scripts/help/__unimplemented__.m	Tue Jun 04 22:07:45 2019 +0200
+++ b/scripts/help/__unimplemented__.m	Tue Jun 04 22:17:42 2019 +0200
@@ -1336,7 +1336,6 @@
   "volume",
   "volumebounds",
   "voronoiDiagram",
-  "web",
   "weboptions",
   "webread",
   "websave",
--- a/scripts/web/module.mk	Tue Jun 04 22:07:45 2019 +0200
+++ b/scripts/web/module.mk	Tue Jun 04 22:17:42 2019 +0200
@@ -1,6 +1,7 @@
 FCN_FILE_DIRS += scripts/web
 
 %canon_reldir%_FCN_FILES = \
+  %reldir%/web.m \
   %reldir%/weboptions.m \
   %reldir%/webread.m \
   %reldir%/webwrite.m
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/scripts/web/web.m	Tue Jun 04 22:17:42 2019 +0200
@@ -0,0 +1,116 @@
+## Copyright (C) 2017-2019 Kai T. Ohlhus <k.ohlhus@gmail.com>
+##
+## This file is part of Octave.
+##
+## Octave is free software: you can redistribute it and/or modify it
+## under the terms of the GNU General Public License as published by
+## the Free Software Foundation, either version 3 of the License, or
+## (at your option) any later version.
+##
+## Octave 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 General Public License for more details.
+##
+## You should have received a copy of the GNU General Public License
+## along with Octave; see the file COPYING.  If not, see
+## <https://www.gnu.org/licenses/>.
+
+## -*- texinfo -*-
+## @deftypefn  {} {@var{status} =} web ()
+## @deftypefnx {} {@var{status} =} web (@var{url})
+## @deftypefnx {} {@var{status} =} web (@var{url}, @var{option})
+## @deftypefnx {} {@var{status} =} web (@var{url}, @var{option1}, @dots{}, @var{optionN})
+## @deftypefnx {} {[@var{status}, @var{h}] =} web (@dots{})
+## @deftypefnx {} {[@var{status}, @var{h}, @var{url}] =} web (@dots{})
+##
+## Open @var{url} in the default system web browser.
+##
+## With no arguments given, the address @code{https://www.octave.org} is
+## opened.
+##
+## Additional options can be passed due to Matlab compatibility, but they have
+## no effect on the system web browser:
+##
+## @itemize @bullet
+## @item
+## @samp{-browser} Open @var{url} in the default system browser.
+##
+## @item
+## @samp{-new} No effect on the system browser.
+##
+## @item
+## @samp{-noaddressbox} No effect on the system browser.
+##
+## @item
+## @samp{-notoolbar} No effect on the system browser.
+##
+## @end itemize
+##
+## The return value @var{status} has one of the values:
+##
+## @itemize @bullet
+## @item
+## @samp{0} Found and opened system browser successfully.
+##
+## @item
+## @samp{1} Cannot find the system browser.
+##
+## @item
+## @samp{2} System browser found, but an error occurred.
+##
+## @end itemize
+##
+## The return values @var{handle} and @var{url} are currently unimplemented
+## but given for compatibility.
+##
+## @seealso{weboptions, webread, webwrite, websave, urlread, urlwrite}
+## @end deftypefn
+
+function [status, h, url] = web (url, varargin)
+
+  if (nargin == 0)
+    url = "https://www.octave.org";
+  endif
+
+  if (! (ischar (url) && isvector (url)))
+    error ("web: URL must be a string");
+  endif
+
+  for i = 1:length (varargin)
+    validatestring (varargin{i}, ...
+      {"-browser", "-new", "-noaddressbox", "-notoolbar"});
+  endfor
+
+  ## Store text after "text://" to temporary file and open it.
+  if (strncmpi (url, "text://", 7))
+    fname = [tempname() ".html"];
+    fid = fopen (fname, "w");
+    if (fid < 0)
+      error ("web: could not open temporary file for text:// content");
+    endif
+    fprintf (fid, "%s", url(8:end));
+    fclose (fid);
+    url = ["file://", fname];
+  endif
+
+  status = __open_with_system_app__ (url);
+  if (status == 1)
+    status = 0;
+  else
+    status = 2;
+  endif
+
+  h = [];  ## Empty handle, as we cannot control an external browser.
+
+  ## For Matlab compatibility.
+  if (any (strcmp (varargin, "-browser")))
+    url = [];
+  endif
+
+endfunction
+
+%!error <URL must be a string> web ([])
+%!error <URL must be a string> web ('')
+%!error <'-invalid_Option' does not match>
+%!  web ("https://www.octave.org", "-invalid_Option")