1 | How to add new kernel commands |
---|
2 | - create a new dynamic module, add your new commands as PROC: |
---|
3 | - create a sub directory of Singular/dyn_modules: Singular/dyn_modules/bla |
---|
4 | - add the name of your sub directory to Singular/dyn_modules/Makefile.am |
---|
5 | - create Singular/dyn_modules/bla/Makefile.am |
---|
6 | (have a look at the other Singular/dyn_modules/*/Makefile.am for an example) |
---|
7 | - your module must contain the following initialization routine, |
---|
8 | where "bla" refers to the (Singular) name for your new procedure |
---|
9 | and bla_proc refers to the C++-implementation of it with |
---|
10 | the following head: static BOOLEAN bla_proc(leftv result, leftv args) |
---|
11 | |
---|
12 | //------------------------------------------------------------------------ |
---|
13 | // initialisation of the module |
---|
14 | extern "C" int SI_MOD_INIT(bla)(SModulFunctions* p) |
---|
15 | { |
---|
16 | p->iiAddCproc("bla.so","bla",FALSE,bla_proc); |
---|
17 | return (MAX_TOK); |
---|
18 | } |
---|
19 | |
---|
20 | ----------------------------------------------------------------------------- |
---|
21 | The following describes how the main Singular kernel commands were constructed, |
---|
22 | but we do not want to change this any more as this would change the Singular |
---|
23 | language (unless an error is found). |
---|
24 | The files not to change are: grammar.y, scanner.l, table.h, tok.h |
---|
25 | and the derived files: grammar.cc, grammar.h, scanner.cc, iparith.inc |
---|
26 | If one of these files really need a change, run make_grammar (for grammar.*) |
---|
27 | or make_table (for table.h). |
---|
28 | The following text serves only as a remainder how iiExprArith etc. work: |
---|
29 | |
---|
30 | Example: bla |
---|
31 | |
---|
32 | - add a new CMD token to tok.h (in alphabetic order): |
---|
33 | .... |
---|
34 | BLA_CMD, |
---|
35 | ... |
---|
36 | - decide, how many argument bla should have and find the tok_type: |
---|
37 | 1: CMD_1 |
---|
38 | 2: CMD_2 |
---|
39 | 3:Â CMD_3 |
---|
40 | 1 or 2: CMD_12 |
---|
41 | 1 or 3: CMD_13 |
---|
42 | 2 or 3: CMD_23 |
---|
43 | 1, 2 or 3: CMD_123 |
---|
44 | not covered above: CMD_M |
---|
45 | |
---|
46 | - add a line describing the name, the token and the tok_type |
---|
47 | to array cmds in Singular/table.h: |
---|
48 | { "bla", 0, BLA_CMD, CMD_1}, |
---|
49 | (the array is sorted by the name). |
---|
50 | |
---|
51 | - choose the requirements: one from each group, combined by | |
---|
52 | ALLOW_PLURAL: non-commutative rings allowed |
---|
53 | NO_PLURAL: non-commutative rings not allowed |
---|
54 | |
---|
55 | ALLOW_RING: coefficients/cring elements may be a ring |
---|
56 | NO_RING: coefficients/cring elements must be a field |
---|
57 | |
---|
58 | ALLOW_ZERODIVISOR: coefficients/cring elements may be zero divisors |
---|
59 | NO_ZERODIVISOR: coefficients/cring elements must be a domain |
---|
60 | |
---|
61 | if a requirement from a group is omited, |
---|
62 | the defaults are: NO_PLURAL | NO_RING | ALLOW_ZERODIVISOR |
---|
63 | |
---|
64 | - add one (or more) lines for the procedures to call: |
---|
65 | if there is more than one line, all lines for the same operation |
---|
66 | must directly following each other within dArith* |
---|
67 | |
---|
68 | if tok_type is CMD_1, CND_12, CMD_13, CMD_123, |
---|
69 | to dArith1: |
---|
70 | ,{D(jjBLAH1), BLA_CMD, <return type>, <argument type> , ALLOW_PLURAL |ALLOW_RING} |
---|
71 | |
---|
72 | analog for CMD_12, CMD_2, CMD_23, CMD_123 |
---|
73 | to dArith2: |
---|
74 | ,{D(jjBLAH2), BLA_CMD, <return type>, <arg1 type>, <arg2 type>, ALLOW_PLURAL |ALLOW_RING} |
---|
75 | |
---|
76 | analog for CMD_13, CMD_23, CMD_123, CMD_3 |
---|
77 | to dArith3: |
---|
78 | ,{D(jjBLAH3), BLA_CMD, <return type>, <arg1 type>, <arg2 type>, <arg3 type>, ALLOW_PLURAL |ALLOW_RING} |
---|
79 | |
---|
80 | CMD_M is different: |
---|
81 | ,{D(jjBLA_M), BLA_CMD, <return type>, <number of arguments>, ALLOW_PLURAL |ALLOW_RING} |
---|
82 | |
---|
83 | |
---|
84 | where a negative "number of arguments" represents: |
---|
85 | -1: any number of arguments |
---|
86 | -2: any number of arguments >0 |
---|
87 | |
---|
88 | Remark: the wrapper routines jjBLA* should be implemented as |
---|
89 | static routines in Singular/iparith.cc |
---|
90 | |
---|
91 | Remark: valid types for return type/arguments type are: |
---|
92 | - types from table.h: cmds with tok_type ROOT_DECL |
---|
93 | - types from table.h: cmds with tok_type ROOT_DECL_LIST |
---|
94 | - types from table.h: cmds with tok_type RING_DECL |
---|
95 | (require a base ring/currRing!=NULL) |
---|
96 | - types from table.h: cmds with tok_type RING_DECL_LIST |
---|
97 | (require a base ring/currRing!=NULL) |
---|
98 | - matrix types: INTMAT_CMD, BIGINTMAT_CMD, MATRIX_CMD |
---|
99 | (MATRIX_CMD requires a base ring/currRing!=NULL) |
---|
100 | - pseudo types for arguments: |
---|
101 | IDHDL: argument must be an interpreter variable |
---|
102 | ANY_TYPE: changes to pseudo data (for "defined", "typeof", etc.) |
---|
103 | - pseudo types for results: |
---|
104 | NONE: void |
---|
105 | ANY_TYPE: the jjBLA* routine decides about the return type |
---|
106 | (including NONE) |
---|
107 | |
---|
108 | Remark: the order of these lines is important: |
---|
109 | first the interpreter tries a perfect match of the data types, |
---|
110 | but, if none is found, the second pass tries automatic type conversion |
---|
111 | starting with the first line: |
---|
112 | for example: bla(<matrix>,<module>) |
---|
113 | ,{D(jjBLAH21), BLA_CMD, <return type>, MATRIX_CMD, MATRIX_CMD, ALLOW_PLURAL |ALLOW_RING} |
---|
114 | ,{D(jjBLAH22), BLA_CMD, <return type>, MODUL_CMD, MODUL_CMD, ALLOW_PLURAL |ALLOW_RING} |
---|
115 | would call jjBLAH21, while |
---|
116 | ,{D(jjBLAH22), BLA_CMD, <return type>, MODUL_CMD, MODUL_CMD, ALLOW_PLURAL |ALLOW_RING} |
---|
117 | ,{D(jjBLAH21), BLA_CMD, <return type>, MATRIX_CMD, MATRIX_CMD, ALLOW_PLURAL |ALLOW_RING} |
---|
118 | would call jjBLAH22. |
---|
119 | If certain conversions should not be allowed, add a line/several lines like: |
---|
120 | ,{jjWRONG, BLA_CMD, NONE, MATRIX_CMD, MODUL_CMD, ALLOW_PLURAL |ALLOW_RING} |
---|
121 | at the end of the block with operations for "bla". |
---|
122 | |
---|
123 | Remark: alias: 0: normal reserved word |
---|
124 | 1: alias for an reserver word: allowed as input, never as output |
---|
125 | 2: outdated alias: allowed as input, never as output, |
---|
126 | output a warning at first use |
---|