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