@comment -*-texinfo-*- @comment $Id: general.doc,v 1.129 1999-07-19 14:07:37 obachman Exp $ @comment this file contains the general information about Singular @c The following directives are necessary for proper compilation @c with emacs (C-c C-e C-r). Please keep it as it is. Since it @c is wrapped in `@ignore' and `@end ignore' it does not harm `tex' or @c `makeinfo' but is a great help in editing this file (emacs @c ignores the `@ignore'). @ignore %**start \input texinfo.tex @setfilename general.info @node Top, General concepts @menu * General concepts:: @end menu @node General concepts, Data types, Introduction, Top @chapter General concepts %**end @end ignore @menu * Interactive use:: * Rings and orderings:: * Implemented algorithms:: * The SINGULAR language:: * Input and output:: * Procedures:: * Libraries:: * Debugging tools:: @end menu @c --------------------------------------------------------------------------- @node Interactive use, Rings and orderings, General concepts, General concepts @section Interactive use @cindex Interactive use In this section, all aspects of interactive use are discussed. This includes how to enter and exit @sc{Singular}, how to interpret its prompt, how to get the online help, and so on. There are a few important notes which one should not forget: @itemize @bullet @item every command has to be terminated by a @code{;} (semicolon) followed by a @code{RETURN} @item the online help is accessible by means of the @code{help} function @end itemize @menu * How to enter and exit:: * The SINGULAR prompt:: * The online help system:: * Interrupting SINGULAR:: * Editing input:: * Command line options:: * Startup sequence:: @end menu @c -------------------------------------------------------------------------- @node How to enter and exit, The SINGULAR prompt, Interactive use, Interactive use @subsection How to enter and exit @cindex How to enter and exit To start @sc{Singular}, enter @code{Singular} at the system prompt. The @sc{Singular} banner appears which, among others, reports the version and the compilation date. To exit @sc{Singular} type @code{quit;}, @code{exit;} or @code{$}. @sc{Singular} may also be started with command line options and with filenames as arguments. More generally, the synopsis of @sc{Singular} is @smallexample Singular [options] [file1 [file2 @dots{}]] @end smallexample @xref{Command line options}, @ref{Startup sequence}. @c -------------------------------------------------------------------------- @node The SINGULAR prompt,The online help system,How to enter and exit, Interactive use @subsection The SINGULAR prompt @cindex prompt @cindex error recovery The @sc{Singular} prompt @code{>} (larger than) asks the user for input of commands. The ``continuation'' prompt @code{.} (period) asks the user for input of missing parts of a command (remember the semicolon at the end of every command). @sc{Singular} does not interpret the semicolon as the end of a command if it occurs inside a string. Also, @sc{Singular} waits for blocks (sequences of commands enclosed in curly brackets) to be closed before prompting with @code{>} for more commands. Thus, if @sc{Singular} does not respond with its regular prompt after typing a semicolon it may wait for a @code{"} or a @code{@}} first. Additional semicolons will not harm @sc{Singular} since they are interpreted as empty statements. @c -------------------------------------------------------------------------- @node The online help system,Interrupting SINGULAR, The SINGULAR prompt,Interactive use @subsection The online help system @cindex The online help system The online help system is invoked with the @code{help} command. @code{?} may be used as a synonym for @code{help}. Simply typing @code{help;} displays the ``top'' of the help system which offers a short table of content. Typing @code{help} topic@code{;} shows the available documentation on topic. Here, topic may be either a function name or, more generally, the name of any section of the printed manual. @xref{help}, for more information. On Unix-like operating systems, the online help system is based on the @code{info} program from the Gnu @code{texinfo} package. @xref{Top, An Introduction to Info, Getting started, info, The Info Manual}, for more information. On the other systems the online help system is not interactively as described in the remainder of this section. Instead, after displaying the information @sc{Singular} immediately returns to the input prompt. The online manual is decomposed into ``nodes'' of information, closely related to the division of the printed manual into sections and subsections. A node contains text describing a specific topic at a specific level of detail. The top line of a node is its ``header''. The node's header tells the name of the current node (@code{Node:}), the name of the next node (@code{Next:}), the name of the previous node (@code{Prev:}), and the name of the upper node (@code{Up:}). To move within info, type commands consisting of single characters. Do not type @code{RETURN}. Do not use cursor keys, either. Using some of the cursor keys by accident might pop to some totally different node. Type @code{l} to return to the original node. Some of the @code{info} commands read input from the command line at the bottom line. The @code{TAB} key may be used to complete partially entered input. The most important commands are: @table @asis @item @code{q} leaves the online help system @item @code{n} goes to the next node @item @code{p} goes to the previous node @item @code{u} goes to the upper node @item @code{m} picks a menu item specified by name @item @code{f} follows a cross reference @item @code{l} goes to the previously visited node @item @code{b} goes to the beginning of the current node @item @code{e} goes to the end of the current node @item @code{SPACE} scrolls forward a page @item @code{DEL} scrolls backward a page @item @code{h} invokes info tutorial (use @code{l} to return to the manual or @code{CTRL-X 0} to remove extra window) @item @code{CTRL-H} shows a short overview on the online help system (use @code{l} to return to the manual or @code{CTRL-X 0} to remove extra window) @item @code{s} searches through the manual for a specified string, and selects the node in which the next occurrence is found @item @code{1}, @dots{}, @code{9} picks i-th subtopic from a menu @end table @c -------------------------------------------------------------------------- @node Interrupting SINGULAR,Editing input,The online help system,Interactive use @subsection Interrupting SINGULAR @cindex Interrupting SINGULAR On Unix-like operating systems and on Windows NT, typing @code{CTRL-C} interrupts @sc{Singular}. @sc{Singular} prints the current command and the current line and prompts for further action. The following choices are available: @table @code @item a returns to the top level after finishing the current command @item c continues @item q quits @sc{Singular} @end table @c -------------------------------------------------------------------------- @node Editing input,Command line options,Interrupting SINGULAR,Interactive use @subsection Editing input @cindex Editing input @cindex SINGULARHIST This section describes only a subset of the key bindings of @sc{Singular} binaries built with the GNU Readline library. @xref{Command Line Editing, GNU Readline Library, Command Line Editing, readline, The GNU Readline Library Manual}, for more information. The following keys can be used for editing the input and retrieving previous input lines: @table @code @item TAB provides command line completion for function names and file names @item CTRL-B moves cursor left @item CTRL-F moves cursor right @item CTRL-A moves cursor to beginning of line @item CTRL-E moves cursor to end of line @item CTRL-D deletes character under cursor @* Warning: on an empty line, @code{CTRL-D} is interpreted as the @code{EOF} character which immediately terminates @sc{Singular}. @item BACKSPACE @itemx DELETE @itemx CTRL-H deletes character before cursor @item CTRL-K kills from cursor to end of line @item CTRL-U kills from cursor to beginning of line @item CTRL-N saves current line on history and gives next line @item CTRL-P saves current line on history and gives previous line @item RETURN saves the current line to the history and sends it to the @sc{Singular} parser for interpretation @end table On Unix-like operating systems, @sc{Singular} maintains a history of the last lines of input. If the environment variable @code{SINGULARHIST} is set and has a name of a file as value, then the input history is stored across sessions using this file. Otherwise, i.e., if the environment variable @code{SINGULARHIST} is not set, then the history of the last inputs is only available for the commands of the current session. @c -------------------------------------------------------------------------- @node Command line options, Startup sequence, Editing input, Interactive use @subsection Command line options @cindex Command line options The synopsis of @sc{Singular} is @smallexample Singular [options] [file1 [file2 @dots{}]] @end smallexample Options can be given in both, their long and short format. The following options control the general behavior of @sc{Singular}: @table @asis @item @code{-e}, @code{--echo[=VAL]} Set value of variable @code{echo} to @code{VAL} (integer in the range 0, @dots{}, 9). Without an argument, @code{echo} is set to 1, which echoes all input coming from a file. By default, the value of @code{echo} is 0. @xref{echo}. @item @code{-h}, @code{--help} Print a one-line description of each command line option and exit. @item @code{--no-rc} Do not execute the @code{.singularrc} file on start-up. By default, this file is executed on start-up. @xref{Startup sequence}. @item @code{--no-stdlib} Do not load the library @code{standard.lib} on start-up. By default, this library is loaded on start-up. @xref{Startup sequence}. @item @code{--no-warn} Do not display warning messages. @item @code{--no-out} Suppress display of all output. @item @code{-t}, @code{--no-tty} Do not redefine the terminal characteristics. This option should be used for batch processes. @item @code{-q}, @code{--quiet} Do not print the start-up banner and messages when loading libraries. Furthermore, redirect @code{stderr} (all error messages) to @code{stdout} (normal output channel). This option should be used if @sc{Singular}'s output is redirected to a file. @item @code{-v}, @code{--verbose} Print extended information about the version and configuration of @sc{Singular} (used optional parts, compilation date, start of random generator etc.). This information should be included if a user reports an error to the authors. @end table The following command line options allow manipulations of the timer and the pseudo random generator and enable passing of commands and strings to @sc{Singular}: @table @asis @item @code{-c}, @code{--execute=STRING} Execute @code{STRING} as (a sequence of) @sc{Singular} commands on start-up after the @code{.singularrc} file is executed, but prior to executing the files given on the command line. E.g., @code{Singular -c "help all.lib; quit;"} shows the help for the library @code{all.lib} and exits. @item @code{-u}, @code{--user-option=STRING} Returns @code{STRING} on @code{system("--user-option")}. This is useful for passing arbitrary arguments from the command line to the @sc{Singular} interpreter. E.g., @*@code{Singular -u "xxx.dump" -c 'getdump(system("--user-option"))'} reads the file @code{xxx.dump} at start-up and allows the user to start working with all the objects defined in a previous session. @item @code{-r}, @code{--random=SEED} Seed (i.e., set the initial value of) the pseudo random generator with integer @code{SEED}. If this option is not given, then the random generator is seeded with a time-based @code{SEED} (the number of seconds since January, 1, 1970, on Unix-like operating systems, to be precise). @item @code{--min-time=SECS} If the @code{timer} (@pxref{timer}), resp. @code{rtimer} (@pxref{rtimer}) , variable is set, report only times larger than @code{SECS} seconds (@code{SECS} needs to be a floating point number greater than 0). By default, this value is set to 0.5 (i.e., half a second). E.g., the option @code{--min-time=0.01} forces @sc{Singular} to report all times larger than 1/100 of a second. @item @code{--ticks-per-sec=TICKS} Set unit of timer to @code{TICKS} ticks per second (i.e., the value reported by the @code{timer} and @code{rtimer} variable divided by @code{TICKS} gives the time in seconds). By default, this value is 1. @end table The last three options are of interest for the use with MP links: @table @asis @item @code{-b}, @code{--batch} Run in MP batch mode. Opens a TCP/IP connection with host specified by @code{--MPhost} at the port specified by @code{--MPport}. Input is read from and output is written to this connection in the MP format. @xref{MPtcp links}. @item @code{--MPport=PORT} Use @code{PORT} as default port number for MP connections (whenever not further specified). This option is mandatory when the @code{--batch} option is given. @xref{MPtcp links}. @item @code{--MPhost=HOST} Use @code{HOST} as default host for MP connections (whenever not further specified). This option is mandatory when the @code{--batch} option is given. @xref{MPtcp links}. @end table The value of options given to @sc{Singular} (resp. their default values, if an option was not given), can be checked with the command @code{system("} long_option_name_string @code{")}. @xref{system}. @smallexample @c example system("--quiet"); // if ``quiet'' 1, otherwise 0 system("--min-time"); // minimal reported time @c example @end smallexample @c -------------------------------------------------------------------------- @node Startup sequence, , Command line options, Interactive use @subsection Startup sequence @cindex Startup sequence On start-up, @sc{Singular} @enumerate @item loads the library @code{standard.lib} (provided the @code{--no-stdlib} option was not given), @item searches the current directory and then the home directory of the user for a file named @code{.singularrc} and executes it, if found (provided the @code{--no-rc} option was not given), @item executes the string specified with the @code{--execute} command line option, @item executes the files @code{file1}, @code{file2} @dots{} (given on the command line) in that order. @end enumerate See @ref{LIB} for the directories on where @sc{Singular} searches for its library files. @c -------------------------------------------------------------------------- @c --------------------------------------------------------------------------- @node Rings and orderings, Implemented algorithms, Interactive use, General concepts @section Rings and orderings @cindex Rings and orderings All non-trivial algorithms in @sc{Singular} require the prior definition of a ring. Such a ring can be @enumerate @item a polynomial ring over a field, @item a localization of a polynomial ring, @item a quotient ring by an ideal of one of 1.@: or 2., @item a tensor product of one of 1.@: or 2. @end enumerate Except for quotient rings, all of these rings are realized by choosing a coefficient field, ring variables, and an appropriate global or local monomial ordering on the ring variables. @xref{Term orderings}, @ref{Mathematical background}. The coefficient field of the rings may be @enumerate @item the field of rational numbers @math{Q}, @item @tex finite fields $Z/p$, $p$ a prime $\le 32003$, @end tex @ifinfo finite fields Z/p, p a prime <= 32003, @end ifinfo @item @tex finite fields $\hbox{GF}(p^n)$ with $p^n$ elements, $p$ a prime, $p^n \le 2^{15}$, @end tex @ifinfo finite fields GF(p^n) with p^n elements, p a prime, p^n <= 2^15, @end ifinfo @item transcendental extension of @math{Q} or @math{Z/p}, @item simple algebraic extension of @math{Q} or @math{Z/p}, @item the field of real numbers represented by simple precision floating point numbers. @end enumerate Throughout this manual, the current active ring in @sc{Singular} is called basering. The reserved name @code{basering} in @sc{Singular} is an alias for the current active ring. The basering can be set by declaring a new ring as described in the following subsections or with the commands @code{setring} and @code{keepring}. @xref{keepring}, @ref{setring}. Objects of ring dependent types are local to a ring. To access them after a change of the basering they have to be mapped using @code{map} or by the functions @code{imap} or @code{fetch}. @xref{Objects}, @ref{fetch}, @ref{imap}, @ref{map}. All changes of the basering in a procedure are local to this procedure unless a @code{keepring} command is used as the last statement of the procedure. @xref{Procedures}, @ref{keepring}. @menu * Examples of ring declarations:: * General syntax of a ring declaration:: * Term orderings:: @end menu @c -------------------------------------- @node Examples of ring declarations, General syntax of a ring declaration, Rings and orderings, Rings and orderings @subsection Examples of ring declarations @cindex Examples of ring declarations The exact syntax of a ring declaration is given in the next two subsections; this subsection lists some examples first. Note that the ordering has to be chosen such that the unit-elements of the ring are precisely those elements with leading monomial 1. For more information, see @ref{Monomial orderings}. @itemize @bullet @item the ring @math{Z/32003[x,y,z]} with degree reverse lexicographical ordering. The exact ring declaration may be omitted in the first example since this is the default ring: @smallexample ring r; ring r = 32003,(x,y,z),dp; @end smallexample @item the ring @math{Q[a,b,c,d]} with lexicographical ordering: @smallexample ring r = 0,(a,b,c,d),lp; @end smallexample @item the ring @math{Z/7[x,y,z]} with local degree reverse lexicographical ordering. The non-prime 10 is converted to the next lower prime in the second example: @smallexample ring r = 7,(x,y,z),ds; ring r = 10,(x,y,z),ds; @end smallexample @item the ring @tex $Z/7[x_1,\ldots,x_6]$ @end tex @ifinfo Z/7[x1,@dots{},x6] @end ifinfo with lexicographical ordering for @tex $x_1,\ldots,x_3$ @end tex @ifinfo x1,@dots{},x3 @end ifinfo and degree reverse lexicographical ordering for @tex $x_4,\ldots,x_6$: @end tex @ifinfo x4,@dots{},x6: @end ifinfo @smallexample ring r = 7,(x(1..6)),(lp(3),dp); @end smallexample @item the localization of @math{(Q[a,b,c])[x,y,z]} at the maximal ideal @math{(x,y,z)}: @smallexample ring r = 0,(x,y,z,a,b,c),(ds(3), dp(3)); @end smallexample @item the ring @math{Q[x,y,z]} with weighted reverse lexicographical ordering. The variables @math{x}, @math{y}, and @math{z} have the weights 2, 1, and 3, respectively, and vectors are first ordered by components (in descending order) and then by monomials: @smallexample ring r = 0,(x,y,z),(c,wp(2,1,3)); @end smallexample For ascending component order, the component ordering @code{C} has to be used. @item the ring @math{K[x,y,z]}, where @math{K=Z/7(a,b,c)} denotes the transcendental extension of @math{Z/7} by @math{a}, @math{b}, and @math{c}, with degree lexicographical ordering: @smallexample ring r = (7,a,b,c),(x,y,z),Dp; @end smallexample @item the ring @math{K[x,y,z]}, where @math{K=Z/7[a]} denotes the algebraic extension of degree 2 of @math{Z/7} by @math{a}. In other words, @math{K} is the finite field with 49 elements. In the first case, @math{a} denotes an algebraic element over @math{Z/7} with minimal polynomial @tex $\mu_a=a^2+a+3$, @end tex @ifinfo mu_a=a^2+a+3, @end ifinfo in the second case, @math{a} refers to some generator of the cyclic group of unities of @math{K}: @smallexample ring r = (7,a),(x,y,z),dp; minpoly = a^2+a+3; ring r = (7^2,a),(x,y,z),dp; @end smallexample @item the ring @math{R'[x,y,z]}, where @math{R'} denotes the field of real numbers represented by simple precision floating point numbers: @smallexample ring r = real,(x,y,z),dp; @end smallexample @item the ring @math{R''[x,y,z]}, where @math{R''} denotes the field of real numbers represented by floating point numbers of 50 valid decimal digits (the maximal precision is 32767): @smallexample ring r = (real,50),(x,y,z),dp; @end smallexample @item the ring @math{R''(i)[x,y,z]}, where @math{R''} denotes the field of real numbers represented by floating point numbers of 50 valid decimal digits and @math{i} denotes the imaginary unit. @smallexample ring r = (real,50,i),(x,y,z),dp; @end smallexample @item the ring @math{R''(i)[x,y,z]}, where @math{R''} denotes the field of real numbers represented by floating point numbers of 6 valid decimal digits and @math{i} denotes the imaginary unit. @smallexample ring r = (real,i),(x,y,z),dp; @end smallexample @item the quotient ring @math{Z/7[x,y,z]} modulo the square of the maximal ideal @math{(x,y,z)}: @smallexample ring R = 7,(x,y,z), dp; qring r = std(maxideal(2)); @end smallexample @end itemize @c --------------------------------------------------------------------------- @node General syntax of a ring declaration, Term orderings, Examples of ring declarations, Rings and orderings @subsection General syntax of a ring declaration @cindex General syntax of a ring declaration @subsubheading Rings @c ------------------------------------------------------------ @c This piece of text (partially) exists also in the @c file types.doc, chapter "ring declarations". @c If you change something here, change it there, too! @c ------------------------------------------------------------ @table @strong @item Syntax: @code{ring} name @code{=} coefficient_field@code{,} @code{(} names_of_ring_variables @code{),} @code{(} ordering @code{);} @item Default: @code{32003,(x,y,z),(dp,C);} @item Purpose: declares a ring and sets it as the actual basering. @end table The coefficient_field is given by one of the following: @enumerate @item a non-negative int_expression less or equal 32003. @* The int_expression should either be 0, specifying the field of rational numbers Q, or a prime number p, specifying the finite field with p elements. If it is not a prime number, int_expression is converted to the next lower prime number. @item an expression_list of an int_expression and one or more names. @* The int_expression specifies the characteristic of the coefficient field as described above. The names are used as parameters in transcendental or algebraic extensions of the coefficient field. Algebraic extensions are implemented for one parameter only. In this case, a minimal polynomial has to be defined by assignment to @code{minpoly}. @xref{minpoly}. @item an expression_list of an int_expression and a name. @* The int_expression has to be a prime number p to the power of a positive integer n. This defines the Galois field @tex $\hbox{GF}(p^n)$ with $p^n$ elements, where $p^n$ has to be smaller or equal $2^{15}$. @end tex @ifinfo GF(p^n) with p^n elements, where p^n has to be smaller or equal 2^15. @end ifinfo The given name refers to a primitive element of @tex $\hbox{GF}(p^n)$ @end tex @ifinfo GF(p^n) @end ifinfo generating the multiplicative group. Due to a different internal representation, the arithmetic operations in these coefficient fields are faster than arithmetic operations in algebraic extensions as described above. @item the name @code{real}. @* This specifies the field of real numbers represented as machine floating point numbers. Note that computations over this field are not exact. @end enumerate The names_of_ring_variables is a list of names or indexed names. The ordering is a list of block orderings where each block ordering is either @enumerate @item @code{lp}, @code{dp}, @code{Dp}, @code{ls}, @code{ds}, or @code{Ds} optionally followed by a size parameter in parentheses. @item @code{wp}, @code{Wp}, @code{ws}, @code{Ws}, or @code{a} followed by a weight vector given as an intvec_expression in parentheses. @item @code{M} followed by an intmat_expression in parentheses. @item @code{c} or @code{C}. @end enumerate For the definition of the orderings, see @ref{Monomial orderings} and @ref{Monomial orderings}. If one of coefficient_field, names_of_ring_variables, and ordering consists of only one entry, the parentheses around this entry may be omitted. @c ------------------------------------------------------------ @c End of duplicate piece of text. @c ------------------------------------------------------------ @subsubheading Quotient rings @c ------------------------------------------------------------ @c This piece of text (partially) exists also in the @c file types.doc, chapter "qring declarations", and in @c singular.doc, chapter "Miscellaneous oddities". @c If you change something here, change it there, too! @c ------------------------------------------------------------ @table @strong @item Syntax: @code{qring} name @code{=} ideal_expression @code{;} @item Default: none @item Purpose: declares a quotient ring as the basering modulo ideal_expression. Sets it as current basering. @end table ideal_expression has to be represented by a standard basis. The most convenient way to map objects from a ring to its quotient ring and vice versa is to use the @code{fetch} function (@pxref{fetch}). @sc{Singular} computes in a quotient ring as long as possible with the given representative of a polynomial, say, @code{f}. I.e., it usually does not reduce @code{f} w.r.t. the quotient ideal. This is only done when necessary during standard bases computations or by an explicit reduction using the command @code{reduce(f, std(0))} (@pxref{reduce}). @strong{Example:} @smallexample @c example ring r=32003,(x,y),dp; poly f=x3+yx2+3y+4; qring q=std(maxideal(2)); basering; poly g=fetch(r, f); g; reduce(g,std(0)); @c example @end smallexample @c ------------------------------------------------------------ @c End of duplicate piece of text. @c ------------------------------------------------------------ @c --------------------------------------------------------------------------- @node Term orderings, , General syntax of a ring declaration, Rings and orderings @subsection Term orderings @cindex Monomial orderings, Term orderings Any polynomial (resp. vector) in @sc{Singular} is ordered w.r.t. a term ordering (or, monomial ordering), which has to be specified together with the declaration of a ring. @sc{Singular} stores and displays a polynomial (resp. vector) w.r.t. this ordering, i.e., the greates monomial (als called the leading monomial) comes first, and the smalles monomial comes last. @strong{Remark:} The novice user should generally use the ordering @code{dp} for computations in the polynomial ring @tex $K[x_1,\ldots,x_n]$, @end tex @ifinfo K[x1,...,xn], @end ifinfo resp. @code{ds} for computations in the localization @tex $\hbox{Loc}_{(x)}K[x_1,\ldots,x_n])$. @end tex @ifinfo Loc_(x)K[x1,...,xn]). @end ifinfo For more details, see @ref{Polynomial data}. In a ring declaration, @sc{Singular} offers the following orderings: @enumerate @item Global orderings @table @asis @item @code{lp} lexicographical ordering @item @code{dp} degree reverse lexicographical ordering @item @code{Dp} degree lexicographical ordering @item @code{wp(} intvec_expression @code{)} weighted reverse lexicographical ordering; the weight vector may consist of positive integers only. @item @code{Wp(} intvec_expression @code{)} weighted lexicographical ordering; the weight vector may consist of positive integers only. @end table Global orderings are well-orderings, i.e., @math{1 < x} for each ring variable @math{x}. They are denoted by a @code{p} as the second character in their name. @item Local orderings @table @asis @item @code{ls} negative lexicographical ordering @item @code{ds} negative degree reverse lexicographical ordering @item @code{Ds} negative degree lexicographical ordering @item @code{ws(} intvec_expression @code{)} (general) weighted reverse lexicographical ordering; the first element of the weight vector has to be non-zero. @item @code{Ws(} intvec_expression @code{)} (general) weighted lexicographical ordering; the first element of the weight vector has to be non-zero. @end table Local orderings are not well-orderings. They are denoted by an @code{s} as the second character in their name. @item Matrix orderings @table @asis @item @code{M(} intmat_expression @code{)} intmat_expression has to be an invertible square matrix @end table Using matrix orderings, @sc{Singular} can compute standard bases w.r.t.@: any monomial ordering that is compatible with the natural semi-group structure on the monomials. In practice, the predefined global and local orderings together with the block orderings should be sufficient in most cases. These orderings are faster than their corresponding matrix orderings since evaluation of a matrix ordering is time consuming. @item Extra weight vector @table @asis @item @code{a(} intvec_expression @code{)} an extra weight vector @code{a(} intvec_expression @code{)} may precede any monomial ordering @end table @item Product ordering @table @asis @item @code{(} ordering [ @code{(} int_expression @code{)} ]@code{,} @dots{} @code{)} any of the above orderings and the extra weight vector may be combined to yield product or block orderings @end table The orderings @code{lp}, @code{dp}, @code{Dp}, @code{ls}, @code{ds}, and @code{Ds} may be followed by an int_expression in parentheses giving the size of the block. For the last block the size is calculated automatically. For the weighted orderings the size of the block is given by the size of the weight vector. The same holds analogously for matrix orderings. @item Module orderings @table @asis @itemx @code{(} ordering@code{,} @dots{}@code{, C )} @item @code{(} ordering@code{,} @dots{}@code{, c )} sort polynomial vectors by the monomial ordering first, then by components @itemx @code{( C,} ordering@code{,} @dots{} @code{)} @item @code{( c,} ordering@code{,} @dots{} @code{)} sort polynomial vectors by components first, then by the monomial ordering @end table Here a capital @code{C} sorts generators in ascending order, i.e., @code{gen(1)} < @code{gen(2)} < @enddots{} A small @code{c} sorts in descending order, i.e., @code{gen(1)} > @code{gen(2)} > @enddots{} The module ordering has not to be specified explicitly since @code{(} ordering@code{,} @dots{}@code{, C )} is the default. In fact, @code{c} or @code{C} may be specified anywhere in a product ordering specification, not only at its beginning or end. All monomial block orderings preceding the component ordering have higher precedence, all monomial block orderings following after it have lower precedence. @end enumerate For a mathematical description of these orderings, see @ref{Polynomial data}. @c --------------------------------------------------------------------------- @node Implemented algorithms, The SINGULAR language, Rings and orderings, General concepts @section Implemented algorithms @cindex Implemented algorithms The basic algorithm in @sc{Singular} is a general standard basis algorithm for any monomial ordering which is compatible with the natural semi-group structure of the exponents. This includes well-orderings (Buchberger algorithm to compute a Groebner basis) and tangent cone orderings (Mora algorithm) as special cases. Nonetheless, there are a lot of other important algorithms: @itemize @bullet @item Algorithms to compute the standard operations on ideals and modules: intersection, ideal quotient, elimination, etc. @item Different Syzygy algorithms and algorithms to compute free resolutions of modules. @item Combinatorial algorithms to compute dimensions, Hilbert series, multiplicities, etc. @item Algorithms for univariate and multivariate polynomial factorization, resultant and gcd computations. @end itemize @c ---------------------------------------------------------------------- @subheading Commands to compute standard bases @table @code @item facstd @ref{facstd} @*computes a list of Groebner bases via the Factorizing Groebner Basis Algorithm, i.e., has the same radical as the original ideal. It need not be a Groebner basis of the given ideal. The intersection of the zero-sets is the zero-set of the given ideal. @item fglm @ref{fglm} @*computes a Groebner basis provided that a reduced Groebner basis w.r.t.@: another ordering is given. Implements the so-called FGLM (Faugere, Gianni, Lazard, Mora) algorithm. The given ideal must be zero-dimensional. @item groebner @ref{groebner}@* computes a standard resp.@: Groebner bases using a heuristically chosen method. This is the preferred method to compute a standard resp.@: Groebner bases. @item mstd @ref{mstd} @*computes a standard basis and a minimal set of generators. @item std @ref{std} @*computes a standard resp.@: Groebner basis. @item stdfglm @ref{stdfglm} @*computes a Groebner basis in a ring with a ``difficult'' ordering (e.g., lexicographical) via @code{std} w.r.t.@: a ``simple'' ordering and @code{fglm}. The given ideal must be zero-dimensional. @item stdhilb @ref{stdhilb}@* computes a Groebner basis in a ring with a ``difficult'' ordering (e.g., lexicographical) via @code{std} w.r.t.@: a ``simple'' ordering and a @code{std} computation guided by the Hilbert series. @end table @c ---------------------------------------------------------------------- @subheading Further processing of standard bases The next commands require the input to be a standard basis. @table @code @item degree @ref{degree} @*computes the (Krull) dimension, codimension and the multiplicity. The result is only displayed on the screen. @item dim @ref{dim}@* computes the dimension of the ideal resp.@: module. @item highcorner @ref{highcorner}@* computes the smallest monomial not contained in the ideal. The ideal has to be zero-dimensional. @item hilb @ref{hilb}@* computes the first and resp.@: or second Hilbert series of an ideal resp.@: module. @item kbase @ref{kbase}@* computes a vector space basis (consisting of monomials) of the quotient of a ring by an ideal resp.@: of a free module by a submodule. The ideal resp.@: module has to be finite dimensional and has to be represented by a standard basis w.r.t.@: the ring ordering. @item mult @ref{mult}@* computes the degree of the monomial ideal resp.@: module generated by the leading monomials of the input. @item reduce @ref{reduce}@* reduces a polynomial, vector, ideal or module to its normal form with respect to an ideal or module represented by a standard basis. @item vdim @ref{vdim}@* computes the vector space dimension of a ring (resp.@: free module) modulo an ideal (resp.@: module). @end table @c ---------------------------------------------------------------------- @subheading Commands to compute resolutions @table @code @item res @ref{res}@* computes a free resolution of an ideal or module using a heuristically chosen method. This is the preferred method to compute free resolutions of ideals or modules. @item lres @ref{lres}@* computes a free resolution of an ideal or module with LaScala's method. The input needs to be homogeneous. @item mres @ref{mres}@* computes a minimal free resolution of an ideal or module with the Syzygy method. @item sres @ref{sres}@* computes a free resolution of an ideal or module with Schreyer's method. The input has to be a standard basis. @item nres @ref{nres}@* computes a free resolution of an ideal or module with the standard basis method. @item minres @ref{minres}@* minimizes a free resolution of an ideal or module. @item syz @ref{syz}@* computes the first Syzygy (i.e., the module of relations of the given generators). @end table @c ---------------------------------------------------------------------- @subheading Further processing of resolutions @table @code @item betti @ref{betti}@* computes the graded Betti numbers of a module from a free resolution. @item minres @ref{minres}@* minimizes a free resolution of an ideal or module. @end table @c ---------------------------------------------------------------------- @subheading Processing of polynomials @table @code @item char_series @ref{char_series}@* computes characteristic sets of polynomial ideals. @item extgcd @ref{extgcd}@* computes the extended gcd of two polynomials. Implemented as extended Euclidean Algorithm. Applicable for univariate polynomials only. @item factorize @ref{factorize}@* computes factorization of univariate and multivariate polynomials into irreducible factors. The most basic algorithm is univariate factorization in prime characteristic. The Cantor-Zassenhaus Algorithm is used in this case. For characteristic 0, an univariate Hensel-lifting is done to lift from prime characteristic to characteristic 0. For multivariate factorization in any characteristic, the problem is reduced to the univariate case first, then a multivariate Hensel-lifting is used to lift the univariate factorization. Note that there is no factorization of polynomials over algebraic extensions of Q. @item gcd @ref{gcd}@* computes univariate and multivariate polynomial greatest common divisors. For prime characteristic, a subresultant gcd is used. In characteristic 0, a modular algorithm is used for the univariate case. For the multivariate case, the EZGCD is used. Note that there is no gcd calculation of polynomials over algebraic extensions of Q. @item resultant @ref{resultant}@* computes the resultant of two univariate polynomials using the subresultant algorithm. Multivariate polynomials are considered univariate polynomials in a main variable to be specified by the user. @end table @c ---------------------------------------------------------------------- @subheading Matrix computations @table @code @item bareiss @ref{bareiss}@* implements Gauss-Bareiss method for elimination (matrix triangularization) in arbitrary integral domains. @item det @ref{det}@* computes the determinant of a square matrix. For matrices with integer entries a modular algorithm is used. For other domains, elementary algorithms are used. @item minor @ref{minor}@* computes all minors (=subdeterminants) of a given size for a matrix. @end table @c ---------------------------------------------------------------------- @subheading Numeric computations @table @code @item laguerre @c @ref{laguerre}@* computes ... TBC @item uressolve @c @ref{uressolve}@* implements ... TBC @c @item vandermonde @c @ref{vandermonde}@* @c computes ... TBC @end table @c ---------------------------------------------------------------------- @subheading Controlling computations @table @code @item option @ref{option}@* allows to set options for manipulating the behaviour of computations (such as reduction strategies) and to show protocol information indicating the progress of a computation. @end table @c --------------------------------------------------------------------------- @node The SINGULAR language, Input and output, Implemented algorithms, General concepts @section The SINGULAR language @cindex The SINGULAR language @sc{Singular} interprets commands given interactively on the command line as well as given in the context of user-defined procedures. In fact, @sc{Singular} makes no distinction between these two cases. Thus, @sc{Singular} offers a powerful programming language as well as an easy-to-use command line interface without differences in syntax or semantics. In the following, the basic language concepts such as commands, expressions, names, objects, etc., are discussed. @xref{Procedures}, and @ref{Libraries}, for the concepts of procedures and libraries. In many aspects, the @sc{Singular} language is similar to the C programming language. For a description of some of the subtle differences, see @ref{Major differences to the C programming language}. @subsubheading Elements of the language The major building blocks of the @sc{Singular} language are expressions, commands, and control structures. The notion of expression in the @sc{Singular} and the C programming language are identical, whereas the notion of commands and control structures only roughly corresponds to the C statements. @itemize @bullet @item An ``expression'' is a sequence of operators, functions, and operands that specifies a computation. An expressions always results in a value of a specific type. @xref{Data types}, and its subsections (e.g., @ref{poly expressions}), for information on how to build expressions. @item A ``command'' is either a declaration, an assignment, a call to a function without return value, or a print command. For detailed information, see @ref{General command syntax}. @item ``Control structures'' determine the execution sequence of commands. @sc{Singular} provides control structures for conditional execution (@code{if} @dots{} @code{else}) and iteration (@code{for} and @code{while}). Commands may be grouped in pairs of @code{@{} @code{@}} (curly brackets) to form blocks. @xref{Control structures}, for more information. @end itemize @subsubheading Other notational conventions For user-defined functions, the notion of ``procedure'' and ``function'' are synonymous. As already mentioned above, functions without return values are called commands. Furthermore, whenever convenient, the term ``command'' is used for a function, even if it does return a value. @menu * General command syntax:: * Special characters:: * Names:: * Objects:: * Type conversion and casting:: * Flow control:: @end menu @c --------------------------------------------------------------------------- @node General command syntax, Special characters, The SINGULAR language, The SINGULAR language @subsection General command syntax @cindex General command syntax In @sc{Singular} a command is either a declaration, an assignment, a call to a function without return value, or a print command. The general form of a command is described in the following subsections. @subsubheading Declaration @enumerate @item type name @code{=} expression @code{;} @* declares a variable with the given name of the given type and assigns the expression as initial value to it. Expression is an expression of the specified type or one that can be converted to that type. @xref{Type conversion and casting}. @item type name_list @code{=} expression_list @code{;} @* declares variables with the given names and assigns successively each expression of expression_list to the corresponding name of name_list. Both lists must be of the same length. Each expression in expression_list is an expression of the specified type or one that can be converted to that type. @xref{Type conversion and casting}. @item type name @code{;} @* declares a variable with the given name of the given type and assigns the default value of the specific type to it. @end enumerate @xref{Names}, for more information on declarations. @xref{Data types}, for a description of all data types known to @sc{Singular}. @smallexample ring r; // the default ring poly f,g = x^2+y^3,xy+z2; // the polynomials f=x^2+y^3 and g=x*y+z^2 ideal I = f,g; // the ideal generated by f and g matrix m[3][3]; // a 3 x 3 zero matrix int i=2; // the integer i=2 @end smallexample @subsubheading Assignment @enumerate 3 @item name @code{=} expression @code{;} @* assigns expression to name. @item name_list @code{=} expression_list @code{;} @* assigns successively each expression of expression_list to the corresponding name of name_list. Both lists must be of the same length. This is not a simultaneous assignment. Thus, @code{f, g = g, f;} does not swap the values of @code{f} and @code{g}, but rather assigns @code{g} to both @code{f} and @code{g}. @end enumerate There must be a type conversion of the type of expression to the type of name. @xref{Type conversion and casting}. An assignment itself does not yield a value. Hence, compound assignments like @code{i = j = k;} are not allowed and result in an error. @smallexample f = x^2 + y^2 ; // overwrites the old value of f I = jacob(f); f,g = I[1],x^2+y^2 ; // overwrites the old values of f and g @end smallexample @subsubheading Function without return value @enumerate 5 @item function_name [ @code{(} argument_list @code{)} ] @code{;} @* calls function function_name with arguments argument_list. @end enumerate The function may have output (not to be confused with a return value of type string). @xref{Functions}. Functions without a return value are specified there to have a return type 'none'. Some of these functions have to be called without parentheses, e.g., @code{help}, @code{LIB}. @smallexample @c example ring r; ideal i=x2+y2,x; i=std(i); degree(i); // degree has no return value but prints output @c example @end smallexample @subsubheading Print command @enumerate 6 @item expression @code{;} @* prints the value of an expression, for smallexample, of a variable. @end enumerate Use the function @code{print} (or the procedure show from inout.lib) to get a pretty output of various data types, e.g., matrix or intmat. @xref{print}. @smallexample @c example int i=2; i; intmat m[2][2]=1,7,10,0; print(m); @c example @end smallexample @c ------------------------------------------------------------ @node Special characters, Names, General command syntax, The SINGULAR language @subsection Special characters @cindex Special characters The following characters and operators have special meaning: @table @asis @item @code{=} @cindex = assignment @item @code{(}, @code{)} @cindex ( @cindex ) in expressions, for indexed names and for argument lists @item @code{[}, @code{]} @cindex [ @cindex ] access operator for strings, integer vectors, ideals, matrices, polynomials, resolutions, and lists. Used to build vectors of polynomials. Example: @code{s[3]}, @code{m[1,3]}, @code{i[1..3]}, @code{[f,g+x,0,0,1]}. @item @code{+} @cindex + addition operator @item @code{-} @cindex - subtraction operator @item @code{*} @cindex * multiplication operator @item @code{/} @cindex / division operator. @xref{Miscellaneous oddities}, for the difference between the division operators @code{/} and @code{div}. @item @code{%} @cindex % modulo operator @item @code{^} or @code{**} @cindex ^ @cindex ** exponentiation operator @item @code{==} @cindex == comparison operator equal @item @code{!=} or @code{<>} @cindex != @cindex <> comparison operator not equal @item @code{>=} @cindex >= comparison operator bigger or equal @item @code{>} @cindex > comparison operator bigger @item @code{<=} @cindex <= comparison operator smaller or equal @item @code{<} @cindex < comparison operator smaller. Also used for file input. @xref{filecmd}. @item @code{!} @cindex ! boolean operator not @item @code{&&} @cindex && boolean operator and @item @code{||} @cindex || boolean operator or @item @code{"} @cindex " delimiter for string constants @item @code{`} @cindex ` delimiter for name substitution @item @code{?} @cindex ? synonym for @code{help} @item @code{//} @cindex // comment delimiter. Comment extends to end of line. @item @code{;} @cindex ; statement separator @item @code{,} separator for expression lists and function arguments @item @code{\} @cindex \ escape character for @code{"} and @code{\} within strings @item @code{..} @cindex .. interval specifier returning intvec. E.g., @code{1..3} which is equivalent to the intvec @code{1, 2, 3}. @item @code{_} @cindex _ value of expression last displayed @item @code{~} @cindex ~ breakpoint in procedures @item @code{#} @cindex # list of parameters in procedures without explicit parameter list @item @code{$} @cindex $ terminates @sc{Singular} @end table @c ------------------------------------------------------------ @node Names, Objects, Special characters, The SINGULAR language @subsection Names @cindex Names @sc{Singular} is a strongly typed language. This means that all names (= identifiers) have to be declared prior to their use. For the general syntax of a declaration, see the description of declaration commands (@pxref{General command syntax}). @xref{Data types}, for a description of @sc{Singular}'s data types. @xref{typeof}, for a short overview of possible types. To get information on a name and the object named by it, the @code{type} command may be used (@pxref{type}). It is possible to redefine an already existing name if doing so does not change its type. A redefinition first sets the variable to the default value and then computes the expression. The difference between redefining and overwriting a variable is shown in the following example: @smallexample @c example int i=3; i=i+1; // overwriting i; int i=i+1; // redefinition i; @c example @end smallexample User defined names should start with a letter and consist of letters and digits only. As an exception of this rule, the character @code{@@} may be used as part of a name, too. Capital and small letters are distinguished. Indexed names are built as a name followed by an int_expression in parentheses. A list of indexed names can be built as a name followed by an intvec_expression in parentheses. @smallexample @c example ring R; int n=3; ideal j(3); ideal j(n); // is equivalent to the above ideal j(2)=x; j(2..3); @c example @end smallexample Names may not coincide with reserved names (keywords). Type @code{reservedName();} to get a list of the reserved names. @xref{reservedName}. Names should not interfere with names of ring variables or, more generally, with monomials. @xref{Identifier resolution}. The most recently printed expression is available under the special name @code{_}, e.g., @smallexample @c example ring r; ideal i=x2+y3,y3+z4; std(i); ideal k=_; k*k+x; size(_[3]); @c example @end smallexample A string_expression enclosed in @code{`}@dots{}@code{`} (back ticks) evaluates to the value of the variable named by the string_expression. This feature is referred to as name substitution. @smallexample @c example int foo(1)=42; string bar="foo"; `bar+"(1)"`; @c example @end smallexample @c ------------------------------------------------------------ @node Objects, Type conversion and casting, Names, The SINGULAR language @subsection Objects @cindex Objects Every object in @sc{Singular} has a type and a value. In most cases it has also a name and in some cases an attribute list. The value of an object may be examined simply by printing it with a print command: object@code{;}. The type of an object may be determined by means of the @code{typeof} function, the attributes by means of the @code{attrib} function (@ref{typeof}, @ref{attrib}): @smallexample @c example ring r=0,x,dp; typeof(10); typeof(10000000000000000); typeof(r); attrib(x); attrib(std(ideal(x))); @c example @end smallexample Each object of type @code{poly}, @code{ideal}, @code{vector}, @code{module}, @code{map}, @code{matrix}, @code{number}, or @code{resolution} belongs to a specific ring. Also @code{list}, if at least one of the objects contained in the list belongs to a ring. These objects are local to the ring. Their names can be used for other objects in other rings. Objects from one ring can be mapped to another ring using maps or with the commands @code{fetch} or @code{imap}. @xref{map}, @ref{fetch}, @ref{imap}. All other types do not belong to a ring and can be accessed within every ring and across rings. They can be declared even if there is no active basering. @c ------------------------------------------------------------ @node Type conversion and casting, Flow control, Objects, The SINGULAR language @subsection Type conversion and casting @subsubheading Type conversion @cindex Type conversion Assignments convert the type of the right-hand side to the type of the left-hand side of the assignment, if possible. Operators and functions which require certain types of operands can also implicitly convert the type of an expression. It is, for example, possible to multiply a polynomial by an integer because the integer is automatically converted to a polynomial. Type conversions do not act transitively. Possible conversions are: @c ------------------------------------------------ @c Do not delete the leading `@ ' for indentation of the whole table. The @c table is indented since regular @tables are indented by a small amount, @c too. @c ------------------------------------------------ @multitable @columnfractions .05 .18 .81 @item @ 1. @tab @code{int} @tab @expansion{} @code{ideal} @item @ 2. @tab @code{poly} @tab @expansion{} @code{ideal} @item @ 3. @tab @code{intvec} @tab @expansion{} @code{intmat} @item @ 4. @tab @code{int} @tab @expansion{} @code{intvec} @item @ 5. @tab @code{int} @tab @expansion{} @code{intvec} @item @ 6. @tab @code{resolution} @tab @expansion{} @code{list} @item @ 7. @tab @code{ideal} @tab @expansion{} @code{matrix} @item @ 8. @tab @code{int} @tab @expansion{} @code{matrix} @item @ 9. @tab @code{intmat} @tab @expansion{} @code{matrix} @item @ 10. @tab @code{intvec} @tab @expansion{} @code{matrix} @item @ 11. @tab @code{module} @tab @expansion{} @code{matrix} @item @ 12. @tab @code{number} @tab @expansion{} @code{matrix} @item @ 13. @tab @code{poly} @tab @expansion{} @code{matrix} @item @ 14. @tab @code{vector} @tab @expansion{} @code{matrix} @item @ 15. @tab @code{ideal} @tab @expansion{} @code{module} @item @ 16. @tab @code{matrix} @tab @expansion{} @code{module} @item @ 17. @tab @code{vector} @tab @expansion{} @code{module} @item @ 18. @tab @code{int} @tab @expansion{} @code{number} @item @ 19. @tab @code{int} @tab @expansion{} @code{poly} @item @ 20. @tab @code{number} @tab @expansion{} @code{poly} @item @ 21. @tab @code{string} @tab @expansion{} @code{proc} @item @ 22. @tab @code{list} @tab @expansion{} @code{resolution} @item @ 23. @tab @code{int} @tab @expansion{} @code{vector} (i @expansion{} i*@code{gen(1)}) @item @ 24. @tab @code{poly} @tab @expansion{} @code{vector} (p @expansion{} p*@code{gen(1)}) @end multitable @subsubheading Type casting @cindex Type casting An expression can be casted to another type by using a type cast expression: @* type @code{(} expression @code{)}. Possible type casts are: @c ------------------------------------------------ @c Do not delete the leading `@ ' for indentation of the whole table. The @c table is indented since regular @tables are indented by a small amount, @c too. @c ------------------------------------------------ @multitable @columnfractions .05 .15 .83 @item @ @tab to @tab from @item @ @tab @code{ideal} @tab expression lists of @code{int}, @code{number}, @code{poly} @item @ @tab @code{ideal} @tab @code{int}, @code{matrix}, @code{module},@code{number}, @code{poly}, @code{vector} @item @ @tab @code{int} @tab @code{number}, @code{poly} @item @ @tab @code{intvec} @tab expression lists of @code{int}, @code{intmat} @item @ @tab @code{intmat} @tab @code{intvec} (@pxref{intmat type cast}) @item @ @tab @code{list} @tab expression lists of any type @item @ @tab @code{matrix} @tab @code{module}, @code{ideal}, @code{vector}, @code{matrix}. @* There are two forms to convert something to a matrix: if @code{matrix(} expression @code{)} is used then the size of the matrix is determined by the size of expression. @* But @code{matrix(} expression @code{,} m @code{,} n @code{)} may also be used - the result is a @tex $ m \times n $ @end tex @ifinfo m x n @end ifinfo matrix (@pxref{matrix type cast}) @item @ @tab @code{module} @tab expression lists of @code{int}, @code{number}, @code{poly}, @code{vector} @item @ @tab @code{module} @tab @code{ideal}, @code{matrix}, @code{vector} @item @ @tab @code{number} @tab @code{poly} @item @ @tab @code{poly} @tab @code{int}, @code{number} @item @ @tab @code{string} @tab any type (@pxref{string type cast}) @end multitable @strong{Example:} @smallexample @c example ring r=0,x,(c,dp); number(3x); number(poly(3)); ideal i=1,2,3,4,5,6; print(matrix(i)); print(matrix(i,3,2)); vector v=[1,2]; print(matrix(v)); module(matrix(i,3,2)); @c example @end smallexample @c ------------------------------------------------------------ @node Flow control, ,Type conversion and casting, The SINGULAR language @subsection Flow control @cindex Flow control @cindex block A block is a sequence of commands surrounded by @{ and @}. @smallexample @{ command; @dots{} @} @end smallexample Blocks are used whenever @sc{Singular} is used as a structured programming language. The @code{if} and @code{else} structures allow conditional execution of blocks (See @ref{if}, @ref{else}). @code{for} and @code{while} loops are available for repeated execution of blocks (See @ref{for}, @ref{while}). In procedure definitions the main part and the example section are blocks as well(See @ref{proc}). @menu * break:: * quit:: * keepring:: * export:: * if:: * else:: * for:: * while:: * proc:: * return:: * continue:: @end menu @c ---------------------------------------------------------------------- @c ---------------------------------------------------------------------- @node Input and output, Procedures, The SINGULAR language, General concepts @section Input and output @cindex input @cindex output @sc{Singular}'s input and output (short, I/O) is realized using links. Links are the communication channels of @sc{Singular}, i.e., something @sc{Singular} can write to and read from. In this section, a short overview of the usage of links and of the different link types is given. Even though library loading may be considered an I/O operation, too, this section does not treat loading of libraries (@pxref{LIB}). @subheading Monitoring A special form of I/O is monitoring. When monitoring is enabled, @sc{Singular} makes a typescript of everything printed on your terminal to a file. It is useful for students who need a hardcopy record of an interactive session as proof of an assignment. More generally, it is useful to create a protocol of a @sc{Singular} session. The @code{monitor} command enables and disables this feature (@pxref{monitor}). @subheading How to use links Besides the usual I/O functions @code{write} and @code{read}, there are also the functions @code{dump} and @code{getdump} which store resp.@: retrieve the content of an entire @sc{Singular} session to resp.@: from a link. The @code{dump} and @code{getdump} commands are not available for DBM links. For more information, see @ref{write}, @ref{read}, @ref{dump}, @ref{getdump}. @strong{Example:} @smallexample @c example ring r; poly p = x+y; dump("MPfile:w test.mp"); // dump the session to the file test.mp kill r; // kill the basering listvar(); getdump("MPfile:r test.mp");// read the dump from the file listvar(); @c example @end smallexample Specifying a link can be as easy as specifying a filename as a string. Except for MPtcp links, links even do not need to be explicitly opened or closed before resp.@: after they are used. To explicitly open or close a link, the @code{open} resp.@: @code{close} commands may be used (see @ref{open}, @ref{close}). Links have various properties which can be checked for using the @code{status} function (@pxref{status}). @strong{Example:} @smallexample @c example link l = "MPtcp:fork"; l; open(l); status(l, "open"); close(l); status(l, "open"); @c example @end smallexample @subheading ASCII links Data that can be converted to a string can be written into files for storage or communication with other programs. The data is written in plain ASCII format. Reading from an ASCII link returns a string --- conversion into other data is up to the user. This can be done, for example, using the command @code{execute} (@pxref{execute}). ASCII links should primarily be used for storing small amounts of data, especially if it might become necessary to manually inspect or manipulate the data. @xref{ASCII links}, for more information. @strong{Example:} @smallexample @c example // (over)write file test.ascii, link is specified as string write(":w test.ascii", "int i =", 3, ";"); // reading simply returns the string read("test.ascii"); // but now test.ascii is "executed" execute(read("test.ascii")); i; @c example @end smallexample @subheading MPfile links Data is stored in the binary MP format. Read and write access is very fast compared to ASCII links. All data (including such data that cannot be converted to a string) can be written to an MPfile link. Reading from an MPfile link returns the written expressions (i.e., not a string, in general). MPfile links should primarily be used for storing large amounts of data (like dumps of the content of an entire @sc{Singular} session), and if the data to be stored cannot be easily converted from or to a string (like rings, or maps). MPfile links are implemented on Unix-like operating systems only. @xref{MPfile links}, for more information. @strong{Example:} @smallexample @c example ring r; // (over)write MPfile test.mp, link is specified as string write("MPfile:w test.mp", x+y); kill r; def p = read("MPfile:r test.mp"); typeof(p); p; @c example @end smallexample @subheading MPtcp links Data is communicated with other processes (e.g., @sc{Singular} processes) which may run on the same or on different computers. Data exchange is accomplished using TCP/IP links in the binary MP format. Reading from an MPtcp link returns the written expressions (i.e., not a string, in general). MPtcp links should primarily be used for communications with other programs or for parallel computations (see, for example, @ref{Parallelization with MPtcp links}). MPtcp links are implemented on Unix-like operating systems only. @xref{MPtcp links}, for more information. @strong{Example:} @smallexample @c example ring r; link l = "MPtcp:launch"; // declare a link explicitly open(l); // needs an open, launches another SINGULAR as a server write(l, x+y); kill r; def p = read(l); typeof(p); p; close(l); // shuts down SINGULAR server @c example @end smallexample @subheading DBM links Data is stored in and accessed from a data base. Writing is accomplished by a key and a value and associates the value with the key in the specified data base. Reading is accomplished w.r.t.@: a key, whose associated value is returned. Both the key and the value have to be specified as strings. Hence, DBM links may be used only for data which may be converted to or from strings. DBM links should primarily be used when data needs to be accessed not in a sequential way (like with files) but in an associative way (like with data bases). @xref{DBM links}, for more information. @strong{Example:} @smallexample @c example ring r; // associate "x+y" with "mykey" write("DBM:w test.dbm", "mykey", string(x+y)); // get from data base what is stored under "mykey" execute(read("DBM: test.dbm", "mykey")); @c example @end smallexample @c --------------------------------------------------------------------------- @node Procedures, Libraries, Input and output, General concepts @section Procedures @cindex Procedures Procedures contain sequences of @sc{Singular}. They are used to extend the set of commands with user defined commands. Procedures are defined by either typing them in on the command line or by loading them from a so-called library file with the @ref{LIB} command. Procedures are invoked like normal built-in commands, i.e., by typing their name followed by the list of arguments in parentheses. The invocation then executes the sequence of commands stored in the specified procedure. All defined procedures can be displayed by the command @code{listvar(proc);}. @menu * Procedure definition:: * Names in procedures:: * Parameter list:: * Procedure commands:: @end menu @c ------------------------------------------------- @node Procedure definition, Names in procedures, Procedures, Procedures @subsection Procedure definition @cindex Procedure definition @c ------------------------------------------------------------ @c This piece of text exists also in the file types.doc, @c chapter "proc declaration". @c If you change something here, change it there, too! @c ------------------------------------------------------------ @table @strong @item Syntax: [@code{static}] @code{proc} proc_name [parameter_list] @*["help_text"] @*@code{@{} @* @tex \quad @end tex procedure_body @*@code{@}} @*[@code{smallexample} @*@code{@{} @* @tex \quad @end tex sequence_of_commands; @*@code{@}}] @item Purpose: defines a new function, the @code{proc} proc_name, with the additional information help_text, which is copied to the screen by @code{help proc_name;} and the @code{example} section which is executed by @code{example proc_name;}. @* The help_text, the parameter_list, and the smallexample section are optional. The default for a parameter_list is @code{(list #)}, see @ref{Parameter list}. The help and example sections are ignored if the procedure is defined @ifset namesapces interactively, i.e., if it was not loaded from a file by a @ref{load} command. @end ifset @ifclear namesapces interactively, i.e., if it was not loaded from a file by a @ref{LIB} command. @end ifclear @* Specifying @code{static} in front of the proc-definition (in a library file) makes this procedure local to the library, i.e., accessible only for the other procedures in the same library, but not for the users. So there is no reason anymore to define a procedure within another one (it just makes debugging harder). @end table @subsubheading Example of an interactive procedure definition @smallexample @c example proc milnor_number (poly p) { ideal i= std(jacob(p)); int m_nr=vdim(i); if (m_nr<0) { "// not an isolated singularity"; } return(m_nr); // the value of m_nr is returned } ring r1=0,(x,y,z),ds; poly p=x^2+y^2+z^5; milnor_number(p); @c example @end smallexample @subsubheading Example of a procedure definition in a library First, the library definition: @smallexample @c include sample.lib @end smallexample Now, we load the library and execute the procedures defined there: @smallexample @c example error LIB "sample.lib"; // load the library sample.lib example tab; // show an example "*"+tab(3)+"*"; // use the procedure tab // the static procedure internal_tab is not accessible "*"+Sample::internal_tab(3)+"*"; // show the help section for tab help tab; @c example @end smallexample @subsubheading Guidelines for the help section of a procedure The help text of a procedure should contain information about the usage, purpose, return values and generated objects. Particular assumptions or limitations should be listed. It should also be mentioned if global objects are generated or manipulated. The libraries contained in the @sc{Singular} distribution use the following format for the help text: @smallexample USAGE: (); [CREATE: ] RETURN: [NOTE: ] [SEE ALSO: ] EXAMPLE: example ; shows an example @end smallexample For more information, see also @ref{Typesetting of help strings}. @c --------------------------------------- @node Names in procedures, Parameter list, Procedure definition, Procedures @subsection Names in procedures @cindex Names in procedures @cindex local names All variables are local to the procedure they are defined in. Locally defined variables cannot interfere with names in other procedures and are automatically deleted after leaving the procedure. Internally, local variables are stored using the nesting level. A variable is said to have nesting level 1, if it is local to a procedure that was called interactively, nesting level 2, if is local to a procedure that was called by a procedure of nesting level 1 etc. @code{listvar()} also displays the nesting level, nesting level 0 is used for global objects (see @ref{listvar}). A ring may be 'moved up' by one nesting level with @code{keepring} (see @ref{keepring}). All variables living in that ring are moved together with that ring. To keep local variables after leaving the procedure, they have to be exported (i.e. made known) to some higher level by the @code{export} command (@pxref{export}). @strong{Example:} @smallexample @c example proc xxx { int k=4; //defines a local variable k int result=k+2; export(result); //defines the global variable "result". } xxx(); listvar(all); @c example @end smallexample Note that the variable @code{result} became a global variable after the execution of @code{xxx}. @c --------------------------------------- @node Parameter list, Procedure commands, Names in procedures, Procedures @subsection Parameter list @cindex Parameter list @table @code @item @strong{Syntax:} @code{( )} @*@code{(} parameter_definition @code{)} @item @strong{Purpose:} defines the number, type and names of the arguments to a @code{proc}. @*The parameter_list is optional. The default for a parameter_list is @code{(list #)} which means the arguments are referenced by @code{#[1], #[2]}, etc. @item @strong{Example:} @smallexample proc x0 @{ // can be called with ... // any number of arguments of any type: #[1], #[2],... // number of arguments: size(#) @} proc x1 () @{ ... // can only be called without arguments @} proc x2 (ideal i, int j) @{ ... // can only be called with 2 arguments, // which can be converted to ideal resp. int @} proc x3 (i,j) @{ ... // can only be called with 2 arguments // of any type // (i,j) is the same as (def i,def j) @} proc x5 (i,list #) @{ ... // can only be called with more than 1 argument // number of arguments: size(#)+1 @} @end smallexample @item @strong{Note:} @* The parameter_list may stretch across multiple lines. @* A parameter may have any type (including the types @code{proc} and @code{ring}). If a parameter is of type ring, then it can only be specified by name, but not with a type, e.g. @smallexample proc x6 (r) @{ ... // this is correct even if the parameter is a ring @} proc x7 (ring r) @{ ... // this is NOT CORRECT @} @end smallexample @end table @c --------------------------------------- ---------- @node Procedure commands, , Parameter list, Procedures @subsection Procedure commands @cindex Procedure commands @c ref See @ref{export}; @ref{keepring}; @ref{return}. @c ref @c ---------------------------------------------------------------------- @node Libraries, Debugging tools, Procedures, General concepts @section Libraries @cindex Libraries A library is a collection of @sc{Singular} procedures in a file. @*@sc{Singular} reads a library with the command @code{LIB}. General information about the library is displayed by the command @code{help lib_name}. After loading the library, its procedures can be used like the built-in @sc{Singular} functions. To have the full functionality of a built-in function (like checking of the type of parameters, automatic loading of necessary other libraries, help pages etc.), libraries have to comply with the syntax rules described below. @menu * Loading of a library:: * Format of a library:: * Guidelines for writing a library:: * Typesetting of help strings:: * template_lib:: @end menu @c --------------------------------------- @node Loading of a library, Format of a library,, Libraries @subsection Loading of a library @cindex Loading of a library @cindex path @cindex SINGULARPATH Libraries can be loaded with the @code{LIB} command: @c ------------------------------------------------------------ @c This piece of text exists also in the file reference.doc, @c chapter "LIB". @c chapter "load". @c If you change something here, change it there, too! @c ------------------------------------------------------------ @table @code @item @strong{Syntax:} @code{LIB} string_expression @code{;} @item @strong{Type:} none @item @strong{Purpose:} reads a library of procedures from a file. If the given filename does not start with @kbd{.} or @kbd{/}, the following directories are searched for (in that order): the current directory, the directories given in the environment variable @code{SINGULARPATH}, some default directories relative to the location of the @sc{Singular} executable program, and finally some default absolute directories. (For setting environment variables consult the manual of your shell). You can view the search path which @sc{Singular} uses to locate its libraries, by starting up @sc{Singular} with the option @code{-v}, or by issuing the command @code{system("with");}. Unless @sc{Singular} is started with the @code{--no-stdlib} option, the library @code{standard.lib} is automatically loaded at start-up time. @end table Only the names of the procedures in the library are loaded, the body of the procedures is read during the first call of this procedure. This minimizes memory consumption by unused procedures. When @sc{Singular} is started with the @code{-q} or @code{--quiet} option, no message about the loading of a library is displayed. More exactly, option @code{-q} (and likewise @code{--quiet}) unsets option @code{loadLib} to inhibit monitoring of library loading (@pxref{option}). All loaded libraries are displayed by the @code{LIB;} command: @smallexample @c example option(loadLib); // show loading of libraries; // standard.lib is loaded LIB; // the names of the procedures of inout.lib LIB "inout.lib"; // are now known to Singular LIB; @c example @end smallexample @c ref See @ref{Command line options}; @ref{Procedures and libraries}; @ref{SINGULAR libraries}; @ref{proc}; @ref{LIB}; @ref{standard_lib}; @ref{string}; @ref{system}. @c ref @c --------------------------------------- @node Format of a library, Guidelines for writing a library, Loading of a library, Libraries @subsection Format of a library @cindex Format of a library A library file can contain comments, an info- and version-string definition, @code{LIB} commands, @code{proc} commands and @code{proc} commands with @code{example} and @code{help} sections, i.e., the following keywords are allowed: @code{info}, @code{version}, @code{LIB}, @code{/* ... */}, @code{//}, @code{[static] proc}. Anything else is not recognized by the parser of @sc{Singular} and leads to an error message while loading the library. If an error occurs, loading is aborted and an error message is displayed, specifying the type of error and the line where it was detected. The info- and version-string are defined as follows: @cindex info in a library @table @code @item @strong{Syntax:} @code{info} = string_constant @code{;} @item @strong{Purpose:} defines the general help for the library. This text is displayed on @code{help lib_name;}. @item @strong{Example:} @smallexample info=" This could be the general help of an library. Quote must be escaped with an \ such as \" "; @end smallexample @item @strong{Note:} In the info-string the characters \ and " must be preceded by a \ (escaped). It is recommended that the info string is placed on the top of a library file and contains general information about the library as well as a listing of all procedures available to the users (with a one line description of each procedure). @end table @cindex version in a library @table @code @item @strong{Syntax:} @code{version} = string_constant @code{;} @item @strong{Purpose:} defines the version number for the library. It is displayed when the library is loaded. @item @strong{Example:} @smallexample version="$I@comment @comment !! Do not erase the @comment at the end of the previous line !! @comment !! It prevents cvs to substitute the id string !! d: sample.lib,v 1.2 1998/05/07 singular Exp $"; version="some version string"; @end smallexample @item @strong{Note:} It is common practice to simply define the version string to be @code{"$I}@comment @comment !! Do not erase the @comment at the end of the previous line !! @comment !! It prevents cvs to substitute the id string !! @code{d:$"} and let a version control system expand it. @end table @c --------------------------------------- @node Guidelines for writing a library, Typesetting of help strings, Format of a library, Libraries @subsection Guidelines for writing a library @cindex Guidelines for writing a library @cindex library Although there are very few enforced rules on how libraries are written (e.g., on whether or where the info- and version-string are defined), it is recommended that certain guidelines should be followed so that debugging and understanding are made easier. @enumerate @item The info- and version-string should appear at the beginning of the library, before procedure definitions. @item The info-string should have the following format: @smallexample info=" LIBRARY: AUTHOR: PROCEDURES: ; . . ; "; @end smallexample The purpose of the one line procedure descriptions is not to give a short help for the procedure, but to help the user decide what procedure might be the right one for the job. Details can then be found in the help section of each procedure. Therefore parameters may be omitted or abbreviated if necessary. For more information, see also @ref{Typesetting of help strings}. @item Each procedure which is not declared @code{static} should have a help and example section as explained in @ref{Procedure definition}. @item Each procedure which should not be accessible by users should be declared @code{static}. @item No procedures should be defined within the body of another procedure. @item It is often useful for a procedure to print out comments, either to explain results or to display intermediate computations. However, if this procedure is called by another procedure, such comments are confusing and disturbing in most cases. @sc{Singular} offers an elegant solution, which requires the usage of the @sc{Singular} function @ref{dbprint} and the reserved variables @ref{printlevel}, and @ref{voice} (@code{voice} counts the nesting of procedures; It has the value 1 on the top level, 2 inside the first procedure etc.; @code{printlevel} has the value 0 by default, but can be set to any integer value by the user). For example, if the following procedure @code{Test} is called directly from the top level then @samp{comment1} is displayed (i.e., printed out) but not @samp{comment2}; and nothing is displayed if @code{Test} is called from within any other procedure. However, if @code{printlevel} is set to a value k with k>0, then @samp{comment1} (resp. @samp{comment2} is displayed provided that @code{Test} is called from other procedures, with a nesting level up to k (resp. k-1). Note furthermore, that the example part of a procedure behaves in this respect like a procedure (i.e., the value of @code{voice} is 1). Therefore, the command @code{printlevel=1;} is necessary for @samp{comment1} to be displayed on @code{ smallexample Test;}. However, since printlevel is a global variable, it should be reset to the old value after at the end of the example part. @smallexample proc Test "USAGE: ... ... EXAMPLE: example Test; shows an example " @{ ... int p = printlevel - voice + 3; ... dbprint(p,"comment1"); dbprint(p-1,"comment2"); // dbprint prints only if p > 0 ... @} example @{ "EXAMPLE:"; echo = 2; int p = printlevel; //store old value of printlevel printlevel = 1; //assign new value to printlevel ... Test(); printlevel = p; //reset printlevel to old value @} @end smallexample @end enumerate @c @end table @c ---------------------------------------- @node Typesetting of help strings, template_lib, Guidelines for writing a library, Libraries @subsection Typesetting of help strings @cindex Typesetting of help strings The help and info strings of libraries which are included in the distribution of @sc{Singular} are parsed and automatically converted into the texinfo format (the typesetting language in which the documentation of @sc{Singular} is written. For optimal typesetting results, the guidelines for writing libraries and procedures should be followed, and the following points should be kept in mind: @itemize @bullet @item If a help string starts with a @code{@@} sign, then no parsing is done, and the info string is assumed to be already in the texinfo format. @item help strings are typeset within a @code{@@table @@asis} environment (which is similar to a latex @code{description} environment). @item If a line starts with a character and contains a colon, then the text up to the colon is taken to be the description-string of an item and the text following the colon is taken to be the content of the item. @item Descritptio @item If the description-string of an item matches @code{SEE ALSO}, then the content of the item is assumed to be comma-separted words which are valid references to other texinfo nodes of the manual. (e.g., all procedure and command names are also texinfo nodes). @item If the description-string of an item matches @code{PROCEDURES}, then the content of the item is assumed to be a summary description of the procedures contained in the library. Separate texinfo nodes (subsections in printed documents) are @strong{only} created out of the help strings of such procedures which appear in the summary description of a library. @item The content-string of an item is typeset as follows: @itemize @item If the content-string starts with an @code{@@} sign, then no parsing is done, but the content-string is assumed to be in the texinfo format. @item The texinfo commands @code{@@*}, @code{@@code@{..@}}, @code{@@math@{..@}} may be used to enforce linebreaks, and typesetting in typewriter font resp. math mode. Text inside @code{@@math@{..@}} need to be valid latex math markup. @item Words which are followed by matching round parenthesis (i.e., by @code{()}) are typeset using a typewriter font (like @code{myfunc()}). @item A linebreak is inserted in front of a line, if (1) the previous line is shorter than 60 characters and does not contain @code{@@code@{..@}} and @code{@@math@{..@}} constructs, or (2) if the first word of a line is followed by matching round parenthesis (like @code{myfunc()}), or (3) if the previous line does only consist of a word followed by matching parehtesis. @end itemize @end itemize See @ref{template_lib} for an examples of the automatic typesetting. @c ---------------------------------------- @node template_lib,, Typesetting of help strings, Libraries @subsection template_lib @cindex template_lib @cindex Template for writing a library First, we show the source-code of a template library: @smallexample @c include template.lib @end smallexample After typesetting, the library appears in the document as follows (with one subsection for each procedure): @c lib template.lib lib_fun lib_ex subsubsection @c ---------------------------------------------------------------------- @node Debugging tools, , Libraries, General concepts @section Debugging tools @cindex Debugging tools If @sc{Singular} does not come back to the prompt while calling a user defined procedure, probably a bracket or a @code{"} is missing. The easiest way to leave the procedure is to type some brackets or @code{"} and then @code{RETURN} . @menu * Tracing of procedures:: * Break points:: * Printing of data:: * libparse:: @end menu @c --------------------------------------- @node Tracing of procedures, Break points, Debugging tools, Debugging tools @subsection Tracing of procedures Setting the @code{TRACE} variable to 1 (resp. 3) results in a listing of the called procedures (resp. together with line numbers). If @code{TRACE} is set to 4, @code{Singular} displays each line before its interpretation and waits for the @code{RETURN} key being pressed. @menu * TRACE var:: @end menu @iftex See @ref{TRACE var}. @end iftex @strong{Example:} @smallexample @c example proc t1 { int i=2; while (i>0) { i=i-1; } } TRACE=3; t1(); @c example @end smallexample @c --------------------------------------- @node Break points, Printing of data, Tracing of procedures, Debugging tools @subsection Break points A break point can be put into a proc by inserting the command @code{~}. If @code{Singular} reaches a break point it asks for lines of commands (line-length must be less than 80 characters) from the user. It returns to normal execution if given an empty line. See @ref{~}. @strong{Example:} @smallexample proc t @{ int i=2; ~; return(i+1); @} t(); @expansion{} -- break point in t -- @expansion{} -- 0: called from STDIN -- i; // here local variables of the procedure can be accessed @expansion{} 2 @expansion{} -- break point in t -- @expansion{} 3 @end smallexample @sp 2 @c --------------------------------------- @node Printing of data,libparse,Break points,Debugging tools @subsection Printing of data The procedure @code{dbprint} is useful for optional output of data: it takes 2 arguments and prints the second argument, if the first argument is positive; it does nothing otherwise. @menu * dbprint:: * voice:: @end menu @ifnothtml @iftex See @ref{dbprint}; @ref{voice}. @end iftex @end ifnothtml @c --------------------------------------- @node libparse,,Printing of data,Debugging tools @subsection libparse @cindex libparse @code{libparse} is a stand-alone program contained in the @sc{Singular} distribution (at the place where the @sc{Singular} executable program resides), which cannot be called inside of @sc{Singular}. It is a debugging tool for libraries which performs exactly the same checks as @ifset namespaces the @code{load} command in @sc{Singular}, but generates more output during @end ifset @ifclear namespaces the @code{LIB} command in @sc{Singular}, but generates more output during @end ifclear parsing. @code{libparse} is useful if an error occurs while loading the library, but the whole block around the line specified seems to be correct. In these situations the real error might be hundreds of lines earlier in the library. @strong{Usage:} @*@code{libparse [options] singular-library} @*@strong{Options:} @table @asis @item @code{-d} Debuglevel increases the amount of output during parsing, where Debuglevel is an integer between 0 and 4. Default is 0. @item @code{-s} turns on reporting about violations of unenforced syntax rules @end table The following syntax checks are performed in any case: @itemize @bullet @item counting of pairs of brackets @{,@} , [,] and (,) (number of @{ has to match number of @}, same for [,] and (,) ). @item counting of " ( number of " must be even ). @item general library syntax ( only LIB, static, proc (with parameters, help, body and example) and comments, i.e // and @code{/* ... */} are allowed). @end itemize Its output lists all procedures that have been parsed successfully: @smallexample $ libparse sample.lib Checking library 'sample.lib' Library function line,start-eod line,body-eob line,example-eoe Version:0.0.0; g Sample tab line 9, 149-165 13, 271-298 14, 300-402 l Sample internal_tab line 24, 450-475 25, 476-496 0, 0-496 @end smallexample where the following abbreviations are used: @itemize @bullet @item g: global procedure (default) @item l: static procedure, i.e., local to the library. @end itemize each of the following is the position of the byte in the library. @itemize @bullet @item start: begin of 'proc' @item eod: end of parameters @item body: start of procedurebody '@{' @item eob: end of procedurebody '@}' @item example: position of 'smallexample' @item eoe: end of smallexample '@}' @end itemize Hence in the above example, the first procedure of the library sample.lib is user-accessible and its name is tab. The procedure starts in line 9, at character 149. The head of the procedure ends at character 165, the body starts in line 13 at character 271 and ends at character 298. The example section extends from line 14 character 300 to character 402. The following example shows the result of a missing close-bracket @} in line 26 of the library @code{sample.lib}. @smallexample LIB "sample.lib"; @expansion{} ? Library sample.lib: ERROR occurred: in line 26, 497. @expansion{} ? missing close bracket '@}' at end of library in line 26. @expansion{} ? Cannot load library,... aborting. @expansion{} ? error occurred in STDIN line 1: `LIB "sample.lib";` @end smallexample