Annotation of OpenXM_contrib/pari/doc/usersch2.tex, Revision 1.1
1.1 ! maekawa 1: \chapter{Specific Use of the GP Calculator}
! 2:
! 3: Originally, \idx{GP} was designed as a debugging tool for the PARI system
! 4: library, and hence not much thought had been given to making it
! 5: user-friendly. The situation has now changed somewhat, and GP is very
! 6: useful as a stand-alone tool. The operations and functions available in
! 7: PARI and GP will be described in the next chapter. In the present one, we
! 8: describe the specific use of the GP programmable calculator.
! 9:
! 10: For starting the calculator, the general commandline syntax is:
! 11:
! 12: \kbd{gp [-s stacksize] [-p primelimit]}
! 13:
! 14: \noindent
! 15: where items within brackets are optional\footnote{*}{On the Macintosh, even
! 16: after clicking on the gp icon, once in the MPW Shell, you still need to type
! 17: explicitly a command of the above form.}. These correspond to some internal
! 18: parameters of GP, or {\it defaults}. See \secref{se:defaults} below for a
! 19: list and explanation of all defaults, there are many more than just those
! 20: two. These defaults can be changed by adding parameters to the input line
! 21: as above, or interactively during a GP session or in a preferences file (also
! 22: known as \kbd{gprc}).
! 23:
! 24: \unix Some new features were developed on UNIX platforms, and depend heavily
! 25: on the operating system in use. It is {\it possible\/} that some of these
! 26: will be ported to other operating systems (BeOS, MacOS, DOS, OS/2, Windows,
! 27: etc.) in future versions (most of them should be easy tasks for anybody
! 28: acquainted with those). As for now, most of them were not. So, whenever a
! 29: specific feature of the UNIX version is discussed in a paragraph, a UNIX sign
! 30: sticks out in the left margin, like here. Just skip these if you're stranded
! 31: on a different operating system: the core GP functions (i.e.~at least
! 32: everything which is even faintly mathematical in nature) will still be
! 33: available to you. It may also be possible (and then definitely advisable) to
! 34: install \idx{Linux} or \idx{FreeBSD} on your machine.
! 35:
! 36: \misctitle{Note (added in version 2.0.12):} All the UNIX goodies are now
! 37: available for DOS, OS/2 and Windows 3.1, thanks to the \tet{EMX} runtime
! 38: package (\kbd{install} excluded under DOS, since DLLs are not supported by
! 39: the OS). They've been reported to be available under Windows 95/98 and NT
! 40: using the Cygwin package (untested by us, but supposedly supported by
! 41: \kbd{Configure}).
! 42:
! 43: \emacs If you have GNU Emacs, you can work in a special Emacs shell (see
! 44: \secref{se:emacs}), which is started by typing \kbd{M-x gp} (where as
! 45: usual \kbd{M} is the \kbd{Meta} key) if you accept the default stack, prime
! 46: and buffer sizes, or \kbd{C-u M-x gp} which will ask you for the name of the
! 47: gp executable, the stack size, the prime limit and the buffer size. Specific
! 48: features of this Emacs shell will be indicated by an EMACS sign.\smallskip
! 49:
! 50: If a \idx{preferences file} (or \kbd{gprc}, to be discussed in
! 51: \secref{se:gprc}) can be found, GP will then read it and execute the commands
! 52: it contains. This provides an easy way to customize GP without having to
! 53: delve into the code to hardwire it to your likings.
! 54:
! 55: A copyright message then appears which includes the version number. Please
! 56: note this number, so as to be sure to have the most recent version if you
! 57: wish to have updates of PARI. The present manual is written for version
! 58: \vers, and has undergone major changes since the 1.39.xx versions.
! 59:
! 60: After the copyright, the computer works for a few seconds (it is in fact
! 61: computing and storing a table of primes), writes the top-level help
! 62: information, some initial defaults, and then waits after printing its prompt
! 63: (initially: \kbd{?}).
! 64:
! 65: Note that at any point the user can type \kbd{Ctrl-C} (that is press
! 66: simultaneously the \kbd{Control} and \kbd{C} keys): the current
! 67: computation will be interrupted and control given back to the user at the GP
! 68: prompt.
! 69:
! 70: The top-level help information tells you that (as in many systems) to get
! 71: help, you should type a \kbd{?}. When you do this and hit return, a menu
! 72: appears, describing the eleven main categories of available functions and
! 73: what to do to get more detailed help. If you now type \kbd{?$n$} with $1\le
! 74: n\le11$, you will get the list of commands corresponding to category $n$
! 75: and simultaneously to Section $3.n$ of this manual.
! 76:
! 77: If you type \kbd{?}\var{functionname} where \var{functionname} is the
! 78: name of a PARI function, you will get a short explanation of this
! 79: function.
! 80:
! 81: \unix If extended help (see \secref{se:exthelp}) is available on your
! 82: system, you can double or triple the \kbd{?} sign to get much more:
! 83: respectively the complete description of the function (e.g.~\kbd{??~sqrt}),
! 84: or a list of GP functions relevant to your query (e.g.~ \kbd{???~"elliptic
! 85: curve"} or \kbd{???~"quadratic field"}).
! 86:
! 87: If GP was compiled with the right options (see Appendix A), a line
! 88: editor will be available to correct the command line, get automatic
! 89: completions, and so on. See \secref{se:readline} for a short summary of
! 90: available commands. This might not be available for all architectures.
! 91:
! 92: Whether extended on-line help and line editing are available or not is
! 93: indicated in the GP banner, between the version number and the copyright
! 94: message.
! 95:
! 96: If you type \kbd{?\bs} you will get a short description of the metacommands
! 97: (keyboard shortcuts).
! 98:
! 99: Finally, typing \kbd{?.} will return the list of available (pre-defined)
! 100: member functions. These are functions attached to specific kind of objects,
! 101: used to retrieve easily some information from complicated structures (you
! 102: can define your own but they won't be shown here). We will soon describe
! 103: these commands in more detail.
! 104:
! 105: As a general rule, under GP, commands starting with \b\ or with some
! 106: other symbols like \kbd{?} or \kbd{\#}, are not computing commands, but are
! 107: metacommands which allow the user to exchange information with GP. The
! 108: available metacommands can be divided into default setting commands
! 109: (explained below) and simple commands (or keyboard shortcuts, to be dealt
! 110: with in \secref{se:meta}).
! 111:
! 112: \section{Defaults and output formats}\sidx{defaults}\sidx{output formats}
! 113: \label{se:defaults}
! 114:
! 115: \noindent
! 116: There are many internal variables in GP, defining how the system will behave
! 117: in certain situations, unless a specific override has been given. Most
! 118: of them are a matter of basic customization (colors, prompt) and will be set
! 119: once and for all in your \idx{preferences file} (see \secref{se:gprc}), but
! 120: some of them are useful interactively (set timer on, increase precision,
! 121: etc.).
! 122:
! 123: The function used to manipulate these values is called \kbd{default}, which
! 124: is described in \secref{se:default}. The basic syntax is
! 125:
! 126: \kbd{default(\var{def}, \var{value})},
! 127:
! 128: \noindent
! 129: which sets the default \var{def} to \var{value}. In interactive
! 130: use, most of these can be abbreviated using historic GP metacommands (mostly,
! 131: starting with \b), which we shall describe in the next section.
! 132:
! 133: Here we will only describe the available defaults and how they are used. Just
! 134: be aware that typing \kbd{default} by itself will list all of them, as well
! 135: as their current values (see \b{d}). Just after the default name, we give
! 136: between parentheses the initial value when GP starts (assuming you did not
! 137: tamper with it using command-line switches or a~\tet{gprc}).
! 138:
! 139: \misctitle{(somewhat technical) Note:} As we will see in \secref{se:strings},
! 140: the second argument to default will be subject to string context expansion,
! 141: which means you can use run-time values. In other words, something like
! 142: \kbd{a = 3; default(logfile, "\var{some filename}" a ".log")} will work.
! 143:
! 144: For the user's convenience, some defaults will be expanded further when
! 145: the values are used (after the above expansion has been performed):
! 146:
! 147: $\bullet$ \idx{time expansion}: the string is sent through the library
! 148: function \tet{strftime}. This means that \kbd{\%}\var{char} combinations have
! 149: a special meaning, usually related to the time and date. For instance,
! 150: \kbd{\%H} = hour (24-hour clock) and \kbd{\%M} = minute [00,59] (on a Unix
! 151: system, you can try \kbd{man strftime} at your shell prompt to get a complete
! 152: list). This is applied to \kbd{prompt}, \kbd{psfile}, and \kbd{logfile}. For
! 153: instance,
! 154:
! 155: \kbd{default(prompt,"(\%R) ? ")}
! 156:
! 157: \noindent
! 158: will prepend the time of day, in the form \kbd{(\var{hh}:\var{mm})}
! 159: to GP's usual prompt.
! 160:
! 161: \unix $\bullet$ \idx{environment expansion}: When the string contains a
! 162: sequence of the form \kbd{\${\it SOMEVAR}} (e.g.~\kbd{\$HOME}) the
! 163: environment is searched and if {\it SOMEVAR} is defined, the sequence is
! 164: replaced by the corresponding value. Also the \kbd{\til} symbol has the
! 165: same meaning as in the C and bash shells~--- \kbd{\til} by itself stands
! 166: for your home directory, and \kbd{\til{}user} is expanded to \kbd{user}'s
! 167: home directory. This is applied to all filenames\sidx{filename}.
! 168:
! 169: \subsecidx{buffersize} (default \kbd{30000}): GP input is buffered, which means
! 170: only so many bytes of data can be read at a time before a command is
! 171: executed. This used to be a very important variable, to allow for very
! 172: large input files to be read into GP, for example large matrices, without it
! 173: complaining about ``unused characters''. Currently, \kbd{buffersize} is
! 174: automatically adjusted to the size of the data that are to be read. It will
! 175: never go down by itself though. Thus this option may come in handy to decrease
! 176: the buffer size after some unusually large \kbd{read}, when you don't need to
! 177: keep gigantic buffers around anymore.
! 178:
! 179: \subsecidxunix{colors} (default \kbd{""}): this default is only usable if GP
! 180: \label{se:colors}
! 181: is running within certain color-capable terminals. For instance \kbd{rxvt},
! 182: \kbd{color\_xterm} and modern versions of \kbd{xterm} under X Windows, or
! 183: standard Linux/DOS text consoles. It causes GP to use a small palette of
! 184: colors for its output. With xterms, the colormap used corresponds to the
! 185: resources \kbd{Xterm*color$n$} where $n$ ranges from $0$ to $15$ (see the
! 186: file \kbd{misc/color.dft} for an example). Legal values for this default are
! 187: strings \kbd{"$a_1$,\dots,$a_k$"} where $k\le7$ and each $a_i$ is either
! 188:
! 189: \noindent $\bullet$ the keyword \kbd{no} (use the default color, usually
! 190: black)
! 191:
! 192: \noindent $\bullet$ an integer between 0 and 15 corresponding to the
! 193: aforementioned colormap
! 194:
! 195: \noindent $\bullet$ a triple $[c_0,c_1,c_2]$ where $c_0$ stands for foreground
! 196: color, $c_1$ for background color, and $c_2$ for attributes (0 is default, 1
! 197: is bold, 4 is underline).
! 198:
! 199: The output objects thus affected are respectively error messages,
! 200: history numbers, prompt, input line, output, help messages, timer (that's
! 201: seven of them). If $k < 7$, the remaining $a_i$ are assumed to be $no$. For
! 202: instance
! 203: %
! 204: \bprog%
! 205: default(colors,"9, 5, no, no, 4")
! 206: \eprog
! 207: \noindent
! 208: typesets error messages in color $9$, history numbers in color $5$, output in
! 209: color $4$, and does not affect the rest.
! 210:
! 211: \emacs{In the present version, this default is incompatible with Emacs.
! 212: Changing it will just fail silently (the alternative would be to display
! 213: escape sequences as is, since Emacs will refuse to interpret them). On the
! 214: other hand, you can customize highlighting in your \kbd{.emacs} so as to mimic
! 215: exactly this behaviour. See \kbd{emacs/pariemacs.txt}.}
! 216:
! 217: If you use an old \kbd{readline} library (version number less than 2.0),
! 218: you should do as in the example above and leave $a_3$ and $a_4$ (prompt
! 219: and input line) strictly alone. Since old versions of \kbd{readline} did
! 220: not handle escape characters correctly (or more accurately, treated them
! 221: in the only sensible way since they did not care to check all your terminal
! 222: capabilities: it just ignored them), changing them would result in many
! 223: annoying display bugs.
! 224:
! 225: The hacker's way to check if this is the case would be to look in the
! 226: \kbd{readline.h} include file (wherever your readline include files are) for
! 227: the string \kbd{RL\_PROMPT\_START\_IGNORE}. If it's there, you are safe.
! 228:
! 229: A more sensible way is to make some experiments, and get a more recent
! 230: \kbd{readline} if yours doesn't work the way you'd like it to. See the file
! 231: \kbd{misc/gprc.dft} for some examples.
! 232:
! 233: \subsecidx{compatible} (default \kbd{0}): The GP function names and syntax have
! 234: changed tremendously between versions 1.xx and 2.00. To help you cope with this
! 235: we provide some kind of backward compatibility, depending on the value of
! 236: this default:
! 237:
! 238: \quad \kbd{compatible} = 0: no backward compatibility. In this mode, a very
! 239: handy function, to be described in \secref{se:whatnow}, is \kbd{whatnow},
! 240: which tells you what has become of your favourite functions, which GP
! 241: suddenly can't seem to remember.
! 242:
! 243: \quad \kbd{compatible} = 1: warn when using obsolete functions, but otherwise
! 244: accept them. The output uses the new conventions though, and there may be
! 245: subtle incompatibilities between the behaviour of former and current
! 246: functions, even when they share the same name (the current function is used in
! 247: such cases, of course!). We thought of this one as a transitory help for GP
! 248: old-timers. Thus, to encourage switching to \kbd{compatible}=0, it is not
! 249: possible to disable the warning.
! 250:
! 251: \quad \kbd{compatible} = 2: use only the old function naming scheme (as used up
! 252: to version 1.39.15), but {\it taking case into account}. Thus \kbd{I}
! 253: (${}=\sqrt{-1}$) is not the same as \kbd{i} (user variable, unbound by
! 254: default), and you won't get an error message using \kbd{i} as a loop index
! 255: as used to be the case.
! 256:
! 257: \quad \kbd{compatible} = 3: try to mimic exactly the former behaviour. This is
! 258: not always possible when functions have changed in a fundamental way. But
! 259: these differences are usually for the better (they were meant to, anyway), and
! 260: will probably not be discovered by the casual user.
! 261:
! 262: One adverse side effect is that any user functions and aliases that have been
! 263: defined {\it before\/} changing \kbd{compatible} will get erased if this
! 264: change modifies the function list, i.e.~if you move between groups $\{0,1\}$
! 265: and $\{2,3\}$ (variables are unaffected). We of course strongly encourage you
! 266: to try and get used to the setting \kbd{compatible}=0.
! 267:
! 268: \subsecidx{debug} (default \kbd{0}): debugging level. If it is non-zero, some
! 269: extra messages may be printed (some of it in French), according to what is
! 270: going on (see~\b{g}).
! 271:
! 272: \subsecidx{debugfiles} (default \kbd{0}): file usage debugging level. If it is
! 273: non-zero, GP will print information on file descriptors in use, from PARI's
! 274: point of view (see~\b{gf}).
! 275:
! 276: \subsecidx{debugmem} (default \kbd{0}): memory debugging level. If it is
! 277: non-zero, GP will regularly print information on memory usage. If it's
! 278: greater than 2, it will indicate any important garbage collecting and the
! 279: function it is taking place in (see~\b{gm}).
! 280:
! 281: \noindent {\bf Important Note:} As it noticeably slows down the performance
! 282: (and triggers bugs in a popular compiler), the first functionality (memory
! 283: usage) is disabled if you're not running a version compiled for debugging
! 284: (see Appendix~A).
! 285:
! 286: \subsecidx{echo} (default \kbd{0}): this is a toggle, which can be either 1
! 287: (on) or 0 (off). When \kbd{echo} mode is on, each command is reprinted before
! 288: being executed. This can be useful when reading a file with the \b{r} or
! 289: \kbd{read} commands. For example, it is turned on at the beginning of the test
! 290: files used to check whether GP has been built correctly (see \b{e}).
! 291:
! 292: \subsecidx{format} (default \kbd{"g0.28"} and \kbd{"g0.38"} on 32-bit and
! 293: 64-bit machines, respectively): of the form x$m.n$, where x is a letter in
! 294: $\{\kbd{e},\kbd{f},\kbd{g}\}$, and $n$, $m$ are integers. If x is \kbd{f},
! 295: real numbers will be printed in \idx{fixed floating point format} with no
! 296: explicit exponent (e.g.~\kbd{0.000033}); if the letter is \kbd{e}, they will be
! 297: printed in \idx{scientific format}, always with an explicit exponent (e.g.
! 298: \kbd{3.3e-5}). If the letter is \kbd{g}, real numbers will be printed in
! 299: \kbd{f} format, except when their absolute value is less than $2^{-32}$,
! 300: in which case they are printed in \kbd{e} format. \label{se:format}
! 301:
! 302: The number $n$ is the number of significant digits printed for real
! 303: numbers, except if $n<0$ where all the significant digits will be printed
! 304: (initial default 28, or 38 for 64-bit machines), and the number $m$ is the
! 305: number of characters to be used for printing integers, but is ignored if
! 306: equal to 0 (which is the default). This is a feeble attempt at formatting.
! 307:
! 308: \subsecidxunix{help} (default: the location of the \kbd{gphelp} script): the
! 309: name of the external help program which will be used from within GP when
! 310: extended help is invoked, usually through a \kbd{??} or \kbd{???} request
! 311: (see \secref{se:exthelp}), or \kbd{M-H} under readline (see
! 312: \secref{se:readline}).
! 313:
! 314: \subsecidx{histsize} (default \kbd{5000}): GP keeps a history of the last
! 315: \kbd{histsize} results computed so far, which you can recover using the
! 316: \kbd{\%} notation (see \secref{se:history}). When this number is exceeded,
! 317: the oldest values are erased. Tampering with this default is the only way to
! 318: get rid of the ones you don't need anymore.
! 319:
! 320: \subsecidx{lines} (default \kbd{0}): if set to a positive value, GP prints at
! 321: most that many lines from each result, terminating the last line shown with
! 322: \kbd{[+++]} if further material has been suppressed. The various \kbd{print}
! 323: commands (see \secref{se:gp_program}) are unaffected, so you can always type
! 324: \kbd{print(\%)}, \b{a}, or \b{b} to view the full result. If the actual
! 325: screen width cannot be determined, a ``line'' is assumed to be 80 characters
! 326: long.
! 327:
! 328: \subsecidx{log} (default \kbd{0}): this is a toggle, which can be either 1
! 329: (on) or 0 (off). When logging mode is turned on, GP opens a log file, whose
! 330: exact name is determined by the \kbd{logfile} default. Subsequently, all the
! 331: commands and results will be written to that file (see \b{l}). In case a file
! 332: with this precise name already existed, it will not be erased: your data will
! 333: be {\it appended\/} at the end.
! 334:
! 335: \subsecidx{logfile} (default \kbd{"pari.log"}): name of the log file to be
! 336: used when the \kbd{log} toggle is on. Tilde and time expansion are performed.
! 337:
! 338: \subsecidx{output} (default \kbd{1}): this can take any of the following three
! 339: values: 0 (=~{\it raw\/}), 1 (=~{\it prettymatrix\/}), or 2
! 340: (=~{\it prettyprint\/}). This means that, independently of the default
! 341: \kbd{format} for reals which we explained above, you can print results in
! 342: three ways: either in {\it raw\/}\sidx{raw format} format, i.e.~a format
! 343: which is equivalent to what you input, including explicit multiplication
! 344: signs, and everything typed on a line instead of two dimensional boxes. This
! 345: can have several advantages, for instance it allows you to pick the result
! 346: with a mouse or an editor, and to put it somewhere else.\label{se:output}
! 347:
! 348: The second format is the {\it prettymatrix\/}\sidx{prettymatrix format} format.
! 349: The only difference to raw format is that matrices are printed as boxes
! 350: instead of horizontally. This is prettier, but takes more space and cannot be
! 351: used for input. Column vectors are still printed horizontally.
! 352:
! 353: The third format is the {\it prettyprint\/}\sidx{prettyprint format} or
! 354: beautified format. In the present version \vers, this is not beautiful at
! 355: all.
! 356:
! 357: Independently of the setting of this default, an object can be printed
! 358: in any of the three formats at any time using the commands \b{a}, \b{m}
! 359: and~\b{b} respectively (see below).
! 360:
! 361: \subsecidx{parisize} (default, 1000000 bytes on the Mac, 4000000 otherwise):
! 362: GP, and in fact any program using the PARI library, needs a stack in which to
! 363: do its computations. \kbd{parisize} is the stack size, in bytes. It is
! 364: strongly recommended you increase this default (using the \kbd{-s}
! 365: command-line switch, or a \kbd{gprc}) if you can afford it. In case of
! 366: emergency, you can use the \tet{allocatemem} function to increase
! 367: \kbd{parisize}, once the session is started. GP will try to {\it double\/} the
! 368: stack size by itself when memory runs low during a computation, but
! 369: this very computation will then be lost, and you will have to type the
! 370: command again.
! 371:
! 372: \subsecidx{path} (default \kbd{".:\til:\til/gp"} on UNIX systems,
! 373: \kbd{".;C:\bs;C:\bs GP} on DOS, OS/2 and Windows, and \kbd{"."} otherwise):
! 374: This is a list of directories, separated by colons ':' (semicolons ';' in the
! 375: DOS world, since colons are pre-empted for drive names). When asked to read a
! 376: file whose name does not contain \kbd{/} (i.e.~no explicit path was given),
! 377: GP will look for it in these directories, in the order they were written in
! 378: \kbd{path}. Here, as usual, '.' means the current directory, and '$.\,.$' its
! 379: immediate parent. Tilde expansion is performed.
! 380:
! 381: \subsecidx{primelimit} (default \kbd{200000} on the Mac, and \kbd{500000}
! 382: otherwise): GP precomputes a list of all primes less than \kbd{primelimit} at
! 383: initialization time. These are used by many arithmetical functions.
! 384: If you don't plan to invoke any of them, you can just set this to 1.
! 385:
! 386: \subsecidx{prompt} (default \kbd{"? "}): a string that will be printed as
! 387: prompt. Note that most usual escape sequences are available there: \b{e} for
! 388: Esc, \b{n} for Newline, \dots, \kbd{\bs\bs} for \kbd{\bs}. Time expansion is
! 389: performed.
! 390:
! 391: This string is sent through the library function \kbd{\idx{strftime}} (on a
! 392: Unix system, you can try \kbd{man strftime} at your shell prompt). This means
! 393: that \kbd{\%} constructs have a special meaning, usually related to the time
! 394: and date. For instance, \kbd{\%H} = hour (24-hour clock) and \kbd{\%M} =
! 395: minute [00,59] (use \kbd{\%\%} to get a real \kbd{\%}).
! 396:
! 397: If you use \kbd{readline}, escape sequences in your prompt will result in
! 398: display bugs. If you have a relatively recent \kbd{readline} (see the comment
! 399: at the end of \secref{se:colors}), you can brace them with special sequences
! 400: (\kbd{\bs[} and \kbd{\bs]}), and you will be safe. If these just result in
! 401: extra spaces in your prompt, then you'll have to get a more recent
! 402: \kbd{readline}. See the file \kbd{misc/gprc.dft} for an example.
! 403:
! 404: \emacs {\bf Caution}: Emacs needs to know about the prompt pattern to
! 405: separate your input from previous GP results, without ambiguity. It's not a
! 406: trivial problem to adapt automatically this regular expression to an
! 407: arbitrary prompt (which can be self-modifying!). Thus, in this version \vers,
! 408: Emacs relies on the prompt being the default one. So, do not tamper with the
! 409: \kbd{prompt} variable {\it unless\/} you modify it simultaneously in your
! 410: \kbd{.emacs} file (see \kbd{emacs/pariemacs.txt} and \kbd{misc/gprc.dft} for
! 411: examples).
! 412:
! 413: \subsecidx{psfile} (default \kbd{"pari.ps"}): name of the default file where
! 414: GP is to dump its PostScript drawings (these will always be appended, so that
! 415: no previous data are lost). Tilde and time expansion are performed.
! 416:
! 417: \subsecidx{realprecision} (default \kbd{28} and \kbd{38} on 32-bit and 64-bit
! 418: machines respectively): the number of significant digits and, at the same
! 419: time, the number of printed digits of real numbers (see~\b{p}). Note that
! 420: PARI internal precision works on a word basis (32 or 64 bits), hence may not
! 421: coincide with the number of decimal digits you input. For instance to get 2
! 422: decimal digits you need one word of precision which, on a 32-bit machine,
! 423: actually gives you 9 digits ($9 < \log_{10}(2^{32}) < 10$):
! 424:
! 425: \bprog%
! 426: ? default(realprecision, 2)
! 427: \q realprecision = 9 significant digits (2 digits displayed)
! 428: \eprog
! 429:
! 430: \subsecidx{secure} (default \kbd{0}): this is a toggle which can be either 1
! 431: (on) or 0 (off). If on, the \tet{system} and \tet{extern} command are
! 432: disabled. These two commands are potentially dangerous when you execute
! 433: foreign scripts since they let GP execute arbitrary UNIX commands. GP will
! 434: ask for confirmation before letting you (or a script) unset this toggle.
! 435:
! 436: \subsecidx{seriesprecision} (default \kbd{16}): precision of power series
! 437: (see~\b{ps}).
! 438:
! 439: \subsecidx{simplify} (default \kbd{1}): this is a toggle which can be either
! 440: 1 (on) or 0 (off). When the PARI library computes something, the type of the
! 441: result is not always the simplest possible. The only type conversions which
! 442: the PARI library does automatically are rational numbers to integers (when
! 443: they are of type \typ{FRAC} and equal to integers), and similarly rational
! 444: functions to polynomials (when they are of type \typ{RFRAC} and equal to
! 445: polynomials). This feature is useful in many cases, and saves time, but can
! 446: be annoying at times. Hence you can disable this and, whenever you feel like
! 447: it, use the function \kbd{simplify} (see Chapter 3) which allows you to
! 448: simplify objects to the simplest possible types recursively (see~\b{y}).
! 449: \sidx{automatic simplification}
! 450:
! 451: \subsecidx{strictmatch} (default \kbd{1}): this is a toggle which can be
! 452: either 1 (on) or 0 (off). If on, unused characters after a sequence has been
! 453: processed will produce an error. Otherwise just a warning is printed. This
! 454: can be useful when you're not sure how many parentheses you have to close after
! 455: complicated nested loops.
! 456:
! 457: \subsecidx{timer} (default \kbd{0}): this is a toggle which can be either 1
! 458: (on) or 0 (off). If on, every instruction sequence (anything ended by a
! 459: newline in your input) is timed, to some accuracy depending on the hardware
! 460: and operating system. The time measured is the user \idx{CPU time},
! 461: {\it not\/} including the time for printing the results (see \kbd{\#} and
! 462: \kbd{\#\#}).
! 463:
! 464: \subsec{Note on output formats.}
! 465:
! 466: \noindent
! 467: A zero real number is printed in \kbd{e} format as $0.Exx$ where $xx$ is
! 468: the (usually negative) {\it decimal\/} exponent of the number (cf.\ %
! 469: \secref{se:whatzero}). This allows the user to check the accuracy of the zero
! 470: in question (this could also be done using \b{x}, but that would be more
! 471: technical).
! 472:
! 473: When the integer part of a real number $x$ is not known exactly because the
! 474: exponent of $x$ is greater than the internal precision, the real number is
! 475: printed in \kbd{e} format (note that in versions before 1.38.93, this was
! 476: instead printed with a $*$ at the end).
! 477:
! 478: Note also that in beautified format, a number of type integer or real is
! 479: written without enclosing parentheses, while most other types have them.
! 480: Hence, if you see the expression $( 3.14 )$, it is not of type real, but
! 481: probably of type complex with zero imaginary part (if you want to be sure, type
! 482: \b{x} or use the function \kbd{type}).
! 483:
! 484: \section{Simple metacommands}\label{se:meta}
! 485:
! 486: \noindent
! 487: Simple metacommands are meant as shortcuts and should not be used in GP
! 488: scripts (see \secref{se:programming}). Beware that these, as all of GP input,
! 489: are now {\it case sensitive}. For example, \b{Q} is no longer identical to
! 490: \b{q}. In the following list, braces are used to denote optional arguments,
! 491: with their default values when applicable, e.g.~$\{n=0\}$ means that if $n$
! 492: is not there, it is assumed to be~$0$. Whitespace (or spaces) between the
! 493: metacommand and its arguments and within arguments is optional. (This can
! 494: cause problems only with \b{w}, when you insist on having a filename whose
! 495: first character is a digit, and with \b{r} or \b{w}, if the filename itself
! 496: contains a space. In such cases, just use the underlying \kbd{read} or
! 497: \kbd{write} function; see~\secref{se:write}).
! 498:
! 499: \subseckbd{?} $\{{\it command}\}$: GP on-line help interface.
! 500: As already mentioned, if you type \kbd{?$n$} where $n$ is a number from 1
! 501: to 11, you will get the list of functions in Section $3.n$ of the manual
! 502: (the list of sections being obtained by simply typing \kbd{?}).
! 503: \label{se:exthelp}
! 504:
! 505: These names are in general not informative enough. More details can be
! 506: obtained by typing \kbd{?{\it function}}, which gives a short explanation of
! 507: the function's calling convention and effects. Of course, to have complete
! 508: information, read Chapter 3 of this manual (the source code is at your
! 509: disposal as well, though a trifle less readable!). Much better help can be
! 510: obtained through the extended help system (see below).
! 511:
! 512: You then get the function description exactly as it stands
! 513: in Chapter 3. All operators (e.g.~\kbd{+}, \kbd{\&\&}, etc.) are accepted
! 514: by this extended help, as well as a few other keywords describing key GP
! 515: concepts, e.g.~\kbd{readline} (the line editor), \kbd{integer}, \kbd{nf}
! 516: (``number field'' as used in most algebraic number theory computations),
! 517: \kbd{ell} (elliptic curves), etc.
! 518:
! 519: \unix If the line before the copyright message indicates that extended help
! 520: is available (this means \kbd{perl} is installed on your system, GP was
! 521: told about it at compile time, and the whole PARI distribution was
! 522: correctly installed), you can add more \kbd{?} signs for extended
! 523: functionalities:
! 524:
! 525: \kbd{??~\var{keyword}} yields the functions description as it stands in this
! 526: manual, usually in Chapter~2 or~3. If you're not satisfied with the default
! 527: chapter chosen, you can impose a given chapter by ending the keyword with
! 528: \kbd{@} followed by the chapter number, e.g.~\kbd{??~Hello@2} will look in
! 529: Chapter~2 for section heading \kbd{Hello} (which doesn't exist, by the way).
! 530:
! 531: \kbd{???~\var{pattern}} produces a list of sections in Chapter~3 of the
! 532: manual related to your query. As before, if \var{pattern} ends by \kbd{@}
! 533: ifollowed by a chapter number, that chapter is searched instead; you also
! 534: have the option to append a simple \kbd{@} (without a chapter number) to
! 535: browse through the whole manual.
! 536:
! 537: If your query contains dangerous characters (e.g \kbd{?} or blanks) it is
! 538: advisable to enclose it within double quotes, as for GP strings (e.g
! 539: \kbd{???~"elliptic curve"}).
! 540:
! 541: Note that extended help is much more powerful than the short help, since
! 542: it knows about operators as well: you can type \kbd{??~*} or
! 543: \kbd{??~\&\&}, whereas a single \kbd{?} would just yield a not too helpful
! 544:
! 545: \kbd{*** unknown identifier.}
! 546:
! 547: \noindent message. Also, you can ask for extended help on section
! 548: number~$n$ in Chapter~3, just by typing \kbd{??~$n$} (where \kbd{?$n$} would
! 549: yield merely a list of functions). Finally, a few key concepts in GP are
! 550: documented in this way: metacommands (e.g \kbd{??~"??"}), defaults (e.g
! 551: \kbd{??~psfile}) and type names (e.g \typ{INT} or \kbd{integer}), as well as
! 552: various miscellaneous keywords such as \kbd{edit} (short summary of line
! 553: editor commands), \kbd{operator}, \kbd{member}, \kbd{"user defined"},
! 554: \kbd{nf}, \kbd{ell}, \dots
! 555:
! 556: Last but not least~: \kbd{??} without argument will open a \kbd{dvi}
! 557: previewer (\kbd{xdvi} by default, \kbd{\$GPXDVI} if it is defined in your
! 558: environment) containing the full user's manual. \kbd{??tutorial} and
! 559: \kbd{??refcard} do the same with the \idx{tutorial} and \idx{reference card}
! 560: respectively.
! 561:
! 562: \misctitle{Technical note:} these functionalities are provided by an
! 563: external \kbd{perl} script that you are free to use outside any GP session
! 564: (and modify to your liking, if you are perl-knowledgeable). It is called
! 565: \kbd{\idx{gphelp}}, lies in the \kbd{doc} subdirectory of your distribution
! 566: (just make sure you run \kbd{Configure} first, see Appendix~A) and is
! 567: really two programs in one. The one which is used from within GP is
! 568: \kbd{gphelp} which runs \TeX\ on a selected part of this manual, then opens
! 569: a previewer. \kbd{gphelp -detex} is a text mode equivalent, which looks
! 570: often nicer especially on a colour-capable terminal (see
! 571: \kbd{misc/gprc.dft} for examples). The default \kbd{help} selects which
! 572: help program will be used from within GP. You are welcome to improve this
! 573: help script, or write new ones (and we really would like to know about it
! 574: so that we may include them in future distributions). By the way, outside
! 575: of GP you can give more than one keyword as argument to \kbd{gphelp}.
! 576:
! 577: \subseckbd{/*...*/}: comment. Everything between the stars is ignored by
! 578: GP. These comments can span any number of lines.
! 579:
! 580: \subseckbd{\bs\bs}: one-line comment. The rest of the line
! 581: is ignored by GP.
! 582:
! 583: \subsec{\b{a}} $\{n\}$: prints the object number $n$ ($\%n$)
! 584: in raw format. If the number $n$ is omitted, print the latest computed object
! 585: ($\%$). \label{se:history}
! 586:
! 587: \subsec{\b{b}} $\{n\}$: Same as \b{a}, in prettyprint (i.e.~beautified)
! 588: format.
! 589:
! 590: \subsec{\b{c}}:\sidx{available commands} prints the list of all available
! 591: hardcoded functions under GP, not including operators written as special
! 592: symbols (see \secref{se:operators}). More information can be obtained using
! 593: the \kbd{?} metacommand (see above). For user-defined functions / member
! 594: functions, see \b{u} and \b{um}.
! 595:
! 596: \subsec{\b{d}}: prints the \idx{defaults} as described in the
! 597: previous section (shortcut for \kbd{default()}, see \secref{se:default}).
! 598:
! 599: \subsec{\b{e}} $\{n\}$: switches the \kbd{echo} mode on (1) or off (0). If
! 600: $n$ is explicitly given, set echo to $n$.
! 601:
! 602: \subsec{\b{g}} $\{n\}$: sets the debugging level \kbd{debug} to the
! 603: non-negative integer $n$.
! 604:
! 605: \subsec{\b{gf}} $\{n\}$: sets the file usage debugging level \kbd{debufiles}
! 606: to the non-negative integer $n$.
! 607:
! 608: \subsec{\b{gm}} $\{n\}$: sets the memory debugging level \kbd{debugmem}
! 609: to the non-negative integer $n$.
! 610:
! 611: \subsec{\b{h}} $\{m$\kbd{-}$n\}$: outputs some debugging info about the
! 612: hashtable. If the argument is a number $n$, outputs the contents of cell
! 613: $n$. Ranges can be given in the form $m$\kbd{-}$n$ (from cell $m$ to cell
! 614: $n$, \$ = last cell). If a function name is given instead of a number or
! 615: range, outputs info on the internal structure of the hash cell this
! 616: function occupies (a \kbd{struct entree} in C). If the range is reduced to
! 617: a dash ('\kbd{-}'), outputs statistics about hash cell usage.
! 618:
! 619: \subsec{\b{l}} $\{${\it logfile/}$\}$: switches \kbd{log} mode on and off.
! 620: If a {\it logfile} argument is given, change the default logfile name to
! 621: {\it logfile} and switch log mode on.
! 622:
! 623: \subsec{\b{m}}: as \b{a}, but using prettymatrix format.
! 624:
! 625: \subsec{\b{p}} $\{n\}$: sets \kbd{realprecision} to $n$ decimal
! 626: digits. Prints its current value if $n$ is omitted.
! 627:
! 628: \subsec{\b{ps}} $\{n\}$: sets \kbd{seriesprecision} to $n$ significant terms.
! 629: Prints its current value if $n$ is omitted.
! 630:
! 631: \subsec{\b{q}}: \idx{quit}s the GP session and returns to the system.
! 632: Shortcut for the function \kbd{quit} (see \secref{se:quit}).
! 633:
! 634: \subsec{\b{r}} $\{${\it filename\/}$\}$: \idx{read}s into GP all the commands
! 635: contained in the named file as if they had been typed from the keyboard, one
! 636: line after the other. Can be used in combination with the \b{w} command (see
! 637: below). Related but not equivalent to the function \kbd{read} (see
! 638: \secref{se:read}); in particular, if the file contains more than one line of
! 639: input, there will be one history entry for each of them, whereas \kbd{read}
! 640: would only record the last one. If {\it filename\/} is omitted, re-read the
! 641: previously used input file (fails if no file has ever been successfully read
! 642: in the current session).
! 643:
! 644: \unix This command accepts compressed files in \idx{compress}ed (\kbd{.Z})
! 645: or \idx{gzip}ped (\kbd{.gz} or \kbd{.z}) format. They will be uncompressed on
! 646: the fly as GP reads them, without changing the files themselves.
! 647:
! 648: \subsec{\b{s}}: prints the state of the PARI \idx{stack} and \idx{heap}.
! 649: This is used primarily as a debugging device for PARI, and is not intended
! 650: for the casual user.
! 651:
! 652: \subsec{\b{t}}: prints the \idx{internal longword format} of all the PARI
! 653: types. The detailed bit or byte format of the initial codeword(s) is
! 654: explained in Chapter~4, but its knowledge is not necessary for a GP user.
! 655:
! 656: \subsec{\b{u}}: prints the definitions of all user-defined functions.
! 657:
! 658: \subsec{\b{um}}: prints the definitions of all user-defined member functions.
! 659:
! 660: \subsec{\b{v}}: prints the \idx{version number} and implementation architecture
! 661: (680x0, Sparc, Alpha, other) of the GP executable you are using. In library
! 662: mode, you can use instead the two character strings \kbd{PARIVERSION} and
! 663: \kbd{PARIINFO}, which correspond to the first two lines printed by GP just
! 664: before the Copyright message.
! 665:
! 666: \subsec{\b{w}} $\{n\}$ $\{${\it filename\/}$\}$: \idx{write}s the object number
! 667: $n$ ( $\%n$ ) into the named file, in raw format. If the number $n$ is
! 668: omitted, writes the latest computed object ( $\%$ ). If {\it filename\/} is
! 669: omitted, appends to \kbd{logfile} (the GP function \kbd{write} is a trifle more
! 670: powerful, as you can have filenames whose first character is a digit).
! 671:
! 672: \subsec{\b{x}}: prints the complete tree with addresses and contents (in
! 673: hexadecimal) of the \idx{internal representation} of the latest computed
! 674: object in GP. As for \b{s}, this is used primarily as a debugging device for
! 675: PARI. However, used on a PARI integer, it can be used as a
! 676: decimal$\rightarrow$hexadecimal converter.
! 677:
! 678: \subsec{\b{y}} $\{n\}$: switches \kbd{simplify} on (1) or off (0). If $n$
! 679: is explicitly given, set simplify to $n$.
! 680:
! 681: \subseckbd{\#}: switches the \kbd{timer} on or off.
! 682:
! 683: \subseckbd{\#\#}: prints the time taken by the latest computation.
! 684: Useful when you forgot to turn on the \kbd{timer}.
! 685:
! 686: \section{Input formats for the PARI types}
! 687:
! 688: \noindent
! 689: Before describing more sophisticated functions in the next section, let us
! 690: see here how to input values of the different data types known to PARI.
! 691: Recall that blanks are ignored in any expression which is not a string (see
! 692: below).
! 693:
! 694: \subsec{Integers} \sidx{integer}
! 695: (type \typ{INT}\idxtyp{INT}): type the integer (with an initial
! 696: \kbd{+} or \kbd{-}, if desired) with no decimal point.
! 697:
! 698: \subsec{Real numbers} \sidx{real number}
! 699: (type \typ{REAL}\idxtyp{REAL}): type the number with a decimal
! 700: point. The internal precision of the real number will be the supremum of the
! 701: input precision and the default precision. For example, if the default
! 702: precision is 28 digits, typing \kbd{2.} will give a number with internal
! 703: precision 28, but typing a 45 significant digit real number will give a
! 704: number with internal precision at least 45 (although less may be printed).
! 705:
! 706: You can also use scientific notation with the letter \kbd{E} or
! 707: \kbd{e} (like \kbd{6.02 E 23} or \kbd{1e-5}).
! 708:
! 709: \subsec{Integermods}\sidx{integermod}
! 710: (type \typ{INTMOD}\idxtyp{INTMOD}): to enter $n \mod m$, type
! 711: \kbd{Mod(n,m)}, {\it not\/} \kbd{n\%m} (see Chapter~3).
! 712:
! 713: \subsec{Rational numbers}\sidx{rational number}
! 714: (types \typ{FRAC}\idxtyp{FRAC} and
! 715: \typ{FRACN}\idxtyp{FRACN}): under GP, all fractions are
! 716: automatically reduced to lowest terms, so it is in principle impossible to
! 717: work with reducible fractions (of type \typ{FRACN}), although of course in
! 718: library mode this is easy. To enter $n/m$ just type it as written. As
! 719: explained in \secref{se:gdiv}, division will {\it not\/} be performed, only
! 720: reduction to lowest terms.\label{se:FRAC}
! 721:
! 722: If you really want a reducible fraction under GP, you must use the \kbd{type}
! 723: function (see \secref{se:gptype}), by typing \kbd{type(x,FRACN)}. Be warned
! 724: however that this function must be used with extreme care.
! 725:
! 726: \subsec{Complex numbers}\sidx{complex number}
! 727: (type \typ{COMPLEX}\idxtyp{COMPLEX}): to enter $x+iy$, type \kbd{x + I*y}
! 728: ({\it not\/} \kbd{x+i*y}). The letter \kbd{\idx{I}} stands for
! 729: $\sqrt{-1}$. Recall from Chapter 1 that $x$ and $y$ can be of type
! 730: \typ{INT}, \typ{REAL}, \typ{INTMOD}, \typ{FRAC}/\typ{FRACN}, or
! 731: \typ{PADIC}.
! 732:
! 733: \subsec{$p$-adic numbers}\sidx{p-adic number}\label{se:padic}
! 734: (type \typ{PADIC}\idxtyp{PADIC}): to enter a $p$-adic number, simply write a
! 735: rational or integer expression and add to it \kbd{O($p$\pow $k$)}, where $p$
! 736: and $k$ are integers. This last expression indicates three things to GP:
! 737: first that it is dealing with a \typ{PADIC} type (the fact that $p$ is an
! 738: integer, and not a polynomial, which would be used to enter a series, see
! 739: \secref{se:series}), secondly the ``prime'' $p$ (note that it is not
! 740: checked whether $p$ is indeed prime; you can work on 10-adics if you want, but
! 741: beware of disasters as soon as you do something non-trivial like taking a
! 742: square root), and finally the number of significant $p$-adic digits $k$.
! 743: Note that \kbd{O(25)} is not the same as \kbd{O(5\pow 2)}; you probably
! 744: want the latter!
! 745:
! 746: For example, you can type in the $7$-adic number
! 747:
! 748: \kbd{2*7\pow(-1) + 3 + 4*7 + 2*7\pow 2 + O(7\pow3)}
! 749:
! 750: \noindent
! 751: exactly as shown, or equivalently as
! 752: \kbd{905/7 + O(7\pow3)}.
! 753:
! 754: \subsec{Quadratic numbers}\sidx{quadratic number}
! 755: (type \typ{QUAD}\idxtyp{QUAD}): first, you must define the
! 756: default quadratic order or field in which you want to work. This is done
! 757: using the \kbd{\idx{quadgen}} function, in the following way. Write something
! 758: like
! 759:
! 760: \kbd{w = quadgen(d)}
! 761:
! 762: \noindent
! 763: where \kbd{d} is the {\it discriminant\/} of the quadratic order in
! 764: which you want to work (hence $d$ is congruent to $0$ or $1$ modulo $4$). The
! 765: name \kbd{w} is of course just a suggestion, but corresponds to traditional
! 766: usage. You can of course use any variable name that you like. However,
! 767: quadratic numbers are always printed with a \kbd{w}, regardless of the
! 768: discriminant. So beware, two numbers can be printed in the same way and not
! 769: be equal. However GP will refuse to add or multiply them for example.
! 770:
! 771: Now $(1,w)$ will be the ``canonical'' integral basis of the quadratic order
! 772: (i.e.~$w=\sqrt{d}/2$ if $d\equiv 0 \mod 4$, and $w=(1+\sqrt{d})/2$ if
! 773: $d\equiv 1 \mod 4$, where $d$ is the discriminant), and to enter $x+yw$ you
! 774: just type \kbd{x + y*w}.
! 775:
! 776: \subsec{Polmods}\sidx{polmod} (type \typ{POLMOD}\idxtyp{POLMOD}): exactly as
! 777: for integermods, to enter $x \mod y$ (where $x$ and $y$ are polynomials),
! 778: type \kbd{Mod(x,y)}, not \kbd{x\%y} (see \secref{se:Mod}). Note that when $y$
! 779: is an irreducible polynomial in one variable, polmods whose modulus is $y$
! 780: are simply algebraic numbers in the finite extension defined by the
! 781: polynomial $y$. This allows us to work easily in \idx{number field}s, finite
! 782: extensions of the $p$-adic field $\Q_p$, or \idx{finite field}s.
! 783:
! 784: \label{se:rempolmod}
! 785: \misctitle{Important remark.} Since the variables\sidx{variable} occurring
! 786: in a polmod are not free variables, it is essential in order to avoid
! 787: inconsistencies that polmods use the same variable in internal operations
! 788: (i.e.~between polmods) and variables of lower priority (which have been
! 789: introduced later in the GP session) for external operations (typically
! 790: between a polynomial and a polmod). For example, PARI will not recognize
! 791: that \kbd{Mod(y, y\pow2 + 1)} is the same as \kbd{Mod(x, x\pow2 + 1)}.
! 792: Hopefully, this problem will pass away when type ``element of a number
! 793: field'' is eventually introduced.
! 794:
! 795: On the other hand, \kbd{Mod(x, x\pow2 + 1) + Mod(x, x\pow2 + 1)}
! 796: (which gives \kbd{Mod(2*x, x\pow2 + 1)}) and \kbd{x + Mod(y, y\pow2 + 1)}
! 797: (which gives a result mathematically equivalent to $\kbd{x} + i$ with
! 798: $i^2=-1$) are completely correct, while \kbd{y + Mod(x, x\pow2 + 1)}
! 799: gives \kbd{Mod(x + y, x\pow2 + 1)}, which may not be what you want (\kbd{y}
! 800: is treated here as a numerical parameter, not as a polynomial variable).
! 801:
! 802: \misctitle{Note (added in version 2.0.16)} As long as the main variables
! 803: are the same, it is allowed to mix \typ{POL} and \typ{POLMOD}s. The result
! 804: will be the expected \typ{POLMOD}. For instance \kbd{x + Mod(x, x\pow2 +
! 805: 1)} is equal to \kbd{Mod(2*x, x\pow2 + 1)}. This wasn't the case prior to
! 806: version 2.0.16: it returned a polynomial in \kbd{x} equivalent to $\kbd{x}
! 807: + i$, which was in fact an invalid object (you couldn't \kbd{lift} it).
! 808:
! 809: \subsec{Polynomials}\sidx{polynomial}\label{se:pol}
! 810: (type \typ{POL}\idxtyp{POL}): type the polynomial in a natural way, not
! 811: forgetting to put a ``$*$'' between a coefficient and a formal variable
! 812: (this $*$ does not appear in beautified output). Any \idx{variable} name
! 813: can be used except for the reserved names \kbd{I} (used exclusively for the
! 814: square root of $-1$), \kbd{Pi} ($3.14\dots$), \kbd{Euler} (Euler's
! 815: constant), and all the function names: predefined functions, as described
! 816: in Chapter~3 (use \b{c} to get the complete list of them) and user-defined
! 817: functions, which you ought to know about (use \b{u} if you are subject to
! 818: memory lapses). The total number of different variable names is limited to
! 819: $16384$ and $65536$ on 32-bit and 64-bit machines respectively, which
! 820: should be enough. If you ever need hundreds of variables, you should
! 821: probably be using vectors instead.
! 822:
! 823: \subsec{Power series}\sidx{power series}\label{se:series}
! 824: (type \typ{SER}\idxtyp{SER}): type a rational function or
! 825: polynomial expression and add to it \hbox{\kbd{O({\it expr\/} \pow $k$)}},
! 826: where {\it expr\/} is an expression which has non-zero valuation (it can be a
! 827: polynomial, power series, or a rational function; the most common case being
! 828: simply a variable name).
! 829: This indicates to GP that it is dealing with a power series, and the desired
! 830: precision is $k$ times the valuation of {\it expr\/} with respect to the
! 831: main variable of {\it expr\/} (to check the ordering of the variables, or
! 832: to modify it, use the function \kbd{reorder}; see~\secref{se:reorder}).
! 833:
! 834: \subsec{Rational functions}\sidx{rational function}
! 835: (types \typ{RFRAC}\idxtyp{RFRAC} and
! 836: \typ{RFRACN}\idxtyp{RFRACN}): as for fractions, all rational
! 837: functions are automatically reduced to lowest terms under GP. All that was
! 838: said about fractions in \secref{se:FRAC} remains valid here.
! 839:
! 840: \subsec{Binary quadratic forms of positive or negative discriminant}%
! 841: \sidx{binary quadratic forms}
! 842: (type \typ{QFR}\idxtyp{QFR} and \typ{QFI}\idxtyp{QFI}):
! 843: these are input using the function \kbd{Qfb} (see Chapter~3). For example
! 844: \kbd{Qfb(1,2,3)} will create the binary form $x^2+2xy+3y^2$. It will be
! 845: imaginary (of internal type \typ{QFI}) since $2^2 - 4*3 = -8$ is negative.
! 846:
! 847: In the case of forms with positive discriminant (type \typ{QFR}), you
! 848: may add an optional fourth component (related to the regulator, more
! 849: precisely to Shanks and Lenstra's ``distance''), which must be a real number.
! 850: See also the function \kbd{qfbprimeform} which directly creates a prime form
! 851: of given discriminant (see Chapter~3).
! 852:
! 853: \subsec{Row and column vectors}\sidx{row vector}\sidx{column vector} (types
! 854: \typ{VEC}\idxtyp{VEC} and \typ{COL}\idxtyp{COL}): to
! 855: enter a row vector, type the components separated by commas ``\kbd{,}'', and
! 856: enclosed between brackets ``\kbd{[}$\,$'' and ``$\,$\kbd{]}'', e.g.~%
! 857: \kbd{[1,2,3]}. To enter a column vector, type the vector horizontally, and
! 858: add a tilde ``\til'' to transpose. \kbd{[ ]} yields the empty (row) vector.
! 859: The function \tet{Vec} can be used to transform any object into a vector (see
! 860: Chapter~3).
! 861:
! 862: \subsec{Matrices} (type \typ{MAT}\idxtyp{MAT}):\sidx{matrix} to
! 863: enter a matrix, type the components line by line, the components being
! 864: separated by commas ``\kbd{,}'', the lines by semicolons ``\kbd{;}'', and
! 865: everything enclosed in brackets ``\kbd{[}$\,$'' and ``$\,$\kbd{]}'', e.g.
! 866: \kbd{[x,y; z,t; u,v]}. \kbd{[ ; ]} yields the empty (0x0) matrix. The
! 867: function \tet{Mat} can be used to transform any object into a matrix (see
! 868: Chapter 3).
! 869:
! 870: Note that although the internal representation is essentially the same (only
! 871: the type number is different), a row vector of column vectors is {\it not\/}
! 872: a matrix; for example, multiplication will not work in the same way.
! 873:
! 874: Note also that it is possible to create matrices (by conversion of empty
! 875: column vectors and concatenation, or using the \kbd{matrix} function) with a
! 876: given positive number of columns, each of which has zero rows. It is not
! 877: possible to create or represent matrices with zero columns and a nonzero
! 878: number of rows.
! 879:
! 880: \subsec{Lists} (type \typ{LIST})\idxtyp{LIST}:\sidx{list}
! 881: lists cannot be input directly; you have to use the function
! 882: \kbd{listcreate} first, then \kbd{listput} each time you want to append a
! 883: new element (but you can access the elements directly as with the
! 884: vector types described above). The function \kbd{List} can be used to
! 885: transform (row or column) vectors into lists (see Chapter~3).
! 886:
! 887: \subsec{Strings} (type \typ{STR})\idxtyp{STR}:\sidx{string}%
! 888: \sidx{character string} to enter a string, just enclose it between double
! 889: quotes \kbd{"}, like this: \kbd{"this is a string"}. The function \kbd{Str}
! 890: can be used to transform any object into a string (see Chapter~3).
! 891:
! 892: \section{GP operators}\label{se:operators}
! 893:
! 894: \noindent
! 895: Loosely speaking, an \idx{operator} is a function (usually associated to
! 896: basic arithmetic operations) whose name contains only non-alphanumeric
! 897: characters. In practice, most of these are simple functions, which take
! 898: arguments, and return a value; assignment operators also have side effects.
! 899: Each of these has some fixed and unchangeable priority, which means that,
! 900: in a given expression, the operations with the highest priority will be
! 901: performed first. Operations at the same priority level will always be
! 902: performed in the order they were written, i.e.~from left to right. Anything
! 903: enclosed between parenthesis is considered a complete subexpression, and
! 904: will be resolved independently of the surrounding context. For instance,
! 905: assuming that {\it op}$_1$, {\it op}$_2$, {\it op}$_3$ are standard binary
! 906: operators with increasing priorities (think of \kbd{+}, \kbd{*}, \kbd{\pow}
! 907: for instance),
! 908: $$ x~\hbox{\it op}_1~y~\hbox{\it op}_2~z~\hbox{\it op}_2~x~\hbox{\it op}_3~y $$
! 909: is equivalent to
! 910: $$ x~\hbox{\it op}_1~((y~\hbox{\it op}_2~z)~\hbox{\it op}_2~
! 911: (x~\hbox{\it op}_3~y)).$$
! 912:
! 913: GP knows quite a lot of different operators, some of them unary (having
! 914: only one argument), some binary. Unary operators are defined for either
! 915: prefix (preceding their single argument: {\it op\/}~$x$) or postfix (following
! 916: the argument: $x$~{\it op\/}) position, never both
! 917: (some are syntactically correct in both positions, but with different
! 918: meanings). Binary operators all use the syntax $x$~{\it op\/}~$y$. Most of
! 919: them are well known, some are borrowed from C~syntax, and a few are specific
! 920: to GP. Beware that some GP operators may differ slightly from their C
! 921: counterparts. For instance, GP's postfix \kbd{++} returns the {\it new\/}
! 922: value, like the prefix \kbd{++} of~C, and the binary shifts \kbd{<<},
! 923: \kbd{>>} have a priority which is different from (higher than) that of
! 924: their C counterparts.
! 925: When in doubt, just surround everything by parentheses (besides, your code
! 926: will probably be more legible).
! 927:
! 928: \noindent Here is the complete list (in order of decreasing priority, binary
! 929: unless mentioned otherwise):
! 930:
! 931: \sidx{priority}
! 932: \def\point#1{\noindent $\bullet$ #1\hfill\break\indent\strut}
! 933: \point{Priority 9}
! 934: %
! 935: \kbd{++} and \kbd{--} (unary, postfix): \kbd{$x$++} assigns the value $x+1$ to
! 936: $x$, then returns the new value of $x$. This corresponds to the C
! 937: statement \kbd{++$x$} (there is no prefix \kbd{++} operator in GP).
! 938: \kbd{$x$--} does the same with $x-1$.
! 939:
! 940: \point{Priority 8}
! 941: %
! 942: \kbd{{\it op\/}=}, where {\it op\/} is any simple binary operator
! 943: (i.e.~a binary operator with no side effects, i.e.~one of those defined below)
! 944: which is not a boolean operator (comparison or logical).
! 945: \kbd{x~{\it op\/}=~$y$} assigns $(\kbd{x}~{\it op\/}~y)$ to~\kbd{x},
! 946: and returns the new value of~\kbd{x}, {\it not\/} a reference to the
! 947: \idx{variable}~\kbd{x}. (Thus an assignment cannot occur on the lefthand
! 948: side of another assignment.)
! 949:
! 950: \point{Priority 7}
! 951: %
! 952: \kbd{=} is the assignment operator. The result of \kbd{x~=~$y$} is the value
! 953: of the expression~$y$, which is also assigned to the variable~\kbd{x}. This
! 954: is {\it not\/} the equality test operator. Beware that a statement like
! 955: \kbd{x~=~1} is always true (i.e.~non-zero), and sets \kbd{x} to~1.
! 956:
! 957: \point{Priority 6}
! 958: %
! 959: \kbd{!} (unary, prefix): logical {\it not}. \kbd{!$x$} return $1$ if $x$ is
! 960: equal to $0$ (specifically, if \kbd{gcmp0($x$)==1}), and $0$ otherwise.
! 961:
! 962: \kbd{'} (unary, prefix): quote its argument without evaluating it.
! 963: \bprog%
! 964: ? a = x + 1; x = 1;
! 965: ? subst(a,x,1)
! 966: \ \ ***\ \ \ variable name expected: subst(a,x,1)
! 967: \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \pow---
! 968: ? subst(a,'x,1)
! 969: \%1 = 2
! 970: \eprog
! 971:
! 972: \point{Priority 5}
! 973: %
! 974: \kbd{\pow}: powering.
! 975:
! 976: \kbd{'} (unary, postfix): derivative with respect to the main variable.
! 977:
! 978: \strut\kbd{\til} (unary, postfix): vector/matrix transpose.
! 979:
! 980: \kbd{!} (unary, postfix): factorial. $x\kbd{!}=x(x-1)\cdots 1$.
! 981:
! 982: \kbd{.}: \kbd{$x$.$b$} extracts member $b$ from structure $x$.
! 983:
! 984: \point{Priority 4}
! 985: %
! 986: \kbd{+}, \kbd{-} (unary, prefix): \kbd{-} toggles the sign of its argument,
! 987: \kbd{+} has no effect whatsoever.
! 988:
! 989: \point{Priority 3}
! 990: %
! 991: \kbd{*}: multiplication.
! 992:
! 993: \kbd{/}: exact division (\kbd{3/2}=$3/2$, not $1.5$).
! 994:
! 995: \kbd{\bs}, \kbd{\%}: euclidean quotient and remainder, i.e.~if $x =
! 996: qy + r$, with $0\le r < y$ (if $x$ and $y$ are polynomials, assume instead
! 997: that $\deg r< \deg y$ and that the leading terms of $r$ and $x$ have the
! 998: same sign), then $\kbd{x \b{ } y} = q$, $\kbd{x\%y} = r$.
! 999:
! 1000: \kbd{\bs/}: rounded euclidean quotient for integers (rounded towards
! 1001: $+\infty$ when the exact quotient would be a half-integer).
! 1002:
! 1003: \kbd{<<}, \kbd{>>}: left and right binary shift: \kbd{x<<n}$~=~x * 2^n$
! 1004: if $n>0$, and $x \b{/} 2^{-n}$ otherwise; and
! 1005: \kbd{x>>n}$~=~$\kbd{x<<(-n)}.
! 1006:
! 1007: \point{Priority 2}
! 1008: %
! 1009: \kbd{+}, \kbd{-}: addition/subtraction.
! 1010:
! 1011: \point{Priority 1}
! 1012: %
! 1013: \kbd{<}, \kbd{>}, \kbd{<=}, \kbd{>=}: the usual comparison operators,
! 1014: returning 1 for \kbd{true} and 0 for \kbd{false}. For instance,
! 1015: \kbd{x<=1} returns $1$ if $x\le 1$ and $0$ otherwise.
! 1016:
! 1017: \kbd{<>}, \kbd{!=}: test for (exact) inequality.
! 1018:
! 1019: \kbd{==}: test for (exact) equality.
! 1020:
! 1021: \point{Priority 0}
! 1022: %
! 1023: \kbd{\&}, \kbd{\&\&}: logical {\it and}.
! 1024:
! 1025: \kbd{|}, \kbd{||}: logical (inclusive) {\it or}. Any sequence of logical
! 1026: {\it or\/} and {\it and\/} operations is evaluated from left to right,
! 1027: and aborted as soon as the final truth value is known. Thus, for instance,
! 1028: \kbd{(x \&\& 1/x)} or \kbd{(type(p) == "t\_INT" \&\& isprime(p))} will never
! 1029: produce an error since the second argument need not (and will not) be processed
! 1030: when the first is already zero (false).
! 1031:
! 1032: \misctitle{Remark:} For the sake of efficiency, you should use the
! 1033: \kbd{++}, \kbd{--} and {\it op\/}\kbd{=} operators whenever possible:
! 1034:
! 1035: \bprog%
! 1036: ? a=200000;
! 1037: ? i=0; while(i<a, i=i+1)
! 1038: time = 4,919 ms.
! 1039: ? i=0; while(i<a, i+=1)
! 1040: time = 4,478 ms.
! 1041: ? i=0; while(i<a, i++)
! 1042: time = 3,639 ms.
! 1043: \eprog
! 1044:
! 1045: \noindent The shift operators should be preferred to multiplication
! 1046: whenever possible:
! 1047:
! 1048: \bprog%
! 1049: ? a=1<<20000;
! 1050: ? i=1; while(i<a, i=i*2);
! 1051: time = 5,255 ms.
! 1052: ? i=1; while(i<a, i<<=1);
! 1053: time = 988 ms.
! 1054: \eprog
! 1055:
! 1056: \section{The general GP input line}
! 1057: \subsec{Generalities}. User interaction with a GP session proceeds as
! 1058: follows: a sequence of characters is typed by the user at the GP prompt. This
! 1059: can be either a \b~command, a function definition, an expression, or a
! 1060: sequence of expressions (i.e.~a program). In the latter two cases, after the
! 1061: last expression has been computed its result is put into an internal
! 1062: (``history'') array, and printed. The successive elements of this array are
! 1063: called \kbd{\%1}, \kbd{\%2}, \dots As a shortcut, the latest computed
! 1064: expression can also be called \kbd{\%}, the previous one \kbd{\%`}, the one
! 1065: before that \kbd{\%``} and so on.
! 1066:
! 1067: If you want to suppress the printing of the result, for example because it
! 1068: is a long unimportant intermediate result, end the expression with a
! 1069: \kbd{;} sign. This same sign is used as an instruction separator when several
! 1070: instructions are written on the same line (note that for the pleasure of BASIC
! 1071: addicts, the \kbd{:} sign can also be used, but we will try to stick to
! 1072: C-style conventions in this manual). The final expression computed, even
! 1073: if not printed, will still be assigned to the history array, so you may have
! 1074: to pay close attention when you intend to refer back to it by number since
! 1075: this number does not appear explicitly. Of course, if you just want to use
! 1076: it on the next line, use \kbd{\%} as usual.
! 1077:
! 1078: Any legal expression can be typed in, and is evaluated using the
! 1079: conventions about operator priorities and left to right associativity (see
! 1080: the previous section), using the available operator symbols, function names
! 1081: (including user-defined functions and member functions see
! 1082: \secref{se:user_defined}), and special variables. Please note that, from
! 1083: version $1.900$ on, there\sidx{case distinction} {\it is\/} a distinction
! 1084: between lowercase and uppercase. Also, note that, outside of constant
! 1085: strings, blanks are completely ignored in the input to GP.
! 1086:
! 1087: The special variable\idx{variable (special)} names known to GP are
! 1088: \kbd{\idx{Euler}} (Euler's constant $\gamma=0.577\dots$), \kbd{\idx{I}}
! 1089: (the square root of $-1$), \kbd{\idx{Pi}} (3.14\dots)~--- which could be
! 1090: thought of as functions with no arguments, and which may therefore be
! 1091: invoked without parentheses~---, and \kbd{\idx{O}} which obeys the
! 1092: following syntax:
! 1093:
! 1094: \kbd{O({\it expr\/}\pow k)}
! 1095:
! 1096: \noindent
! 1097: When {\it expr\/} is an integer or a rational number, this creates an
! 1098: {\it expr}-adic number (zero in fact) of precision \kbd{k}. When {\it expr\/}
! 1099: is a polynomial, a power series or a rational function whose main variable is
! 1100: $X$, say, this creates a power series (also zero) of precision $v*\kbd{k}$
! 1101: where $v$ is the $X$-adic valuation of {\it expr\/} (see \ref{se:padic}
! 1102: and~\ref{se:pol}).
! 1103:
! 1104: \subsec{Special editing characters}.\sidx{editing characters} A GP program
! 1105: can of course have more than one line. Since GP executes your commands as
! 1106: soon as you have finished typing them, there must be a way to tell it to
! 1107: wait for the next line or lines of input before doing anything. There are
! 1108: three ways of doing this.
! 1109:
! 1110: The first one is simply to use the \idx{backslash character} \kbd{\bs} at the
! 1111: end of the line that you are typing, just before hitting \kbd{<Return>}. This
! 1112: tells GP that what you will write on the next line is the physical
! 1113: continuation of what you have just written. In other words, it makes GP
! 1114: forget your newline character. For example if you use this while defining a
! 1115: function, and if you ask for the definition of the function using
! 1116: \kbd{?name}, you will see that your backslash has disappeared and that
! 1117: everything is on the same line. You can type a \kbd{\bs} anywhere. It will be
! 1118: interpreted as above only if (apart from ignored whitespace characters) it is
! 1119: immediately followed by a newline. For example, you can type
! 1120:
! 1121: \bprog%
! 1122: ? 3 + \bs
! 1123: 4%
! 1124: \eprog
! 1125:
! 1126: \noindent instead of typing \kbd{3 + 4}.
! 1127:
! 1128: The second one is a slight variation on the first, and is mostly useful when
! 1129: defining a user function (see \secref{se:user_defined}): since an equal sign
! 1130: can never end a valid expression, GP will disregard a newline immediately
! 1131: following an \kbd{=}.
! 1132:
! 1133: \bprog%
! 1134: ? a =
! 1135: 123
! 1136: \%1 = 123
! 1137: \eprog
! 1138:
! 1139: The third one cannot be used everywhere, but is in general much more useful.
! 1140: It is the use of braces \kbd{\obr} and \kbd{\cbr}.\sidx{brace characters}
! 1141: When GP sees an opening brace (\kbd{\obr}) {\it at the beginning of a line}
! 1142: (modulo spaces as usual), it understands that you are typing a multi-line
! 1143: command, and newlines will be ignored until you type a closing brace
! 1144: \kbd{\cbr}. However, there is an important (but easily obeyed) restriction:
! 1145: inside an open brace-close brace pair, all your input lines will be
! 1146: concatenated, suppressing any newlines. Thus, all newlines should occur after
! 1147: a semicolon (\kbd{;}), a comma (\kbd{,}) or an operator (for clarity's sake,
! 1148: we don't recommend splitting an identifier over two lines in this way). For
! 1149: instance, the following program
! 1150:
! 1151: \bprog
! 1152: \obr
! 1153: \q a = b
! 1154: \q b = c
! 1155: \cbr
! 1156: \eprog
! 1157:
! 1158: \noindent would silently produce garbage, since what GP will really see is
! 1159: \kbd{a=bb=c} which will assign the value of \kbd{c} to both \kbd{bb} and
! 1160: \kbd{a} (if this really is what you intended, you're a hopeless case).
! 1161:
! 1162: \section{The GP/PARI programming language}
! 1163:
! 1164: The GP calculator uses a purely interpreted language. The structure of this
! 1165: language is reminiscent of LISP with a functional notation, \kbd{f(x,y)}
! 1166: rather than \kbd{(f x y)}: all \idx{programming} constructs, such as
! 1167: \kbd{if}, \kbd{while,} etc... are functions \footnote{*}{Not exactly, since
! 1168: not all their arguments need be evaluated. For instance it would be stupid
! 1169: to evaluate both branches of an \kbd{if} statement: since only one will
! 1170: apply, GP only expands this one.} (see \secref{se:programming} for a
! 1171: complete list), and the main loop does not really execute, but rather
! 1172: evaluates (sequences of) expressions. Of course, it is by no means a true
! 1173: LISP.
! 1174:
! 1175: \subsec{Variables and symbolic expressions}.\sidx{variable}
! 1176:
! 1177: In GP you can use up to 16383 variable names (up to 65535 on 64-bit
! 1178: machines). These names can be any standard identifier names, i.e.~they must
! 1179: start with a letter and contain only valid keyword characters: \kbd{\_} or
! 1180: alphanumeric characters ([\kbd{\_A-Za-z0-9}]). To avoid confusion with other
! 1181: symbols, you must not use other non-alphanumeric symbols like \kbd{\$}, or
! 1182: '\kbd{.}'. In addition to the function names which you must not use (see the
! 1183: list with \b{c}), there are exactly three special variable names which you
! 1184: are not allowed to use: \kbd{Pi} and \tet{Euler}, which represent well known
! 1185: constants, and $\kbd{I}=\sqrt{-1}$.
! 1186:
! 1187: Note that GP names are case sensitive since version 1.900. This means for
! 1188: instance that the symbol \kbd{i} is perfectly safe to use, and will not be
! 1189: mistaken for $\sqrt{-1}$, and that \kbd{o} is not synonymous anymore to
! 1190: \kbd{O}. If you grew addicted to the previous behaviour, you can have it back
! 1191: by setting the default \kbd{compatible} to $3$.
! 1192:
! 1193: Now the main thing to understand is that PARI/GP is {\it not\/} a symbolic
! 1194: manipulation package, although it shares some of the functionalities. One of
! 1195: the main consequences of this fact is that all expressions are evaluated as
! 1196: soon as they are written, they never stay in a purely abstract form%
! 1197: \footnote{**}{An obvious but important exception are character strings which
! 1198: are evaluated\dots\ essentially to themselves (type \typ{STR}). Not exactly
! 1199: so though, since we do some work to treat the quoted characters correctly
! 1200: (those preceded by a \b{)}.}.
! 1201: %
! 1202: As an important example, consider what happens when you use a variable name
! 1203: {\it before\/} assigning a value into it. This is perfectly acceptable to GP,
! 1204: which considers this variable in fact as a polynomial of degree 1, with
! 1205: coefficients 1 in degree 1, 0 in degree 0, whose variable is the variable
! 1206: name you used.
! 1207:
! 1208: If later you assign a value to that variable, the objects which you have
! 1209: created before will still be considered as polynomials. If you want to obtain
! 1210: their value, use the function \kbd{eval} (see \secref{se:eval}).
! 1211:
! 1212: Finally, note that if the variable $x$ contains a vector or list, you can
! 1213: assign a result to $x[m]$ (i.e.~write something like $x[k]=\var{expr}$). If
! 1214: $x$ is a matrix, you can assign a result to $x[m,n]$, but {\it not\/} to
! 1215: $x[m]$. If you want to assign an expression to the $m$-th column of a matrix
! 1216: $x$, use $x[,m]=\var{expr}$ instead. Similarly, use $x[m,]=\var{expr}$ to
! 1217: assign an expression to the $m$-th row of $x$. This process is recursive, so
! 1218: if $x$ is a matrix of matrices of \dots, an expression such as
! 1219: $x[1,1][,3][4]=1$ would be perfectly valid (assuming of course that all
! 1220: matrices along the way have the correct dimensions).
! 1221:
! 1222: \misctitle{Note:} We'll see in \secref{se:user_defined} that it is possible
! 1223: to restrict the use of a given variable by declaring it to be \tet{global} or
! 1224: \tet{local}. This can be useful to enforce clean programming style, but is in
! 1225: no way mandatory.
! 1226:
! 1227: \misctitle{(Technical) Note:} Variables are numbered in the order that they
! 1228: appear since the beginning of the session, and the main variable of an
! 1229: expression is always the lowest numbered variable. Hence if you are working
! 1230: with expressions involving several variables and want to have them ordered in
! 1231: a specific manner {\it in the internal representation}, the simplest is just
! 1232: to write down the variables one after the other under GP before starting any
! 1233: real computations. If you already have started working and want to change the
! 1234: names of the variables in an object, use the function \tet{changevar}. If you
! 1235: only want to have them ordered when the result is printed, you can also use
! 1236: the function \tet{reorder}, but this won't change anything to the internal
! 1237: representation.
! 1238:
! 1239: \misctitle{(Very technical) Note:}
! 1240: Each variable has a stack of values, implemented as a linked list. When a new
! 1241: scope is entered (during a function call which uses it as a parameter, or if
! 1242: the variable is used as a loop index, see \secref{se:user_defined} and
! 1243: \secref{se:programming}), the value of the actual parameter is pushed on the
! 1244: stack. If the parameter is not supplied, a special $0$ value called
! 1245: \teb{gnil} is pushed on the stack (this value is not printed if it is
! 1246: returned as the result of a GP expression sequence). Upon exit, the stack
! 1247: decreases. You can \kbd{kill} a variable, decreasing the stack yourself. This
! 1248: should be used only at the top level of GP, to undo the effect of an
! 1249: assignment, not from a function. However, the stack has a bottom: the value
! 1250: of a variable is the monomial of degree 1 in this variable, as is natural for
! 1251: a mathematician.
! 1252:
! 1253: \subsec{Expressions and expression sequences}.
! 1254:
! 1255: An \idx{expression}\sidx{expression sequence} is formed by combining the
! 1256: GP operators, functions (including user-defined functions, see below) and
! 1257: control statements. It may be preceded by an assignment statement '$=$'
! 1258: into a variable. It always has a value, which can be any PARI object.
! 1259:
! 1260: Several expressions can be combined on a single line by separating them
! 1261: with semicolons (';') and also with colons (':') for those who are used to
! 1262: BASIC. Such an expression sequence will be called simply a \var{seq}. A
! 1263: \var{seq} also has a value, which is the value of the last non-empty
! 1264: expression in the sequence. Under GP, the value of the \var{seq}, and only
! 1265: this last value, is always put on the stack (i.e. it will become the next
! 1266: object $\%n$). The values of the other expressions in the \var{seq} are
! 1267: discarded after the execution of the \var{seq} is complete, except of
! 1268: course if they were assigned into variables. In addition, the value of
! 1269: the \var{seq} (or of course of an expression if there is only one) is
! 1270: printed if the line does not end with a semicolon (';').
! 1271:
! 1272: \subsec{User defined functions}.\sidx{user defined functions}
! 1273: \label{se:user_defined}
! 1274:
! 1275: It is very easy to define a new function under GP, which can then be used
! 1276: like any other function. The syntax is as follows:
! 1277:
! 1278: \kbd{name(list of formal variables) = local(list of local variables); \var{seq}}
! 1279:
! 1280: \noindent which looks better written on consecutive lines:
! 1281: \bprog% name($x_0$, $x_1$, \dots) =
! 1282: \obr
! 1283: \q local($t_0$, $t_1$, \dots);
! 1284: \q local(\dots);
! 1285: \q
! 1286: \q \dots
! 1287: \cbr
! 1288: \eprog
! 1289: \noindent (note that the first newline is disregarded due to the preceding
! 1290: \kbd{=} sign, and the others because of the enclosing braces). Both lists
! 1291: of variables are comma-separated and allowed to be empty. The \tet{local}
! 1292: statements can be omitted; as usual \var{seq} is any expression sequence.
! 1293:
! 1294: \kbd{name} is the name given to the function and is subject to the same
! 1295: restrictions as variable names. In addition, variable names are not valid
! 1296: function names, you have to \kbd{kill} the variable first (the converse is
! 1297: true: function names can't be used as variables, see \secref{se:kill}).
! 1298: Previously used function names can be recycled: you are just redefining the
! 1299: function (the previous definition is lost of course).
! 1300:
! 1301: \kbd{list of formal variables} is the list of variables corresponding to
! 1302: those which you will actually use when calling your function. The number of
! 1303: actual parameters supplied when calling the function has to be less than the
! 1304: number of formal variables.
! 1305:
! 1306: Uninitialized formal variables will be given a default value. An equal
! 1307: (\kbd{=}) sign following a variable name in the function definition,
! 1308: followed by any expression, gives the variable a default value. The
! 1309: expression gets evaluated the moment the function is defined, and is fixed
! 1310: afterward. A variable for which you supply no default value will be
! 1311: initialized to zero.
! 1312:
! 1313: \kbd{list of local variables} is the list of the additional local variables
! 1314: which are used in the function body. Note that if you omit some or all of
! 1315: these local variable declarations, the non-declared variables will become
! 1316: global, hence known outside of the function, and this may have undesirable
! 1317: side-effects. On the other hand, in some cases it may also be what you want.
! 1318: Local variables can be given a default value as the formal variables.
! 1319:
! 1320: \misctitle{Example:} For instance \kbd{foo(x=1,y=2,z=3) = print(x ":" y ":"
! 1321: z)}, defines a function which prints its arguments (at most three of them),
! 1322: separated by colons. This then follows the rules of default arguments
! 1323: generation as explained at the beginning of \secref{se:functions}.
! 1324:
! 1325: \bprog%
! 1326: ? foo(6,7)
! 1327: 6:7:3
! 1328: ? foo(,5)
! 1329: 1:5:3
! 1330: ? foo
! 1331: 1:2:3
! 1332: \eprog
! 1333:
! 1334: Once the function is defined using the above syntax, you can use it like
! 1335: any other function. In addition, you can also recall its definition exactly
! 1336: as you do for predefined functions, that is by writing \kbd{?\var{name}}.
! 1337: This will print the list of arguments, as well as their default values,
! 1338: the text of \var{seq}, and a short help text if one was provided using
! 1339: the \kbd{addhelp} function (see \secref{se:addhelp}). One small difference
! 1340: to predefined functions is that you can never redefine the built-in
! 1341: functions, while you can redefine a user-defined function as many times
! 1342: as you want.
! 1343:
! 1344: Typing \b{u} will output the list of user-defined functions.
! 1345:
! 1346: An amusing example of a user-defined function is the following. It is
! 1347: intended to illustrate both the use of user-defined functions and the power
! 1348: of the \kbd{sumalt} function. Although the \idx{Riemann zeta-function} is
! 1349: included in the standard functions, let us assume that this is not the case
! 1350: (or that we want another implementation). One way to define it, which is
! 1351: probably the simplest (but certainly not the most efficient), is as
! 1352: follows:
! 1353:
! 1354: \sidx{zeta function}
! 1355: \bprog%
! 1356: zet(s) =
! 1357: \obr
! 1358: \q local(j); /* not needed, and possibly confusing (see below) */
! 1359: \q sumalt(j=1, (-1)\pow(j-1)*j\pow(-s)) / (1 - 2\pow(1-s))
! 1360: \cbr
! 1361: \eprog
! 1362:
! 1363: \noindent This gives reasonably good accuracy and speed as long as you are
! 1364: not too far from the domain of convergence. Try it for $s$ integral between
! 1365: $-5$ and $5$, say, or for $s=0.5+i*t$ where $t=14.134\dots$
! 1366:
! 1367: The iterative constructs which use a variable name (\kbd{for$xxx$},
! 1368: \kbd{prod$xxx$}, \kbd{sum$xxx$}, \kbd{vector}, \kbd{matrix}, \kbd{plot},
! 1369: etc.) also consider the given variable to be local to the construct. A value
! 1370: is pushed on entry and pulled on exit. So, it is not necessary for a function
! 1371: using such a construct to declare the variable as a dummy formal parameter.
! 1372:
! 1373: In particular, since loop variables are not visible outside their loops,
! 1374: the variable \kbd{j} need not be declared in the protoype of our \kbd{zet}
! 1375: function above.
! 1376:
! 1377: \kbd{zet(s) = sumalt(j=1, (-1)\pow(j-1)*j\pow(-s)) / (1 - 2\pow(1-s))}
! 1378:
! 1379: \noindent would be a perfectly sensible (and in fact better) definition.
! 1380: Since local/global scope is a very tricky point, here's one more example.
! 1381: What's wrong with the following definition?
! 1382: \bprog%
! 1383: ? first\_prime\_div(x) =
! 1384: \obr
! 1385: \q local(p);
! 1386: \q forprime(p=2, x, if (x\%p == 0, break));
! 1387: \q p
! 1388: \cbr
! 1389: ? first\_prime\_div(10)
! 1390: \%1 = 0
! 1391: \eprog
! 1392:
! 1393: \misctitle{Answer:} the index $p$ in the \kbd{forprime} loop is local to
! 1394: the loop and is not visible to the outside world. Hence, it doesn't survive
! 1395: the \kbd{break} statement. More precisely, at this point the loop index is
! 1396: restored to its preceding value, which is 0 (local variables are
! 1397: initialized to 0 by default). To sum up, the routine returns the $p$
! 1398: declared local to it, not the one which was local to \kbd{forprime} and ran
! 1399: through consecutive prime numbers. Here's a corrected version:
! 1400:
! 1401: \bprog%
! 1402: ? first\_prime\_div(x) = forprime(p=2, x, if (x\%p == 0, return(p)))
! 1403: \eprog
! 1404:
! 1405: Again, it is strongly recommended to declare all other local variables that
! 1406: are used inside a function: if a function accesses a variable which is not
! 1407: one of its formal parameters, the value used will be the one which happens to
! 1408: be on top of the stack at the time of the call. This could be a ``global''
! 1409: value, or a local value belonging to any function higher in the call chain.
! 1410: So, be warned.
! 1411:
! 1412: There's no problem with recursive functions as long as one pays proper
! 1413: attention to variable scope. Here's a last example, used to retrieve the
! 1414: coefficient array of a multivariate polynomial (a non-trivial task due to
! 1415: PARI's unsophisticated representation for those objects)~:
! 1416: \sidx{multivariate polynomial}
! 1417:
! 1418: \bprog%
! 1419: coeffs(P, nbvar) =
! 1420: \obr
! 1421: \q local(v);
! 1422: \h
! 1423: \q if (type(P) != "t\_POL",
! 1424: \q\q for (i=0, nbvar-1, P = [P]);
! 1425: \q\q return (P)
! 1426: \q );
! 1427: \q v = vector(poldegree(P)+1, i, polcoeff(P,i-1));
! 1428: \q vector(length(v), i, coeffs(v[i], nbvar-1))
! 1429: \cbr
! 1430: \eprog
! 1431:
! 1432: \noindent If $P$ is a polynomial in $k$ variables, show that after the
! 1433: assignment {\tt v = coeffs(P,k)}, the coefficient of $x_1^{n_1}\dots
! 1434: x_k^{n_k}$ in P is given by {\tt v[$n_1$+1][\dots][$n_k$+1]}. What would
! 1435: happen if the declaration {\tt local(v)} had been omitted ?
! 1436:
! 1437: \misctitle{Function which take functions as parameters ?} This is easy
! 1438: in GP using the following trick (neat example due to Bill Daly):
! 1439:
! 1440: \bprog%
! 1441: calc(f, x) = eval(Str( f "(x)"))
! 1442: \eprog
! 1443:
! 1444: \noindent If you call this with \kbd{calc("sin", 1)}, it will
! 1445: return $\sin(1)$ (evaluated!).
! 1446:
! 1447: \misctitle{Restrictions on variable use:} it is not allowed to use the same
! 1448: variable name for different parameters of your function. Or to use a given
! 1449: variable both as a formal parameter and a local variable in a given function.
! 1450: Hence
! 1451: \bprog%
! 1452: ? f(x,x) = 1
! 1453: \q *** user function f: variable x declared twice.
! 1454: \eprog
! 1455:
! 1456: Also, the statement \kbd{\idx{global}(x, y, z, t)} (see \secref{se:global})
! 1457: declares the corresponding variables to be global. It is then forbidden to
! 1458: use them as formal parameters or loop indexes as described above, since the
! 1459: parameter would ``shadow'' the variable.
! 1460:
! 1461: \misctitle{Implementation note.} For the curious reader, here is how these
! 1462: stacks are handled: a \idx{hashing function} is computed from the identifier,
! 1463: and used as an index in \tet{hashtable}, a table of pointers. Each of
! 1464: these pointers begins a linked list of structures (type \tet{entree}).
! 1465: The linked list is searched linearly for the identifier (each list will
! 1466: typically have less than 7 components or so). When the correct \kbd{entree}
! 1467: is found, it points to the top of the stack of values for that identifier if
! 1468: it is a variable, to the function itself if it is a predefined function, and
! 1469: to a copy of the text of the function if it is a user-defined function. When
! 1470: an error occurs, all of this maze (rather a tree, in fact) is searched and
! 1471: (hopefully) restored to the state preceding the last call of the main
! 1472: evaluator.
! 1473:
! 1474: \misctitle{Note:} The above syntax (using the \tet{local} keyword) was
! 1475: introduced in version 2.0.13. The old syntax
! 1476:
! 1477: \kbd{name(list of true formal variables, list of local variables) = \var{seq}}
! 1478:
! 1479: \noindent is still recognized but is deprecated since genuine arguments and
! 1480: local variables become undistinguishable.
! 1481:
! 1482: \subsec{Member functions}.\sidx{member functions}
! 1483:
! 1484: Member functions use the `dot' notation to retrieve information from
! 1485: complicated structures (by default: types \tet{ell}, \tet{nf}, \tet{bnf},
! 1486: \tet{bnr} and prime ideals). The syntax \kbd{structure.member} is taken to
! 1487: mean: retrieve \kbd{member} from \kbd{structure}, e.g.~\kbd{ell.j} returns
! 1488: the $j$-invariant of the elliptic curve \kbd{ell} (or outputs an error
! 1489: message if \kbd{ell} doesn't have the correct type).
! 1490:
! 1491: You can define your own member functions using the syntax:
! 1492:
! 1493: \bprog%
! 1494: structure.member = {\it function text}
! 1495: \eprog
! 1496: \noindent where {\it function text\/} is written as the {\it seq\/} in a
! 1497: standard user function (without local variables), whose only argument would
! 1498: be \kbd{structure}. For instance, the current implementation of the \kbd{ell}
! 1499: type is simply an horizontal vector, the $j$-invariant being the thirteenth
! 1500: component. This could be implemented as
! 1501:
! 1502: \bprog
! 1503: x.j =
! 1504: \obr
! 1505: \q if (type(x) != "t\_VEC" || length(x) < 14,
! 1506: \q\q error("this is not a proper elliptic curve: " x)
! 1507: \q );
! 1508: \q x[13]
! 1509: \cbr
! 1510: \eprog
! 1511:
! 1512: You can redefine one of your own member functions simply by typing a new
! 1513: definition for it. On the other hand, as a safety measure, you can't redefine
! 1514: the built-in member functions, so typing the above text would in fact produce
! 1515: an error (you'd have to call it e.g.~\kbd{x.j2} in order for GP to accept it).
! 1516:
! 1517: Typing \b{um} will output the list of user-defined member functions.
! 1518:
! 1519: \misctitle{Note:} Member functions were not meant to be too complicated or to
! 1520: depend on any data that wouldn't be global. Hence they do no have parameters
! 1521: (besides the implicit \kbd{structure}) or local variables. Of course, if you
! 1522: need some preprocessing work in there, there's nothing to prevent you from
! 1523: calling your own functions (using freely their local variables) from a member
! 1524: function. For instance, one could implement (a dreadful idea as far as
! 1525: efficiency goes):
! 1526:
! 1527: \bprog
! 1528: correct\_ell\_if\_needed(x) =
! 1529: \obr
! 1530: \q local(tmp);
! 1531: \q if (type(x) != "t\_VEC", tmp = ellinit(x))
! 1532: \q \bs\bs {\it some further checks}
! 1533: \q tmp
! 1534: \cbr
! 1535: x.j = correct\_ell\_if\_needed(x)[13];
! 1536: \eprog
! 1537:
! 1538: \subsec{Strings and Keywords}\sidx{string}\sidx{keyword}
! 1539: \label{se:strings}
! 1540:
! 1541: \noindent
! 1542: GP variables can now hold values of type character string
! 1543: (internal type \typ{STR}).
! 1544: This section describes how they are actually used, as well as some convenient
! 1545: tricks (automatic concatenation and expansion, keywords) valid in string
! 1546: context.
! 1547:
! 1548: As explained above, the general way to input a string is to enclose characters
! 1549: between quotes~\kbd{"}. This is the only input construct where whitespace
! 1550: characters are significant: the string will contain the exact number
! 1551: of spaces you typed in. Besides, you can ``escape'' characters by putting a
! 1552: \kbd{\bs} just before them; this has the following effects:
! 1553:
! 1554: {
! 1555: \def\q{\quad}
! 1556: \obeylines
! 1557: \q \b{e}: the \kbd{<Escape>} character.
! 1558: \q \b{n}: the \kbd{<Newline>} character.
! 1559: \q \b{t}: the \kbd{<Tab>} character.
! 1560: \q \b{any-other-char}: the \kbd{any-other-char} character.
! 1561: }
! 1562: In particular, the only way to put a \kbd{"} into a string is to escape it.
! 1563: Thus, for instance, \kbd{"\bs"a\bs""} would produce the
! 1564: string whose content is ``a''. This is definitely {\it not\/} the same thing as
! 1565: typing \kbd{"a"}, whose content is merely the one-letter string a.
! 1566:
! 1567: You can concatenate two strings using the \tet{concat} function. If either
! 1568: argument is a string, the other is automatically converted to a string if
! 1569: necessary (it will be evaluated first).
! 1570:
! 1571: \bprog%
! 1572: ? concat("ex", 1+1)
! 1573: \%1 = "ex2"
! 1574: ? a = 2; b = "ex"; concat(b, a)
! 1575: \%2 = "ex2"
! 1576: ? concat(a, b)
! 1577: \%3 = "2ex"
! 1578: \eprog
! 1579:
! 1580: Some functions expect strings for some of their arguments: \tet{print} would
! 1581: be an obvious example, \tet{Str} is a less obvious but very useful one (see
! 1582: the end of this section for a complete list). While typing in such an
! 1583: argument, you will be said to be in {\it \idx{string context}}. The rest of
! 1584: this section is devoted to special syntactical tricks which can be used with
! 1585: such arguments (and only here; you will get an error message if you try these
! 1586: outside of string context):
! 1587:
! 1588: $\bullet$ Writing two strings alongside one another will just concatenate
! 1589: them, producing a longer string. Thus it is equivalent to type in
! 1590: \kbd{"a " "b"} or \kbd{"a b"}. A little tricky point in the first expression:
! 1591: the first whitespace is enclosed between quotes, and so is part of a string;
! 1592: while the second (before the \kbd{"b"}) is completely optional and GP
! 1593: actually suppresses it, as it would with any number of whitespace characters
! 1594: at this point (i.e.~outside of any string).
! 1595:
! 1596: $\bullet$ If you insert an expression without quotes when GP expects a
! 1597: string, it gets ``expanded'': it is evaluated as a standard GP expression,
! 1598: and the final result (as would have been printed if you had typed it by
! 1599: itself) is then converted to a string, as if you had typed it directly. For
! 1600: instance \kbd{"a" 1+1 "b"} is equivalent to \kbd{"a2b"}: three strings get
! 1601: created, the middle one being the expansion of \kbd{1+1}, and these are then
! 1602: concatenated according to the rule described above. Another tricky point
! 1603: here: assume you did not assign a value to \kbd{aaa} in a GP expression
! 1604: before. Then typing \kbd{aaa} by itself in a string context will actually
! 1605: produce the correct output (i.e.~the string whose content is aaa), but in a
! 1606: fortuitous way. This \kbd{aaa} gets expanded to the monomial of degree one in
! 1607: the variable \kbd{aaa}, which is of course printed as \kbd{aaa}, and thus
! 1608: will expand to the three letters you were expecting. But you will have
! 1609: defined a variable as a side effect.
! 1610:
! 1611: $\bullet$ Since there are cases where expansion is not really desirable, we
! 1612: now distinguish between ``Keywords'' and ``Strings''. String is what has been
! 1613: described so far. Keywords are special relatives of Strings which are
! 1614: automatically assumed to be quoted, whether you actually type in the quotes
! 1615: or not. Thus expansion is never performed on them. They get concatenated,
! 1616: though. The analyzer supplies automatically the quotes you have ``forgotten''
! 1617: and treats Keywords just as normal strings otherwise. For instance, if you
! 1618: type \kbd{"a"b+b} in Keyword context, you will get the string whose contents
! 1619: are ab+b. In String context, on the other hand, you would get a2\kbd{*}b
! 1620: (and you would have created the variable \kbd{b} in the process if it didn't
! 1621: exist before, but not the variable~\kbd{a}).
! 1622:
! 1623: All GP functions have prototypes (described in Chapter~3 below) which specify
! 1624: the types of arguments they expect: either generic PARI objects (GEN),
! 1625: or strings, or keywords, or unevaluated expression sequences.
! 1626: In the keyword case, only a very small set of words
! 1627: will actually be meaningful (the \kbd{default} function is a prominent
! 1628: example).
! 1629:
! 1630: Let's now try some not-so-stupid exercises to get the hang of it. Try to
! 1631: guess the results of the following commands without actually typing them,
! 1632: assuming that the \kbd{print} command evaluates and prints its (string)
! 1633: arguments in left-to-right order, ending with a newline (and returns 0
! 1634: as an unprinted result):
! 1635:
! 1636: \bprog%
! 1637: \q print()
! 1638: \q print(1+3"a,3" ,4)
! 1639: \q print(a=3, (1 + ((a-3)==print())) (a = (a == 5\bs/2)))
! 1640: \eprog
! 1641:
! 1642: \noindent To round this up, here is a less artificial example, used to create
! 1643: generic matrices\sidx{generic matrix}:
! 1644:
! 1645: \bprog%
! 1646: ? genmat(u,v,s="x") = \idx{matrix}(u,v,i,j, eval(Str(s "" i "" j)))
! 1647: ? genmat(2,3) + genmat(2,3,m)
! 1648: \%1 =
! 1649: [x11 + m11 x12 + m12 x13 + m13]
! 1650: [x21 + m21 x22 + m22 x23 + m23]
! 1651: \eprog
! 1652:
! 1653: \noindent
! 1654: Note that the argument of \kbd{Str} is evaluated in string context, and
! 1655: really consists of 5 pieces (exercise: why are the empty strings necessary?).
! 1656: This part could also have been written as \kbd{concat(concat(Str(s), i), j)}
! 1657: (but {\it not\/} as \kbd{concat(Str(s), concat(i,j))}!). In practice,
! 1658: \kbd{Str} will often be easier to use than \kbd{concat}, if slightly more
! 1659: cryptic.
! 1660:
! 1661: \noindent The arguments of the following functions are processed in string
! 1662: context:
! 1663: \bprog%
! 1664: \idx{Str}
! 1665: \idx{addhelp} {\rm (second argument)}
! 1666: \idx{default} {\rm (second argument)}
! 1667: \idx{error}
! 1668: \idx{extern}
! 1669: \idx{plotstring} {\rm (second argument)}
! 1670: \idx{plotterm} {\rm (first argument)}
! 1671: {\rm all the \kbd{\idx{print}{\it xxx\/}} functions}
! 1672: \idx{read}
! 1673: \idx{system}
! 1674: {\rm all the \kbd{\idx{write}{\it xxx\/}} functions}
! 1675: \eprog
! 1676:
! 1677: \noindent The arguments of the following functions are processed as keywords:
! 1678: \bprog%
! 1679: \idx{alias}
! 1680: \idx{default} {\rm (first argument)}
! 1681: \idx{install} {\rm (all arguments but the last)}
! 1682: \idx{type} {\rm (second argument)}
! 1683: \idx{whatnow}
! 1684: \eprog
! 1685:
! 1686: \section{Interfacing GP with other languages}
! 1687: \noindent
! 1688: The PARI library was meant to be interfaced with C programs. This specific
! 1689: use will be dealt with extensively in Chapter~4. GP itself provides a
! 1690: convenient, if simple-minded, interpreter, which enables you to execute
! 1691: rather intricate scripts (see \secref{se:programming}).
! 1692:
! 1693: Scripts, when properly written, tend to be shorter and much clearer than C
! 1694: programs, and are certainly easier to write, maintain or debug. You don't
! 1695: need to deal with memory management, garbage collection, pointers,
! 1696: declarations, and so on. Because of their intrinsic simplicity, they are more
! 1697: robust as well. They are unfortunately somewhat slower. Thus their use will
! 1698: remain complementary: it is suggested that you test and debug your algorithms
! 1699: using scripts, before actually coding them in C for the sake of speed.
! 1700:
! 1701: \unix{Note that the \kbd{install} command enables you to concentrate on
! 1702: critical parts of your programs only (which can of course be written with the
! 1703: help of other mathematical libraries than PARI!), and to easily and
! 1704: efficiently import foreign functions for use under GP
! 1705: (see~\secref{se:install}).}
! 1706:
! 1707: We are aware of three PARI-related public domain libraries. {\it We neither
! 1708: endorse nor support any of them}. You might want to give them a try if you
! 1709: are familiar with the languages they are based on. First, there are
! 1710: \tet{PariPerl}%
! 1711: \footnote{*}{
! 1712: see \kbd{%
! 1713: http://nswt.tuwien.ac.at:8000/htdocs/internet/unix/perl/math-pari.html}},
! 1714: %
! 1715: written by Ilya Zakharevich (\kbd{ilya@math.ohio-state.edu}),
! 1716: and \tet{PariPython}%
! 1717: \footnote{**}{
! 1718: see \kbd{http://www.math.jussieu.fr/\til{}fermigie/PariPython/readme.html}},
! 1719: %
! 1720: by St\'efane Fermigier (\kbd{fermigie@math.jussieu.fr}). Finaly, Michael Stoll
! 1721: (\kbd{Michael\_Stoll@math.uni-bonn.de}) has integrated PARI into \tet{CLISP},
! 1722: which is a Common Lisp implementation by Bruno Haible, Marcus Daniels and
! 1723: others. These provide interfaces to GP functions for use in \kbd{perl},
! 1724: \kbd{python} or \kbd{Lisp} programs.\sidx{Perl}\sidx{Python}\sidx{Lisp}
! 1725: To our knowledge, only the \kbd{python} and \kbd{perl} interfaces have been
! 1726: upgraded to version 2.0 of PARI, the \kbd{CLISP} one being still based on
! 1727: version 1.39.$xx$.
! 1728:
! 1729: \section{The preferences file}\sidx{startup}\sidx{gprc}\sidx{preferences file}
! 1730: \label{se:gprc}
! 1731:
! 1732: \noindent
! 1733: When GP is started, it looks for a customization file, or \kbd{gprc} in the
! 1734: following places (in this order, only the first one found will be read):
! 1735:
! 1736: \noindent$\bullet$ On the Macintosh (only), GP looks in the directory which
! 1737: contains the GP executable itself for a file called \kbd{gprc}. No other places
! 1738: are examined.
! 1739:
! 1740: \noindent$\bullet$ If the operating system supports environment variables
! 1741: (essentially, anything but MacOS), GP checks whether the environment variable
! 1742: \tet{GPRC} is set. Under DOS, you can set it in \kbd{AUTOEXEC.BAT}.
! 1743: On Unix, this can be done with something like:
! 1744: \smallskip
! 1745:
! 1746: \settabs\+\indent&\kbd{GPRC=/my/dir/anyname; export GPRC}\quad&\cr
! 1747:
! 1748: \+&\kbd{GPRC=/my/dir/anyname; export GPRC}\quad&in \kbd{sh} syntax
! 1749: (for instance in your \kbd{.profile}),\cr
! 1750:
! 1751: \+&\kbd{setenv GPRC /my/dir/anyname} &in \kbd{csh} syntax
! 1752: (in your \kbd{.login} or \kbd{.cshrc} file).\cr
! 1753:
! 1754: \noindent If so, the file named by \kbd{\$GPRC} is the \kbd{gprc}.
! 1755:
! 1756: \noindent$\bullet$ If \kbd{GPRC} is not set, and if the environment variable
! 1757: \kbd{HOME} is defined, GP then tries
! 1758:
! 1759: \kbd{\$HOME/.gprc} on a Unix system
! 1760:
! 1761: \kbd{\$HOME\bs\_$\,$gprc} on a DOS, OS/2, or Windows system.
! 1762:
! 1763: \noindent$\bullet$ If \kbd{HOME} also leaves us clueless, we try
! 1764:
! 1765: \strut\kbd{\til/.gprc} on a Unix system (where as usual \kbd{\til} stands for
! 1766: your home directory), or
! 1767:
! 1768: \kbd{\b{\_}$\,$gprc} on a DOS, OS/2, or Windows system.
! 1769:
! 1770: \noindent$\bullet$ Finally, if no gprc was found among the user files
! 1771: mentioned above we look for \kbd{/etc/gprc} (\kbd{\bs etc\bs gprc})
! 1772: for a system-wide gprc file (you'll need root privileges to set up such a
! 1773: file yourself).
! 1774:
! 1775: Note that on Unix systems, the \kbd{gprc}'s default name starts with a '.' and
! 1776: thus is hidden to regular \kbd{ls} commands; you need to type \kbd{ls -a} to
! 1777: see whether it's already there without your knowing about it.
! 1778:
! 1779: In any case, GP will open the corresponding file and process the commands in
! 1780: there, {\it before\/} doing anything else, e.g.~creating the PARI stack. If
! 1781: the file doesn't exist or cannot be read, GP will proceed to the
! 1782: initialization phase at once, eventually emitting a prompt. If any explicit
! 1783: commandline switches are given, they will override the values read from the
! 1784: \kbd{gprc} file.
! 1785:
! 1786: The syntax in this file (and valid in this file only, at this very precise
! 1787: moment!) is simple-minded, but should be sufficient for most purposes. It
! 1788: is read line by line, white space being optional as usual (unless surrounded
! 1789: by quotes). Two types of lines are first dealt with by a preprocessor:
! 1790:
! 1791: $\bullet$ comments are removed. This applies to all text surrounded by
! 1792: \kbd{/*~\dots~*/} as well as everything following \kbd{\bs\bs} on a given
! 1793: line.
! 1794:
! 1795: $\bullet$ lines starting with \kbd{\#if} \var{keyword} are treated as
! 1796: comments if \var{keyword} is not defined, and read normally otherwise. The
! 1797: condition can be negated using either \kbd{\#if not} (or \kbd{\#if !}). Only
! 1798: two keywords are recognized:
! 1799:
! 1800: \kbd{EMACS}: defined if GP is running in an Emacs shell (see
! 1801: \secref{se:emacs}).
! 1802:
! 1803: \kbd{READL}: defined if GP is compiled with \kbd{readline} support (see
! 1804: \secref{se:readline}).
! 1805:
! 1806: \noindent For instance you could set your prompt in the following portable
! 1807: way:
! 1808: \bprog%
! 1809: \b{\bs} self modifying prompt looking like \hbox{{\rm (18:03) \key{gp}} >}
! 1810: prompt = "(\%R) \b{e}[1mgp\b{e}[m > "
! 1811: \h
! 1812: \b{\bs} readline wants non-printing characters to be braced between \pow A/\pow B pairs
! 1813: \#if READL prompt = "(\%R) \pow A\b{e}[1m\pow Bgp\pow A\b{e}[m\pow B > "
! 1814: \h
! 1815: \b{\bs} escape sequences not supported under emacs
! 1816: \#if EMACS prompt = "(\%R) gp > "
! 1817: \eprog
! 1818:
! 1819: \noindent After the preprocessing there remain two types of lines:
! 1820:
! 1821: $\bullet$ lines of the form \var{default} \kbd{=} \var{value}, where
! 1822: \var{default} is one of the available defaults (see \secref{se:defaults}),
! 1823: which will be set to \var{value} on actual startup. Don't forget the
! 1824: quotes around strings (e.g.~for \kbd{prompt} or \kbd{help}).
! 1825:
! 1826: $\bullet$ lines of the form \kbd{read "\var{some\_GP\_file}"} where
! 1827: \kbd{\var{some\_GP\_file}} is a regular GP script this time, which will
! 1828: be read just before GP prompts you for commands, but after initializing the
! 1829: defaults. This is the right place to input files containing \kbd{alias}
! 1830: commands, or your favorite macros.
! 1831:
! 1832: A sample \kbd{gprc} file called \kbd{gprc.dft} is provided in the
! 1833: standard distribution (in directory \kbd{lib}). It's a good idea to have a
! 1834: look at it and customize it to your needs.
! 1835:
! 1836: \section{Using GP under GNU Emacs}
! 1837: \label{se:emacs}
! 1838:
! 1839: Thanks to the initial help of Annette Hoffman from the University of
! 1840: Saarbr\"ucken, and David Carlisle from the University of Manchester, it is
! 1841: possible to use GP as a subprocess of GNU \idx{Emacs}. (Of course, you need
! 1842: GNU Emacs to be installed on your machine!). To use this, you should
! 1843: include in your \kbd{.emacs} file the following lines:
! 1844: \bprog%
! 1845: (autoload 'gp-mode "\miscdir/pari" nil t)
! 1846: (autoload 'gp-script-mode "\miscdir/pari" nil t)
! 1847: (autoload 'gp "\miscdir/pari" nil t)
! 1848: (autoload 'gpman "\miscdir/pari" nil t)
! 1849: (setq auto-mode-alist
! 1850: \q (cons '("\bs\bs.gp\$" . gp-script-mode) auto-mode-alist))
! 1851: \eprog
! 1852:
! 1853: where \kbd{pari.el} is the name of the file that will have to be loaded by
! 1854: GNU Emacs (if you have changed the name, or if you have the file in a
! 1855: different directory, you must of course supply the correct name). This file
! 1856: is included in the PARI distribution and probably has been installed at the
! 1857: same time as GP.
! 1858:
! 1859: Once this is done, under GNU Emacs if you type \kbd{M-x gp} (where as usual
! 1860: \kbd{M} is the \kbd{Meta} key, i.e.~Escape, or on SUN keyboards, the Left
! 1861: key), a special shell will be started, which in particular launches GP with
! 1862: the default stack size, prime limit and input buffer size. If you type
! 1863: instead \kbd{C-u M-x gp}, you will be asked for the name of the GP
! 1864: executable, the stack size, the prime limit and the input buffer size before
! 1865: the execution of GP begins. If for any of these you simply type return, the
! 1866: default value will be used. On UNIX machines it will be the place you told
! 1867: \kbd{Configure} (usually \kbd{/usr/local/bin/gp}) for the executable, 4000000
! 1868: for the stack, 500000 for the prime limit and 30000 for the buffer size.
! 1869:
! 1870: \smallskip
! 1871: You can then work as usual under GP, but with two notable advantages (which
! 1872: don't really matter if readline is available to you, see below). First and
! 1873: foremost, you have at your disposal all the facilities of a text editor like
! 1874: Emacs, in particular for correcting or copying blocks. Second, you can have
! 1875: an on-line help which is much more complete than what you obtain by typing
! 1876: \kbd{?name}. This is done by typing \kbd{M-?}. In the minibuffer, Emacs asks
! 1877: what function you want to describe, and after your reply you obtain the
! 1878: description which is in the users manual, including the description of
! 1879: functions (such as \kbd{\bs}, \kbd{\%}) which use special symbols.
! 1880:
! 1881: This help system can also be menu-driven, by using the command
! 1882: \kbd{M-\char`\\ c} which opens a help menu window which enables you to choose
! 1883: the category of commands for which you want an explanation.
! 1884:
! 1885: Nevertheless, if extended help is available on your system (see
! 1886: \secref{se:exthelp}), you should use it instead of the above, since it's
! 1887: nicer (it ran through \TeX) and understands many more keywords.
! 1888:
! 1889: Finally you can use command completion in the following way. After the
! 1890: prompt, type the first few letters of the command, then \kbd{<TAB>} where
! 1891: \kbd{<TAB>} is the TAB key. If there exists a unique command starting with
! 1892: the letters you have typed, the command name will be completed. If not,
! 1893: either the list of commands starting with the letters you typed will be
! 1894: displayed in a separate window (which you can then kill by typing as usual
! 1895: \kbd{C-x 1} or by typing in more letters), or ``no match found'' will be
! 1896: displayed in the Emacs command line. If your GP was linked with the readline
! 1897: library, read the section on completion in the section below (the paragraph
! 1898: on online help is not relevant).
! 1899:
! 1900: Note that if for some reason the session crashes (due to a bug in your
! 1901: program or in the PARI system), you will usually stay under Emacs, but the GP
! 1902: buffer will be killed. To recover it, simply type again \kbd{M-x gp} (or
! 1903: \kbd{C-u M-x gp}), and a new session of GP will be started after the old one,
! 1904: so you can recover what you have typed. Note that this will of course
! 1905: {\it not} work if for some reason you exited Emacs before coming back (except
! 1906: for the \kbd{C-z} temporary stopping command).
! 1907:
! 1908: \smallskip
! 1909: You also have at your disposal a few other commands and many possible
! 1910: customizations (colours, prompt). Read the file \kbd{emacs/pariemacs.txt} in
! 1911: standard distribution for details.
! 1912:
! 1913:
! 1914: \section{Using GP with readline}
! 1915: \sidx{line editor}\sidx{completion}
! 1916:
! 1917: Thanks to the initial help of Ilya Zakharevich, there is a possibility of
! 1918: line editing and command name completion outside of an Emacs buffer {\it
! 1919: if} you have compiled GP with the GNU \idx{readline} library. If you don't
! 1920: have Emacs available, or can't stand using it, we really advise you to make
! 1921: sure you get this very useful library before configuring or compiling GP.
! 1922: In fact, with \kbd{readline}, even line editing becomes {\it more} powerful
! 1923: outside an Emacs buffer!
! 1924:
! 1925: \subsec{A (too) short introduction to readline}:
! 1926: \label{se:readline}
! 1927: The basics are as follows (read the readline user manual~!), assume that
! 1928: \kbd{C-} stands for ``the \kbd{Control} key combined with another'' and the
! 1929: same for \kbd{M-} with the \kbd{Meta} key (generally \kbd{C-} combinations
! 1930: act on characters, while the \kbd{M-} ones operate on words). The \kbd{Meta}
! 1931: key might be called \kbd{Alt} on some keyboards, will display a black diamond
! 1932: on most others, and can safely be replaced by \kbd{Esc} in any case. Typing
! 1933: any ordinary key inserts text where the cursor stands, the arrow keys
! 1934: enabling you to move in the line. There are many more movement commands,
! 1935: which will be familiar to the Emacs user, for instance \kbd{C-a}/\kbd{C-e}
! 1936: will take you to the start/end of the line, \kbd{M-b}/\kbd{M-f} move the
! 1937: cursor backward/forward by a word, etc. Just press the \kbd{Return} key at
! 1938: any point to send your command to GP.
! 1939:
! 1940: All the commands you type in are stored in a history (with multiline
! 1941: commands being saved as single concatenated lines). The Up and Down arrows (or
! 1942: \kbd{C-p}/\kbd{C-n}) will move you through it, \kbd{M-<}/\kbd{M->} sending
! 1943: you to the start/end of the history. \kbd{C-r}/\kbd{C-s} will start an
! 1944: incremental backward/forward search. You can kill text (\kbd{C-k} kills till
! 1945: the end of line, \kbd{M-d} to the end of current word) which you can then
! 1946: yank back using the \kbd{C-y} key (\kbd{M-y} will rotate the kill-ring).
! 1947: \kbd{C-\_} will undo your last changes incrementally (\kbd{M-r} undoes all
! 1948: changes made to the current line). \kbd{C-t} and \kbd{M-t} will transpose
! 1949: the character (word) preceding the cursor and the one under the cursor.
! 1950:
! 1951: Keeping the \kbd{M-} key down while you enter an integer (a minus sign
! 1952: meaning reverse behaviour) gives an argument to your next readline command
! 1953: (for instance \kbd{M-- C-k} will kill text back to the start of line). If you
! 1954: prefer \idx{Vi}--style editing, \kbd{M-C-j} will toggle you to Vi mode.
! 1955:
! 1956: Of course you can change all these default bindings. For that you need to
! 1957: create a file named \kbd{.inputrc} in your home directory. For instance
! 1958: (notice the embedding conditional in case you would want specific bindings
! 1959: for GP):
! 1960: %
! 1961: \bprog%
! 1962: \$if Pari-GP
! 1963: \q set show-all-if-ambiguous
! 1964: \q "\b{C}-h": backward-delete-char
! 1965: \q "\b{e}\b{C}-h": backward-kill-word
! 1966: \q "\b{C}-xd": dump-functions
! 1967: \q (: "\b{C}-v()\b{C}-b" \qquad \# can be annoying when copy-pasting~!
! 1968: \q [: "\b{C}-v[]\b{C}-b"
! 1969: \$endif%
! 1970: \eprog
! 1971: %
! 1972: \noindent\kbd{C-x C-r} will re-read this init file, incorporating any
! 1973: changes made to it during the current session.
! 1974:
! 1975: \misctitle{Note:} By default, \kbd{(} and \kbd{[} are bound to the function
! 1976: \kbd{pari-matched-insert} which, if ``electric parentheses'' are enabled
! 1977: (default: off) will automatically insert the matching closure (respectively
! 1978: \kbd{)} and \kbd{]}). This behaviour can be toggled on and off by giving
! 1979: the numeric argument $-2$ to \kbd{(} (\kbd{M--2(}), which is useful if you
! 1980: want, e.g to copy-paste some text into the calculator. If you don't want a
! 1981: toggle, you can use \kbd{M--0} / \kbd{M--1} to specifically switch it on or
! 1982: off).
! 1983:
! 1984: \misctitle{Note:} In recent versions of readline (2.1 for instance), the
! 1985: \kbd{Alt} or \kbd{Meta} key can give funny results (output 8-bit accented
! 1986: characters for instance). If you don't want to fall back to the \kbd{Esc}
! 1987: combination, put the following two lines in your \kbd{.inputrc}:
! 1988: %
! 1989: \bprog%
! 1990: set convert-meta on
! 1991: set output-meta off%
! 1992: \eprog
! 1993:
! 1994: % don't remove this leading space (needed by gphelp)
! 1995: \subsec{Command completion and online help}
! 1996:
! 1997: As in the Emacs shell, \kbd{<TAB>} will complete words for you. But, under
! 1998: readline, this mechanism will be context-dependent: GP will strive to only
! 1999: give you meaningful completions in a given context (it will fail sometimes,
! 2000: but only under rare and restricted conditions).
! 2001:
! 2002: For instance, shortly after a \kbd{\til}, we expect a user name, then a
! 2003: path to some file. Directly after \kbd{default(} has been typed, we would
! 2004: expect one of the \kbd{default} keywords. After \kbd{whatnow(} , we expect
! 2005: the name of an old function, which may well have disappeared from this
! 2006: version. After a '.', we expect a member keyword. And generally of course, we
! 2007: expect any GP symbol which may be found in the hashing lists: functions (both
! 2008: yours and GP's), and variables.
! 2009:
! 2010: If, at any time, only one completion is meaningful, GP will provide it
! 2011: together with
! 2012:
! 2013: $\bullet$ an ending comma if we're completing a default,
! 2014:
! 2015: $\bullet$ a pair of parentheses if we're completing a function name. In
! 2016: that case hitting \kbd{<TAB>} again will provide the argument list as given
! 2017: by the online help\footnote{*}{recall that you can always undo the effect
! 2018: of the preceding keys by hitting \kbd{C-\_}}.
! 2019:
! 2020: Otherwise, hitting \kbd{<TAB>} once more will give you the list of possible
! 2021: completions. Just experiment with this mechanism as often as possible,
! 2022: you'll probably find it very convenient. For instance, you can obtain
! 2023: \kbd{default(seriesprecision,10)}, just by hitting \kbd{def<TAB>se<TAB>10},
! 2024: which saves 18 keystrokes (out of 27).
! 2025:
! 2026: Hitting \kbd{M-h} will give you the usual short online help concerning the
! 2027: word directly beneath the cursor, \kbd{M-H} will yield the extended help
! 2028: corresponding to the \kbd{help} default program (usually opens a \idx{dvi}
! 2029: previewer, or runs a primitive tex-to-ASCII program). None of these disturb
! 2030: the line you were editing.
! 2031: \vfill\eject
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to usersch2.tex CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [local] / OpenXM_contrib / pari / doc