// Software    : Scilab >= 5.5
// Function    : browseURL()
// License     : CeCILL-C : http://www.cecill.info/licences
// Copyright(C): Samuel GOUGEON - 2015
// Version     : 1.0
// Date        : 2015-09-12
// Release     : http://fileexchange.scilab.org/toolboxes/453000
//
// History     :
//  2015-09-12 1.0: First release on FileExchange
//
// DISCLAIMER: This macro is provided as is, with NO WARRANTY of any kind.
//  Use it to your own risks, awareness, and responsability.

function browseURL(url)
//
// Opens one or several URLs in the default or prefered web browser
//
// SYNTAX
// ------
// browseURL      // Displays this help
// browseURL(url)
// 
// PARAMETERS
// ----------
// url : single or vector of full URLs (text). If no protocol is specified,
//       'http://' is prepended to url.
// 
// DESCRIPTION
// -----------
// browseURL() 
// * looks for a web browser set in Scilab Preferences, or a default one,
// * opens it -- or new tab(s) in the current browser session --, 
// * and displays the given URL(s), provided that an internet connexion is alive
//
// WARNING: 
//  * All literal double quotes included in URLs must priorly be encoded as %22
//  * IE will open a new window for each URL, instead of a new tab.
//
// NOTE: browseURL() has been tested with Firefox, Chrome, IE and Safari 
//       under MSWindow, and with Firefow under Linux.
//
// NOTE: No portable equivalent options common to main web browsers have been 
//  found. Therefore, no option is proposed through browseURL.
//  For information only, main browser-specific command line options are 
//   presented hereafter for major browsers:
//  * FIREFOX: -new-windows -new-tab -height 600 -width 600 -search term 
//             -foreground (bring it to the FG)
//  * CHROME:  --user-data-dir
//  * SAFARI: no options found.
//  * IE: -k : full screen, no address bar, no navigation bar, no buttons
//  * EDGE: First release to come.
//
// SEE ALSO
// --------
// getURL : Download an URL (HTTP, HTTPS, FTP...)
// preferences: Set interactively Scilab's web preferences
//
// FEEDBACK
// --------
//  Comments, scoring and bug reports about browseURL() are welcome on
//  http://fileexchange.scilab.org/toolboxes/453000#new_comment
//  Feedbacks from Linux and MacOS users are encouraged.
//
// EXAMPLES
// --------
// browseURL("http://www.scilab.org")
// browseURL(['atoms.scilab.org' 'http://help.scilab.org'])
// browseURL('fileexchange.scilab.org/toolboxes/360000#files')
// browseURL('fileexchange.scilab.org/?order=authors&direction=DESC#advanced')
//
    fname = "browseURL"
    if argn(2)==0
        head_comments(fname)
        return
    end
    
    if url==[]
        return
    end

    if type(url)~=10
        msg = _("%s: Wrong type for input argument #%d: matrix of text expected.\n")
        error(msprintf(msg, fname))
    end

    // By default, "http://" is used:
    k = setdiff(1:size(url,"*"), grep(convstr(url),"://"))
    if k~=[]
        url(k) = "http://"+url(k)
    end
    
    url = """"+url(:)+""""
    pref = getPreferencesValue("//web/body/web",["default-browser" "command-browser"])

    // Default browser
    appli = []
    if getos()=="Windows"
        appli = findfileassociation(".html")
        if appli~=[]
            appli = """"+appli+""""
        end
    elseif getos()=="Linux"
        appli = "xdg-open "
    elseif getos()=="Darwin"
        appli = "open "
    else
        //........ Other OSes
    end

    // Chosen browser
    if (convstr(pref(1))=="false" & pref(2)~="")
        appli = pref(2)
    end

    // Protection of spaces in appli's path
    if appli~=[] & and(part(appli,1)~=["""" '''']) & grep(appli, " ")~=[]
        appli = """"+appli+""""
    end

    // IE <= 11.0 and Safari <= 5.1.7 do not support multiple URLs in a once: 
    //  Special handlings
    if getos()=="Windows" & grep(convstr(appli), ["iexplore.exe" "safari.exe"])~=[]
        cmd = "start """" "+appli+" "+url
        if grep(convstr(appli), "safari.exe")~=[]
            cmd = [cmd' ; emptystr(cmd')+"sleep"] 
            cmd = cmd(:)                // Safari needs a sleep to open next tab
        end
    elseif appli~=[]
        if getos()=="Windows"
            cmd = "start """" "+appli+" "+strcat(url, " ")
        else
            cmd = appli+strcat(url, " ")+" &"
        end
    else
        msg = _("%s: No web browser available.\n")
        error(msprintf(msg, fname))
    end

    // Calling the browser
    for c = cmd'
        if c~="sleep"
            host(c)
        else
            sleep(1000)
        end
    end
endfunction

