source: git/Singular/HOWTO.addKernelCmds @ 117805

spielwiese
Last change on this file since 117805 was 117805, checked in by Hans Schoenemann <hannes@…>, 5 years ago
new commands should go to dynamic modules
  • Property mode set to 100644
File size: 5.2 KB
Line 
1How 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
14extern "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-----------------------------------------------------------------------------
21The following describes how the main Singular kernel commands were constructed,
22but we do not want to change this any more as this would change the Singular
23language (unless an error is found).
24The files not to change are: grammar.y, scanner.l, table.h, tok.h
25and the derived files: grammar.cc, grammar.h, scanner.cc, iparith.inc
26If one of these files really need a change, run make_grammar (for grammar.*)
27or make_table (for table.h).
28The following text serves only as a remainder how iiExprArith etc. work:
29
30Example: 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 ommited,
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
88Remark: the wrapper routines jjBLA* should be implemented as
89    static routines in Singular/iparith.cc
90
91Remark: 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
108Remark: 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
123Remark: 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
Note: See TracBrowser for help on using the repository browser.