Re: doc scm_set_program_arguments

[Kevin Ryde]

Neil Jerram <address@hidden> writes:
>
> Is argv normally NULL-terminated?

Yes, if it's from main().

> I would have thought that "argc-i" would be more reliable than "-1"
> here.

I guess it's clearer to use one method or the other (not a mixture).
I changed it to below (with set-program-arguments added too).

Is there a particular reason for the extra `command-line' name?



 -- Scheme Procedure: program-arguments
 -- Scheme Procedure: command-line
 -- Scheme Procedure: set-program-arguments
 -- C Function: scm_program_arguments ()
 -- C Function: scm_set_program_arguments_scm (lst)
     Get the command line arguments passed to Guile, or set new
     arguments.

     The arguments are a list of strings, the first of which is the
     invoked program name.  This is just "guile" (or the executable
     path) when run interactively, or it's the script name when running
     a script with `-s' (*note Invoking Guile::).

          guile -L /my/extra/dir -s foo.scm abc def

          (program-arguments) => ("foo.scm" "abc" "def")

     `set-program-arguments' allows a library module or similar to
     modify the arguments, for example to strip options it recognises,
     leaving the rest for the mainline.

     The argument list is held in a fluid, which means it's separate for
     each thread.  Neither the list nor the strings within it are
     copied at any point and normally should not be mutated.

     The two names `program-arguments' and `command-line' are an
     historical accident, they both do exactly the same thing.  The name
     `scm_set_program_arguments_scm' has an extra `_scm' on the end to
     avoid clashing with the C function below.

 -- C Function: void scm_set_program_arguments (int argc, char **argv,
          char *first)
     Set the list of command line arguments for `program-arguments' and
     `command-line' above.

     ARGV is an array of null-terminated strings, as in a C `main'
     function.  ARGC is the number of strings in ARGV, or if it's
     negative then a `NULL' entry in ARGV marks its end.

     FIRST is an extra string put at the start of the arguments, or
     `NULL' for no such extra.  This is a convenient way to pass the
     program name after advancing ARGV to strip option arguments.

          {
            char *progname = argv[0];
            int i;
            for (argv++; argv[0] != NULL && argv[0][0] == '-'; argv++)
              {
                /* munch option ... */
              }
            /* remaining args for scheme level use */
            scm_set_program_arguments (-1, argv, progname);
          }

     This sort of thing is often done at startup under `scm_boot_guile'
     with any options handled at the C level removed.  The given
     strings are all copied, so the C data is not accessed again once
     `scm_set_program_arguments' returns.