/* helpfile.c - GnuPG's helpfile feature

 *  Copyright (C) 2007 Free Software Foundation, Inc.

 *  Copyright (C) 2011,2012, 2025 g10 Code GmbH

 *

 * This file is part of GnuPG.

 *

 * This file is free software; you can redistribute it and/or modify

 * it under the terms of either

 *

 *   - the GNU Lesser General Public License as published by the Free

 *     Software Foundation; either version 3 of the License, or (at

 *     your option) any later version.

 *

 * or

 *

 *   - the GNU General Public License as published by the Free

 *     Software Foundation; either version 2 of the License, or (at

 *     your option) any later version.

 *

 * or both in parallel, as here.

 *

 * This file 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 this program; if not, see <https://www.gnu.org/licenses/>.

 * SPDX-License-Identifier: (LGPL-3.0-or-later OR GPL-2.0-or-later)

 */

#include <config.h>

#include <stdlib.h>

#include "util.h"

#include "i18n.h"

#include "membuf.h"

/* Try to find KEY in the file FNAME.  */

static char *

findkey_fname (const char *key, const char *fname, unsigned int flags)

{

  gpg_error_t err = 0;

  estream_t fp;

  int lnr = 0;

  int c;

  char *p, line[256];

  int in_item = 0;

  membuf_t mb = MEMBUF_ZERO;

  fp = es_fopen (fname, "r");

  if (!fp)

    {

      if (errno != ENOENT)

        {

          err = gpg_error_from_syserror ();

          log_error (_("can't open '%s': %s\n"), fname, gpg_strerror (err));

        }

      return NULL;

    }

  while (es_fgets (line, DIM(line)-1, fp))

    {

      lnr++;

      if (!*line || line[strlen(line)-1] != '\n')

        {

          /* Eat until end of line. */

          while ((c = es_getc (fp)) != EOF && c != '\n')

            ;

          err = gpg_error (*line? GPG_ERR_LINE_TOO_LONG

                           : GPG_ERR_INCOMPLETE_LINE);

          log_error (_("file '%s', line %d: %s\n"),

                     fname, lnr, gpg_strerror (err));

        }

      else

        line[strlen(line)-1] = 0; /* Chop the LF. */

    again:

      if (!in_item)

        {

          /* Allow for empty lines and spaces while not in an item. */

          for (p=line; spacep (p); p++)

            ;

          if (!*p || *p == '#')

            continue;

          if (*line != '.' || spacep(line+1))

            {

              log_info (_("file '%s', line %d: %s\n"),

                        fname, lnr, _("ignoring garbage line"));

              continue;

            }

          trim_trailing_spaces (line);

          in_item = 1;

          if (!strcmp (line+1, key))

            {

              /* Found.  Start collecting.  */

              init_membuf (&mb, 1024);

            }

          continue;

        }

      /* If in an item only allow for comments in the first column

         and provide ". " as an escape sequence to allow for

         leading dots and hash marks in the actual text.  */

      if (*line == '#')

        continue;

      if (*line == '.')

        {

          if (spacep(line+1))

            p = line + 2;

          else

            {

              trim_trailing_spaces (line);

              in_item = 0;

              if (is_membuf_ready (&mb))

                break;        /* Yep, found and collected the item.  */

              if (!line[1])

                continue;     /* Just an end of text dot. */

              goto again;     /* A new key line.  */

            }

        }

      else

        p = line;

      if (is_membuf_ready (&mb))

        {

          put_membuf_str (&mb, p);

          if ((flags & GET_TEMPLATE_CRLF))

            put_membuf (&mb, "\r\n", 2);

          else

            put_membuf (&mb, "\n", 1);

        }

    }

  if ( !err && es_ferror (fp) )

    {

      err = gpg_error_from_syserror ();

      log_error (_("error reading '%s', line %d: %s\n"),

                 fname, lnr, gpg_strerror (err));

    }

  es_fclose (fp);

  if (is_membuf_ready (&mb))

    {

      /* We have collected something.  */

      if (err)

        {

          xfree (get_membuf (&mb, NULL));

          return NULL;

        }

      else

        {

          put_membuf (&mb, "", 1);  /* Terminate string.  */

          return get_membuf (&mb, NULL);

        }

    }

  else

    return NULL;

}

/* Try the help files depending on the locale.  */

static char *

findkey_locale (const char *domain, const char *key, const char *locname,

                const char *dirname, unsigned int flags)

{

  const char *s;

  char *fname, *ext, *p;

  char *result;

  fname = xtrymalloc (strlen (dirname) + 2

                      + strlen (domain) + strlen (locname) + 4 + 1);

  if (!fname)

    return NULL;

  ext = stpcpy (stpcpy (stpcpy (stpcpy (fname, dirname), "/"), domain), ".");

  /* Search with locale name and territory.  ("help.LL_TT.txt") */

  if (strchr (locname, '_'))

    {

      strcpy (stpcpy (ext, locname), ".txt");

      result = findkey_fname (key, fname, flags);

    }

  else

    result = NULL;  /* No territory.  */

  if (!result)

    {

      /* Search with just the locale name - if any. ("help.LL.txt") */

      if (*locname)

        {

          for (p=ext, s=locname; *s && *s != '_';)

            *p++ = *s++;

          strcpy (p, ".txt");

          result = findkey_fname (key, fname, flags);

        }

      else

        result = NULL;

    }

  if (!result && (!(flags & GET_TEMPLATE_CURRENT_LOCALE) || !*locname))

    {

      /* Last try: Search in file without any locale info.  ("help.txt") */

      strcpy (ext, "txt");

      result = findkey_fname (key, fname, flags);

    }

  xfree (fname);

  return result;

}

/* Return a malloced text as identified by KEY.  The system takes

   the string from an UTF-8 encoded file to be created by an

   administrator or as distributed with GnuPG.  On a GNU or Unix

   system the entry is searched in these files:

     /etc/gnupg/<domain>.<LL>.txt

     /etc/gnupg/<domain>.txt

     /usr/share/gnupg/<domain>.<LL>.txt

     /usr/share/gnupg/<domain>.txt

   The <domain> is either "help" or any other domain like "mail-tube".

   Here <LL> denotes the two digit language code of the current

   locale.  If the flag bit GET_TEMPLATE_CURRENT_LOCALE is set, the

   function won't fallback to the english valiant ("<domain>.txt")

   unless that locale has been requested.

   The template file needs to be encoded in UTF-8, lines with a '#' in the

   first column are comment lines and entirely ignored.  Help keys are

   identified by a key consisting of a single word with a single dot

   as the first character.  All key lines listed without any

   intervening lines (except for comment lines) lead to the same help

   text.  Lines following the key lines make up the actual template texts.

*/

char *

gnupg_get_template (const char *domain, const char *key, unsigned int flags,

                    const char *override_locale)

{

  static const char *locname_buffer;

  const char *locname;

  char *result;

  if (override_locale && *override_locale)

    locname = override_locale;

  else if (!locname_buffer)

    {

      char *buffer, *p;

      int count = 0;

      const char *s = gnupg_messages_locale_name ();

      buffer = xtrystrdup (s);

      if (!buffer)

        locname_buffer = "";

      else

        {

          for (p = buffer; *p; p++)

            if (*p == '.' || *p == '@' || *p == '/' /*(safeguard)*/)

              *p = 0;

            else if (*p == '_')

              {

                if (count++)

                  *p = 0;  /* Also cut at an underscore in the territory.  */

              }

          locname_buffer = buffer;

        }

      locname = locname_buffer;

    }

  else

    locname = locname_buffer;

  if (!key || !*key)

    return NULL;

  result = findkey_locale (domain, key, locname,

                           gnupg_sysconfdir (), flags);

  if (!result)

    result = findkey_locale (domain, key, locname,

                             gnupg_datadir (), flags);

  if (result && (flags & GET_TEMPLATE_SUBST_ENVVARS))

    {

      char *tmp = substitute_envvars (result);

      if (tmp)

        {

          xfree (result);

          result = tmp;

        }

    }

  if (result && !(flags & GET_TEMPLATE_CRLF))

    trim_trailing_spaces (result);

  return result;

}

char *

gnupg_get_help_string (const char *key, int only_current)

{

  return gnupg_get_template ("help", key,

                             only_current? GET_TEMPLATE_CURRENT_LOCALE : 0,

                             NULL);

}