code.consxy.com Git - clnl/blob - docs/DocsMain.md

   1 # Package CLNL
   2
   3 Main CLNL package
   4
   5 The entry point for general purpose clnl startup, as well as the place that ties all the parts together into a cohesive whole.
   6
   7 ## Contents
   8
   9 * **variable [\*model\-package\*](#variable-model-package)** - _*model-package*_ is used for interning symbols as a NetLogo code gets compiled.
  10 * **function [boot](#function-boot)** - _boot_ does exactly that, boots the clnl system in a clean state.  The seed is set so that multiple runs will evaluate to the same.
  11 * **function [model->multi-form-lisp](#function-model->multi-form-lisp)** - _model->multi-form-lisp_ takes a model and returns a multi form lisp program, that when executed, sets up the model.  Procedures map to defuns, globals to defvars, etc.  This can be output to load up quickly later.  A function named by _boot-fn_ will be set for booting the program.
  12 * **function [model->single-form-lisp](#function-model->single-form-lisp)** - _model->single-form-lisp_ takes a model and returns a lisp program as a single form, that when executed runs the model.  The _seed_ passed in is used to start the clnl-random RNG.
  13 * **function [nlogo->lisp](#function-nlogo->lisp)** - _nlogo->lisp_ takes a stream _str_ and returns a multi form lisp program, that when executed, sets up the model.  See MODEL->MULTI-FORM-LISP for more information.
  14 * **function [run](#function-run)** - _run_ starts up the CLNL system.
  15 * **function [run-commands](#function-run-commands)** - _run-commands_ will take NetLogo commands, put them through the various stages need to turn them into Common Lisp code, and run it.
  16 * **function [run-reporter](#function-run-reporter)** - _run-reporter_ will take a NetLogo _reporter_, put it through the various stages need to turn them into Common Lisp code, run it, and return the _result_.
  17
  18 ## Variable \*MODEL\-PACKAGE\*
  19
  20 #### Value Type:
  21
  22 a package
  23
  24 #### Initial Value:
  25
  26 The package named by :clnl-default-model-package
  27
  28 #### Description:
  29
  30 _*model-package*_ is used for interning symbols as a NetLogo code gets compiled.
  31
  32 :clnl-default-model-package is used because it's set up to shadow common overlaps between the :cl package and netlogo programs, most notably GO.  When you set this to a package of your choosing, be aware of those overlaps in the case that use :use :common-lisp
  33
  34 Any local symbols are interned in this package, for use either by other code, or in order to have all symbols interned in the same placakge.  This is also the package in which a model should be run, whether by clnl code or independently.
  35
  36 ## Function **BOOT**
  37
  38 #### Syntax:
  39
  40 **boot** _&optional_ _file_ _headless-mode_ => _result_
  41
  42 #### Arguments and Values:
  43
  44 _file_---nlogo file with which to initialize state
  45 _headless-mode_---a boolean, defaults to nil
  46 _result_---undefined
  47
  48 #### Description:
  49
  50 _boot_ does exactly that, boots the clnl system in a clean state.  The seed is set so that multiple runs will evaluate to the same.
  51
  52 When _file_ is not provided, a default model is used.
  53
  54 When _headless-mode_ is set to nil, the opengl interface is initialized. Otherwise, the model will run headlessly, with no view.
  55
  56 ## Function **MODEL->MULTI-FORM-LISP**
  57
  58 #### Syntax:
  59
  60 **model->multi-form-lisp** _model_ _boot-fn_ _&key_ _seed_ _initialize-interface_ _netlogo-callback-fn_ => _forms_
  61
  62 #### Arguments and Values:
  63
  64 _model_---A valid model
  65 _boot-fn_---A function name
  66 _seed_---An integer, defaults to 15
  67 _initialize-interface_---A boolean
  68 _netlogo-callback-fn_---a symbol
  69 _forms_---A list of common lisp form
  70
  71 #### Description:
  72
  73 _model->multi-form-lisp_ takes a model and returns a multi form lisp program, that when executed, sets up the model.  Procedures map to defuns, globals to defvars, etc.  This can be output to load up quickly later.  A function named by _boot-fn_ will be set for booting the program.
  74
  75 The _seed_ passed in is used to start the clnl-random RNG.
  76
  77 _initialize-interface_, when non nil, leads to initialization code for the opengl interface being included.
  78
  79 _netlogo-callback-fn_ is a symbol that will be defined as a function to be called to execute code in the running netlogo instance.
  80
  81 ## Function **MODEL->SINGLE-FORM-LISP**
  82
  83 #### Syntax:
  84
  85 **model->single-form-lisp** _model_ _&key_ _seed_ _initialize-interface_ _netlogo-callback_ => _form_
  86
  87 #### Arguments and Values:
  88
  89 _model_---A valid model
  90 _seed_---An integer, defaults to 15
  91 _initialize-interface_---A boolean
  92 _netlogo-callback_---A function of one argument, or a symbol
  93 _form_---A common lisp form
  94
  95 #### Description:
  96
  97 _model->single-form-lisp_ takes a model and returns a lisp program as a single form, that when executed runs the model.  The _seed_ passed in is used to start the clnl-random RNG.
  98
  99 _initialize-interface_, when non nil, leads to initialization code for the opengl interface being included.
 100
 101 _netlogo-callback_ is a function that when called with a single argument, a function that when called with netlogo code, will compile and run that code in the environment of the model.
 102
 103 Of note, all globals defined either in the model code or via the widgets are declared special in order to remain in the lexical environment for EVAL.
 104
 105 ## Function **NLOGO->LISP**
 106
 107 #### Syntax:
 108
 109 **nlogo->lisp** _str_ _pkg-symb_ _boot-fn_ _&key_ _seed_ _initialize-interface_ _netlogo-callback-fn_ => _forms_
 110
 111 #### Arguments and Values:
 112
 113 _str_---A stream holding an nlogo file
 114 _pkg-symb_---A symbol for the generated package
 115 _boot-fn_---A function name
 116 _seed_---An integer, defaults to 15
 117 _initialize-interface_---A boolean
 118 _netlogo-callback-fn_---a symbol
 119 _forms_---A list of common lisp form
 120
 121 #### Description:
 122
 123 _nlogo->lisp_ takes a stream _str_ and returns a multi form lisp program, that when executed, sets up the model.  See MODEL->MULTI-FORM-LISP for more information.
 124
 125 _nlogo->lisp_ does extra work of setting up the package to be named by _pkg-symb_ in order to correctly shadow common lisp functions.
 126
 127 It will also change the current package to the one created for the model named by _pkg-symb_.
 128
 129 #### Examples:
 130
 131 ```(with-open-file (str "Wolf Sheep Predation.nlogo") (nlogo->lisp str :wolfsheep 'boot))``` => ```(forms)```
 132
 133 ## Function **RUN**
 134
 135 #### Syntax:
 136
 137 **run** _&optional_ _file_ => _result_
 138
 139 #### Arguments and Values:
 140
 141 _file_---nlogo file with which to initialize
 142 _result_---undefined, the system terminates at the end of the loop
 143
 144 #### Description:
 145
 146 _run_ starts up the CLNL system.
 147
 148 ## Function **RUN-COMMANDS**
 149
 150 #### Syntax:
 151
 152 **run-commands** _cmds_ => _result_
 153
 154 #### Arguments and Values:
 155
 156 _cmds_---A string that may have one more NetLogo commands
 157 _result_---undefined
 158
 159 #### Description:
 160
 161 _run-commands_ will take NetLogo commands, put them through the various stages need to turn them into Common Lisp code, and run it.
 162
 163 ## Function **RUN-REPORTER**
 164
 165 #### Syntax:
 166
 167 **run-reporter** _reporter_ => _result_
 168
 169 #### Arguments and Values:
 170
 171 _reporter_---A string that should have only one reporter
 172 _result_---The value reported by the NVM
 173
 174 #### Description:
 175
 176 _run-reporter_ will take a NetLogo _reporter_, put it through the various stages need to turn them into Common Lisp code, run it, and return the _result_.