## Copyright (C) 2001-2012 Paul Kienzle
##
## 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
## <http://www.gnu.org/licenses/>.

## -*- texinfo -*-
## @deftypefn  {Command} {} edit @var{name}
## @deftypefnx {Command} {} edit @var{field} @var{value}
## @deftypefnx {Command} {@var{value} =} edit get @var{field}
## Edit the named function, or change editor settings.
##
## If @code{edit} is called with the name of a file or function as
## its argument it will be opened in a text editor.
##
## @itemize @bullet
## @item
## If the function @var{name} is available in a file on your path and
## that file is modifiable, then it will be edited in place.  If it
## is a system function, then it will first be copied to the directory
## @env{HOME} (see further down) and then edited.
## If no file is found, then the m-file
## variant, ending with ".m", will be considered.  If still no file
## is found, then variants with a leading "@@" and then with both a
## leading "@@" and trailing ".m" will be considered.
##
## @item
## If @var{name} is the name of a function defined in the interpreter but
## not in an m-file, then an m-file will be created in @env{HOME}
## to contain that function along with its current definition.
##
## @item
## If @code{name.cc} is specified, then it will search for @code{name.cc}
## in the path and try to modify it, otherwise it will create a new
## @file{.cc} file in @env{HOME}.  If @var{name} happens to be an
## m-file or interpreter defined function, then the text of that
## function will be inserted into the .cc file as a comment.
##
## @item
## If @var{name.ext} is on your path then it will be edited, otherwise
## the editor will be started with @file{HOME/name.ext} as the
## filename.  If @file{name.ext} is not modifiable, it will be copied to
## @env{HOME} before editing.
##
## @strong{Warning:} You may need to clear name before the new definition
## is available.  If you are editing a .cc file, you will need
## to mkoctfile @file{name.cc} before the definition will be available.
## @end itemize
##
## If @code{edit} is called with @var{field} and @var{value} variables,
## the value of the control field @var{field} will be @var{value}.
## If an output argument is requested and the first argument is @code{get}
## then @code{edit} will return the value of the control field @var{field}.
## If the control field does not exist, edit will return a structure
## containing all fields and values.  Thus, @code{edit get all} returns
## a complete control structure.
## The following control fields are used:
##
## @table @samp
## @item editor
## This is the editor to use to modify the functions.  By default it uses
## Octave's @env{EDITOR} built-in function, which comes from
## @code{getenv("EDITOR")} and defaults to @code{emacs}.  Use @code{%s}
## In place of the function name.  For example,
## @table @samp
## @item [EDITOR, " %s"]
## Use the editor which Octave uses for @code{edit_history}.
##
## @item "xedit %s &"
## pop up simple X11 editor in a separate window
##
## @item "gnudoit -q \"(find-file \\\"%s\\\")\""
## Send it to current Emacs; must have @code{(gnuserv-start)} in @file{.emacs}.
## @end table
##
## See also field 'mode', which controls how the editor is run by Octave.
##
## On Cygwin, you will need to convert the Cygwin path to a Windows
## path if you are using a native Windows editor.  For example:
## @c Set example in small font to prevent overfull line in TeX
##
## @smallexample
## @exdent '"C:/Program Files/Good Editor/Editor.exe" "$(cygpath -wa %s)"'
## @end smallexample
##
## @item home
## This is the location of user local m-files.  Be be sure it is in your
## path.  The default is @file{~/octave}.
##
## @item author
## This is the name to put after the "## Author:" field of new functions.
## By default it guesses from the @code{gecos} field of password database.
##
## @item email
## This is the e-mail address to list after the name in the author field.
## By default it guesses @code{<$LOGNAME@@$HOSTNAME>}, and if @code{$HOSTNAME}
## is not defined it uses @code{uname -n}.  You probably want to override this.
## Be sure to use @code{<user@@host>} as your format.
##
## @item license
## @table @samp
## @item gpl
## GNU General Public License (default).
##
## @item bsd
## BSD-style license without advertising clause.
##
## @item pd
## Public domain.
##
## @item "text"
## Your own default copyright and license.
## @end table
##
## Unless you specify @samp{pd}, edit will prepend the copyright statement
## with "Copyright (C) yyyy Function Author".
##
## @item mode
## This value determines whether the editor should be started in async mode
## (editor is started in the background and Octave continues) or sync mode
## (Octave waits until the editor exits).  Set it to "async" to start the editor
## in async mode.  The default is "sync" (see also "system").
##
## @item editinplace
## Determines whether files should be edited in place, without regard to
## whether they are modifiable or not.  The default is @code{false}.
## @end table
## @end deftypefn

## Author: Paul Kienzle <pkienzle@users.sf.net>

## Original version by Paul Kienzle distributed as free software in the
## public domain.

function ret = edit (file, state)

  ## Pick up globals or default them.

  persistent FUNCTION = struct ("EDITOR", cstrcat (EDITOR (), " %s"),
                                "HOME", fullfile (default_home, "octave"),
                                "AUTHOR", default_user(1),
                                "EMAIL",  [],
                                "LICENSE",  "GPL",
                                "MODE", "async",
                                "EDITINPLACE", false);
  ## Make sure the state variables survive "clear functions".
  mlock;

  if (nargin == 2)
    switch (toupper (file))
    case "EDITOR"
      FUNCTION.EDITOR = state;
    case "HOME"
      if (! isempty (state) && state(1) == "~")
        state = [ default_home, state(2:end) ];
      endif
      FUNCTION.HOME = state;
    case "AUTHOR"
      FUNCTION.AUTHOR = state;
    case "EMAIL"
      FUNCTION.EMAIL = state;
    case "LICENSE"
      FUNCTION.LICENSE = state;
    case "MODE"
      if (strcmp (state, "sync") || strcmp (state, "async"))
        FUNCTION.MODE = state;
      else
        error('edit: expected "edit MODE sync|async"');
      endif
    case "EDITINPLACE"
      if (ischar (state))
        if (strcmpi (state, "true"))
          state = true;
        elseif (strcmpi (state, "false"))
          state = false;
        else
          state = eval (state);
        endif
      endif
      FUNCTION.EDITINPLACE = state;
    case "GET"
      if (isfield (FUNCTION, toupper(state)))
        ret = FUNCTION.(toupper (state));
      else
        ret = FUNCTION;
      endif
    otherwise
      error ('edit: expected "edit EDITOR|HOME|AUTHOR|EMAIL|LICENSE|MODE val"');
    endswitch
    return
  endif

  ## Start the editor without a file if no file is given.
  if (nargin < 1)
    if (exist (FUNCTION.HOME, "dir") == 7 && (isunix () || ! ispc ()))
      system (cstrcat ("cd \"", FUNCTION.HOME, "\" ; ",
                      sprintf (FUNCTION.EDITOR, "")),
              [], FUNCTION.MODE);
    else
      system (sprintf (FUNCTION.EDITOR,""), [], FUNCTION.MODE);
    endif
    return;
  endif

  ## Check whether the user is trying to edit a builtin of compiled function.
  switch (exist (file))
    case {3, 5}
      error ("edit: unable to edit a built-in or compiled function");
  endswitch

  ## Checks for whether the file is
  ## absolute or relative should be handled inside file_in_loadpath.
  ## That way, it will be possible to look up files correctly given
  ## partial path information.  For example, you should be able to
  ## edit a particular overloaded function by doing any one of
  ##
  ##   edit classname/foo
  ##   edit classname/foo.m
  ##   edit @classname/foo
  ##   edit @classname/foo.m
  ##
  ## This functionality is needed for other functions as well (at least
  ## help and type; there may be more).  So the place to fix that is in
  ## file_in_loadpath, possibly with some help from the load_path class.

  ## The code below includes a portion that serves as a place-holder for
  ## the changes suggested above.

  ## Create list of explicit and implicit file names.
  filelist = {file};
  ## If file has no extension, add file.m and file.cc to the list.
  idx = rindex (file, ".");
  if (idx == 0)
    ## Create the list of files to look for
    filelist = {file};
    if (isempty (regexp (file, '\.m$')))
      ## No ".m" at the end of the file, add to the list.
      filelist{end+1} = cat (2, file, ".m");
    endif
    if (isempty (regexp (file, '\.cc$')))
      ## No ".cc" at the end of the file, add to the list.
      filelist{end+1} = cat (2, file, ".cc");
    endif
  endif

  ## If the file includes a path, it may be an overloaded function.
  if (! strcmp (file, "@") && index (file, filesep))
    ## No "@" at the beginning of the file, add to the list.
    numfiles = numel(filelist);
    for n = 1:numfiles
      filelist{n+numfiles} = cat (2, "@", filelist{n});
    endfor
  endif

  ## Search the entire path for the 1st instance of a file in the list.
  fileandpath = "";
  for n = 1:numel(filelist)
    filetoedit = file_in_path (path, filelist{n});
    if (! isempty (filetoedit))
      ## The path is explicitly included.
      fileandpath = filetoedit;
      break;
    endif
  endfor

  if (! isempty (fileandpath))
    ## If the file exists, then edit it.
    if (FUNCTION.EDITINPLACE)
      ## Edit in place even if it is protected.
      system (sprintf (FUNCTION.EDITOR, cstrcat ("\"", fileandpath, "\"")),
              [], FUNCTION.MODE);
      return;
    else
      ## If the file is modifiable in place then edit it, otherwise make
      ## a copy in HOME and then edit it.
      fid = fopen (fileandpath, "r+t");
      if (fid < 0)
        from = fileandpath;
        fileandpath = cstrcat (FUNCTION.HOME, from (rindex (from, filesep):end));
        [status, msg] = copyfile (from, fileandpath, 1);
        if (status == 0)
          error (msg);
        endif
      else
        fclose (fid);
      endif
      system (sprintf (FUNCTION.EDITOR, cstrcat ("\"", fileandpath, "\"")),
              [], FUNCTION.MODE);
      return;
    endif
  endif

  ## If editing a new file that is neither a m-file or an oct-file,
  ## just edit it.
  fileandpath = file;
  idx = rindex (file, ".");
  name = file(1:idx-1);
  ext = file(idx+1:end);
  switch (ext)
    case {"cc", "m"}
      0;
    otherwise
      system (sprintf (FUNCTION.EDITOR, cstrcat ("\"", fileandpath, "\"")),
              [], FUNCTION.MODE);
      return;
  endswitch

  ## The file doesn't exist in path so create it, put in the function
  ## template and edit it.

  ## Guess the email name if it was not given.
  if (isempty (FUNCTION.EMAIL))
    host = getenv("HOSTNAME");
    if (isempty (host) && ispc ())
      host = getenv ("COMPUTERNAME");
    endif
    if (isempty (host))
      [status, host] = system ("uname -n");
      ## trim newline from end of hostname
      if (! isempty (host))
        host = host(1:end-1);
      endif
    endif
    if (isempty (host))
      FUNCTION.EMAIL = " ";
    else
      FUNCTION.EMAIL = cstrcat ("<", default_user(0), "@", host, ">");
    endif
  endif

  ## Fill in the revision string.
  now = localtime (time);
  revs = cstrcat ("Created: ", strftime ("%Y-%m-%d", now));

  ## Fill in the copyright string.
  copyright = cstrcat (strftime ("Copyright (C) %Y ", now), FUNCTION.AUTHOR);

  ## Fill in the author tag field.
  author = cstrcat ("Author: ", FUNCTION.AUTHOR, " ", FUNCTION.EMAIL);

  ## Fill in the header.
  uclicense = toupper (FUNCTION.LICENSE);
  switch (uclicense)
    case "GPL"
      head = cstrcat (copyright, "\n\n", "\
This program is free software; you can redistribute it and/or modify\n\
it under the terms of the GNU General Public License as published by\n\
the Free Software Foundation; either version 3 of the License, or\n\
(at your option) any later version.\n\
\n\
This program is distributed in the hope that it will be useful,\n\
but WITHOUT ANY WARRANTY; without even the implied warranty of\n\
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the\n\
GNU General Public License for more details.\n\
\n\
You should have received a copy of the GNU General Public License\n\
along with Octave; see the file COPYING.  If not, see\n\
<http://www.gnu.org/licenses/>.\
");
      tail = cstrcat (author, "\n", revs);

    case "BSD"
      head = cstrcat (copyright, "\n\n", "\
This program is free software; redistribution and use in source and\n\
binary forms, with or without modification, are permitted provided that\n\
the following conditions are met:\n\
\n\
   1.Redistributions of source code must retain the above copyright\n\
     notice, this list of conditions and the following disclaimer.\n\
   2.Redistributions in binary form must reproduce the above copyright\n\
     notice, this list of conditions and the following disclaimer in the\n\
     documentation and/or other materials provided with the distribution.\n\
\n\
THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND\n\
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE\n\
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE\n\
ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE\n\
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL\n\
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS\n\
OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)\n\
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT\n\
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY\n\
OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF\n\
SUCH DAMAGE.\
");
      tail = cstrcat (author, "\n", revs);

    case "PD"
      head = "";
      tail = cstrcat (author, "\n", revs, "\n\n",
                     "This program is granted to the public domain.");

    otherwise
      head = "";
      tail = cstrcat (copyright, "\n\n", FUNCTION.LICENSE, "\n",
                     author, "\n", revs);
  endswitch

  ## Generate the function template.
  exists = exist (name);
  switch (ext)
    case {"cc", "C", "cpp"}
      if (isempty (head))
        comment = cstrcat ("/*\n", tail, "\n\n*/\n\n");
      else
        comment = cstrcat ("/*\n", head, "\n\n", tail, "\n\n*/\n\n");
      endif
      ## If we are shadowing an m-file, paste the code for the m-file.
      if (any (exists == [2, 103]))
        code = cstrcat ("\\ ", strrep (type (name), "\n", "\n// "));
      else
        code = " ";
      endif
      body = cstrcat ("#include <octave/oct.h>\n\n",
                     "DEFUN_DLD(", name, ",args,nargout,\"\\\n",
                     name, "\\n\\\n\")\n{\n",
                     "  octave_value_list retval;\n",
                     "  int nargin = args.length();\n\n",
                     code, "\n  return retval;\n}\n");

      text = cstrcat (comment, body);
    case "m"
      ## If we are editing a function defined on the fly, paste the
      ## code.
      if (any (exists == [2, 103]))
        body = type (name);
      else
        body = cstrcat ("function [ ret ] = ", name, " ()\n\nendfunction\n");
      endif
      if (isempty (head))
        comment = cstrcat ("## ", name, "\n\n",
                          "## ", strrep (tail, "\n", "\n## "), "\n\n");
      else
        comment = cstrcat ("## ", strrep(head,"\n","\n## "), "\n\n", ...
                          "## ", name, "\n\n", ...
                          "## ", strrep (tail, "\n", "\n## "), "\n\n");
      endif
      text = cstrcat (comment, body);
  endswitch

  ## Write the initial file (if there is anything to write)
  fid = fopen (fileandpath, "wt");
  if (fid < 0)
    error ("edit: could not create %s", fileandpath);
  endif
  fputs (fid, text);
  fclose (fid);

  ## Finally we are ready to edit it!
  system (sprintf (FUNCTION.EDITOR, cstrcat ("\"", fileandpath, "\"")),
          [], FUNCTION.MODE);

endfunction

function ret = default_home ()

  ret = getenv ("HOME");
  if (isempty (ret))
    ret = glob ("~");
    if (! isempty (ret))
      ret = ret{1};
    else
      ret = "";
    endif
  endif

endfunction

## Return the name associated with the current user ID.
##
## If LONG_FORM is 1, return the full name.  This will be the
## default author.  Otherwise return the login name.
## login@host will be the default email address.

function ret = default_user (long_form)

  ent = getpwuid (getuid);
  if (! isstruct (ent))
    ret = getenv ("USER");
    if (isempty (ret))
      ret = getenv ("USERNAME");
    endif
  elseif (long_form)
    ret = ent.gecos;
    pos = strfind (ret, ",");
    if (! isempty (pos))
      ret = ret(1:pos-1);
    endif
  else
    ret = ent.name;
  endif

endfunction

%!test
%! s.editor = edit ("get", "editor");
%! s.home = edit ("get", "home");
%! s.author = edit ("get", "author");
%! s.email = edit ("get", "email");
%! s.license = edit ("get", "license");
%! s.editinplace = edit ("get", "editinplace");
%! s.mode = edit ("get", "mode");
%! edit editor none
%! edit home none
%! edit author none
%! edit email none
%! edit license none
%! edit ("editinplace", !s.editinplace)
%! if (s.mode(1) == "a")
%!   edit mode sync
%! else
%!   edit mode async
%! endif
%! edit ("editor", s.editor);
%! edit ("home", s.home);
%! edit ("author", s.author);
%! edit ("email", s.email);
%! edit ("license", s.license);
%! edit ("editinplace", s.editinplace);
%! edit ("mode", s.mode);
%! assert (edit ("get", "editor"), s.editor);
%! assert (edit ("get", "home"), s.home);
%! assert (edit ("get", "author"), s.author);
%! assert (edit ("get", "email"), s.email);
%! assert (edit ("get", "license"), s.license);
%! assert (edit ("get", "editinplace"), s.editinplace);
%! assert (edit ("get", "mode"), s.mode);