Update documentation after 0.1.1 release
[clnl] / docs / DocsOtherPackages.md
diff --git a/docs/DocsOtherPackages.md b/docs/DocsOtherPackages.md
new file mode 100644 (file)
index 0000000..2bd4998
--- /dev/null
@@ -0,0 +1,742 @@
+# Package CLNL-INTERFACE
+
+CLNL Interface
+
+The NetLogo view interface using opengl.  This is responsible for taking the current state of the enging and displaying it.  Will not house any interface components.
+
+## Contents
+
+* **function [export-view](#function-export-view)** - _export-view_ returns the current view in raw data of RGBA pixels.
+* **function [initialize](#function-initialize)** - This is where the initialization of the interface that sits behind the interface lives.  From here, one can go into headless or running mode, but for certain things this interface will still need to act, and also allows for bringing up and taking down of visual elements.
+* **function [run](#function-run)** - _run_ runs the view in an external window.
+
+## Function **EXPORT-VIEW**
+
+#### Syntax:
+
+**export-view** => _image-data_
+
+#### Arguments and Values:
+
+_image-data_---A vector, pixel data as returned by opengls readPixels  
+
+#### Description:
+
+_export-view_ returns the current view in raw data of RGBA pixels.
+
+Each pixel is made up of 4 bytes of data, which an be walked over.  The number of pixels is the current width x height.  Converting to some other image format is a matter of pulling that information out and putting it into whatever format you like.
+
+This requires opengl to run, but can be used with xvfb in a headless mode.
+
+## Function **INITIALIZE**
+
+#### Syntax:
+
+**initialize** _&key_ _dims_ _view_ _buttons_ _switches_ => _result_
+
+```dims::= (:xmin xmin :xmax xmax :ymin ymin :ymax ymax :patch-size patch-size)```  
+```view::= (:left left :top top)```  
+```buttons::= button-def*```  
+```switches::= switch-def*```  
+```button-def::= (:left left :top top :height height :width width :forever forever :display display)```  
+```switch-def::= (:left left :top top :width width :var var :display display :initial-value initial-value)```  
+
+#### Arguments and Values:
+
+_result_---undefined  
+_xmin_---An integer representing the minimum patch coord in X  
+_xmax_---An integer representing the maximum patch coord in X  
+_ymin_---An integer representing the minimum patch coord in Y  
+_ymax_---An integer representing the maximum patch coord in Y  
+_patch-size_---A double representing the size of the patches in pixels  
+_height_---An integer representing height  
+_forever_---A boolean representing the forever status  
+_left_---An integer representing the left position  
+_top_---An integer representing the top position  
+_width_---An integer representing width  
+_var_---A string representing the variable name  
+_display_---A string representing display name  
+_initial-value_---The initial value  
+
+#### Description:
+
+This is where the initialization of the interface that sits behind the interface lives.  From here, one can go into headless or running mode, but for certain things this interface will still need to act, and also allows for bringing up and taking down of visual elements.
+
+## Function **RUN**
+
+#### Syntax:
+
+**run** => _result_
+
+#### Arguments and Values:
+
+_result_---undefined, should never get here  
+
+#### Description:
+
+_run_ runs the view in an external window.
+
+This should be run inside another thread as it starts the glut main-loop. Closing this window will then cause the entire program to terminate.
+# Package CLNL-LEXER
+
+CLNL Lexer
+
+The primary code responsible for tokenizing NetLogo code.
+
+## Contents
+
+* **function [lex](#function-lex)** - _lex_ lexes NetLogo code.
+
+## Function **LEX**
+
+#### Syntax:
+
+**lex** _text_ => _ast_
+
+#### Arguments and Values:
+
+_text_---Some NetLogo code  
+_ast_---An ambigious _ast_ that can later be parsed  
+
+#### Description:
+
+_lex_ lexes NetLogo code.
+
+_lex_ checks for some things, in as much as it can without knowing anything about some of the backgrounds of NetLogo.  However, it does the first pass with as much as it can.
+# Package CLNL-PARSER
+
+CLNL Parser
+
+All the code to convert the list of tokens coming from the lexer into an ast that can be transpiled later.
+
+## Contents
+
+* **function [parse](#function-parse)** - _parse_ takes a ambigious _lexed-ast_ and converts it to an unambigious one.
+
+## Function **PARSE**
+
+#### Syntax:
+
+**parse** _lexed-ast_ _&optional_ _dynamic-prims_ => _ast_
+
+```dynamic-prims::= dynamic-prim*```  
+```dynamic-prim::= (:name name :args args :infix infix :precedence precedence)```  
+```args::= arg*```  
+
+#### Arguments and Values:
+
+_lexed-ast_---An ambigious ast  
+_ast_---An unambigious ast that can be transpiled  
+_name_---A symbol in the keyword package  
+_infix_---Boolean denoting whether the prim is infix, defaulting to NIL  
+_precedence_---A number, usually 10 for reporters, and 0 for commands  
+_arg_---A list of symbols denoting the type of argument  
+
+#### Description:
+
+_parse_ takes a ambigious _lexed-ast_ and converts it to an unambigious one.
+
+_dynamic-prims_ that are passed in are used to avoid compilation errors on things not statically defined by the NetLogo language, be they user defined procedures or generated primitives from breed declarations.  _name_ and _precedence_ are required for all dynamic prims.
+
+_precedence_ is a number used to calculate the order of operations.  Higher numbers have more precedence than lower ones.  Generally all commands should have the lowest precedence, and all reporters should have 10 as the precedence.
+
+The possible values for _arg_ are :agentset, :boolean, :number, :command-block, :string, or t for wildcard.  For optional arguments, _arg_ can be a list of the form (_arg_ :optional) where _arg_ is one of the aforementioned values.
+
+The need for a parser between the lexer and the transpiler is because NetLogo needs two passes to turn into something that can be used.  This is the only entry point into this module, and should probably remain that way.
+
+There's also a lot of error checking that the _lexed-ast_ even makes sense, even though the lexer obviously thought it did.
+
+Examples are too numerous and varied, but by inserting an output between the lexer and this code, a good idea of what goes on can be gotten.
+# Package CLNL-TRANSPILER
+
+CLNL Transpiler
+
+The transpiler is responsible for taking an ast and turning it into valid CL code targeting the nvm.  Here is where start to care about commands versus reporters and ensuring that things are in the right place.  The reason we wait until here is because we want to allow someone else to play with the AST before handing it off to us.  For instance, the command center wants to add "show" to reporters, and the users dictate based on entry point whether they are expecting a command or a reporter.  So monitors can say "hey, transpile this reporter" and we'll check to make sure it actually is.
+
+Furthermore, the lisp code that any netlogo code would be transpiled to should use exported symbols, such that anyone writing NetLogo code in lisp could use the nvm in the same way that comes out of this transpiler All the code to convert the list of tokens coming from the lexer into an ast that can be transpiled later.
+
+## Contents
+
+* **function [command-list-p](#function-command-list-p)** - _command-list-p_ returns whether the parsed-ast is a valid list of commands.
+* **function [reporter-p](#function-reporter-p)** - _reporter-p_ returns whether the parsed-ast is a valid reporter.
+* **function [transpile](#function-transpile)** - _transpile_ takes a unambigious _parsed-ast_ and converts it to Common Lisp code.  The _parsed-ast_ must be either a list of commands, or a single reporter.
+
+## Function **COMMAND-LIST-P**
+
+#### Syntax:
+
+**command-list-p** _parsed-ast_ => _result_
+
+#### Arguments and Values:
+
+_parsed-ast_---An ast as returned by the parser  
+_result_---A boolean  
+
+#### Description:
+
+_command-list-p_ returns whether the parsed-ast is a valid list of commands.
+
+## Function **REPORTER-P**
+
+#### Syntax:
+
+**reporter-p** _parsed-ast_ => _result_
+
+#### Arguments and Values:
+
+_parsed-ast_---An ast as returned by the parser  
+_result_---A boolean  
+
+#### Description:
+
+_reporter-p_ returns whether the parsed-ast is a valid reporter.
+
+## Function **TRANSPILE**
+
+#### Syntax:
+
+**transpile** _parsed-ast_ _&optional_ _dynamic-prims_ => _ast_
+
+```dynamic-prims::= dynamic-prim*```  
+```dynamic-prim::= (:name name :type type :macro macro :func func)```  
+```type::= :reporter | :command```  
+
+#### Arguments and Values:
+
+_parsed-ast_---An ast as returned by the parser  
+_ast_---An common lisp _ast_ that can be actually run in a common lisp instance  
+_name_---A symbol in the keyword package  
+_macro_---A macro that will be called with the arguments ast  
+_func_---A function that will be called with the transpiled arguments  
+
+#### Description:
+
+_transpile_ takes a unambigious _parsed-ast_ and converts it to Common Lisp code.  The _parsed-ast_ must be either a list of commands, or a single reporter.
+
+When a set of _dynamic-prims_ is included, external language constructs can be also transpiled.  The provided functions will be inserted into the returned _ast_ with a call to _func_ALL.  If :macro is included, instead of having a call to _func_ALL provided, the macro will be run at netlogo transpile time, with the arguments it should have specified to the parser.  The result of that function call will then be dropped into the ast.
+
+Calling eval on that code should work correctly as long as you have a running engine.
+# Package CLNL-CODE-PARSER
+
+CLNL Code Parser
+
+A parser specifically for code from NetLogo models, that turns the lexed ast from an entire structured file into something more defined.
+
+This is different from the general parser (in clnl-parser) in that it's made for parsing the code section of nlogo files, and so works outside of the constraints.  In NetLogo, I believe this is analagous to the StructureParser, but I'm guessing there's weird overlap with other things.
+
+## Contents
+
+* **function [breeds](#function-breeds)** - Returns the breeds that get declared in the code.
+* **function [globals](#function-globals)** - Returns the globals that get declared in the code.
+* **function [parse](#function-parse)** - _parse_ takes a ambigious _lexed-ast_ and converts it to an unambigious one. It also returns the primitives that are defined in the code file, including ones generated from the _external-globals_, that can then be passed to both the parser and the transpiler.
+* **function [patches-own-vars](#function-patches-own-vars)** - Returns the turtles own variables that get declared in the code.
+* **function [procedures](#function-procedures)** - Returns the procedures that were defined in the code.  These can then be translated into common lisp by using mapcar on the _body_, and set to some function defined by _name_
+* **function [turtles-own-vars](#function-turtles-own-vars)** - Returns the turtles own variables that get declared in the code.
+
+## Function **BREEDS**
+
+#### Syntax:
+
+**breeds** _code-parsed-ast_ => _breeds_
+
+```breeds::= breed*```  
+
+#### Arguments and Values:
+
+_code-parsed-ast_---An ast as created by clnl-code-parse:parse  
+_breed_---A symbol interned in :keyword  
+
+#### Description:
+
+Returns the breeds that get declared in the code.
+
+## Function **GLOBALS**
+
+#### Syntax:
+
+**globals** _code-parsed-ast_ => _globals_
+
+```globals::= global*```  
+
+#### Arguments and Values:
+
+_code-parsed-ast_---An ast as created by clnl-code-parse:parse  
+_global_---A symbol interned in :keyword  
+
+#### Description:
+
+Returns the globals that get declared in the code.
+
+## Function **PARSE**
+
+#### Syntax:
+
+**parse** _lexed-ast_ _&optional_ _external-globals_ => _ast_, _prims_
+
+#### Arguments and Values:
+
+_lexed-ast_---An ambigious ast  
+_external-globals_---A list of symbols in keyword package  
+_ast_---An unambigious ast that represents the code block of a model  
+_prims_---Primitives that can be sent to the parser and transpiler  
+
+#### Description:
+
+_parse_ takes a ambigious _lexed-ast_ and converts it to an unambigious one. It also returns the primitives that are defined in the code file, including ones generated from the _external-globals_, that can then be passed to both the parser and the transpiler.
+
+_external-globals_ is a list of symbols representing global variables that are not defined within the code.  Normally these come from widgets defined in the model file, but could arguably come from elsewhere.
+
+This parser, unlike CLNL-_parse_:_parse_, should not be fed into the transpiler.
+
+Rather, the ast that's returned can be queried with other functions included in the CLNL-CODE-_parse_R package to tease out necessary information.  Some of those things will involve code blocks that can then be transpiled.
+
+## Function **PATCHES-OWN-VARS**
+
+#### Syntax:
+
+**patches-own-vars** _code-parsed-ast_ => _patches-own-vars_
+
+```patches-own-vars::= patches-own-var*```  
+
+#### Arguments and Values:
+
+_code-parsed-ast_---An ast as created by clnl-code-parse:parse  
+_patches-own-var_---A symbol interned in :keyword  
+
+#### Description:
+
+Returns the turtles own variables that get declared in the code.
+
+## Function **PROCEDURES**
+
+#### Syntax:
+
+**procedures** _code-parsed-ast_ => _procedures_
+
+```procedures::= procedure*```  
+```procedure::= (name body)```  
+
+#### Arguments and Values:
+
+_code-parsed-ast_---An ast as created by clnl-code-parse:parse  
+_name_---A symbol interned in :keyword  
+_body_---A list of lexed forms  
+
+#### Description:
+
+Returns the procedures that were defined in the code.  These can then be translated into common lisp by using mapcar on the _body_, and set to some function defined by _name_
+
+## Function **TURTLES-OWN-VARS**
+
+#### Syntax:
+
+**turtles-own-vars** _code-parsed-ast_ => _turtles-own-vars_
+
+```turtles-own-vars::= turtles-own-var*```  
+
+#### Arguments and Values:
+
+_code-parsed-ast_---An ast as created by clnl-code-parse:parse  
+_turtles-own-var_---A symbol interned in :keyword  
+
+#### Description:
+
+Returns the turtles own variables that get declared in the code.
+# Package CLNL-MODEL
+
+CLNL Model
+
+The representation, parsing, and serializing of NetLogo model files, including all of the sections, and subsections held within.  This package houses not only the code to read and write .nlogo files, but also the living state of the model as clnl runs.
+
+## Contents
+
+* **function [buttons](#function-buttons)** - Returns button definitions that get declared in the buttons of the _model_.  This is used to initialize the interface.
+* **function [code](#function-code)** - Returns the code from the model.
+* **function [default-model](#function-default-model)** - Returns the default startup model.
+* **function [execute-button](#function-execute-button)** - Executes the code in the button referenced by _name_ and _idx_.
+* **function [forever-button-on](#function-forever-button-on)** - Returns whether the button identified by _name_ and _idx_ is currently on.
+* **function [interface](#function-interface)** - _interface_ returns the widgets in _model_, used for display, or setting with SET-CURRENT-_interface_.
+* **function [read-from-nlogo](#function-read-from-nlogo)** - Takes a stream _str_, reads in a nlogo file, parses it, and then returns the model object.
+* **function [set-callback](#function-set-callback)** - Sets the means by which the interface can call arbitrary netlogo code.
+* **function [set-current-interface](#function-set-current-interface)** - Sets the currently running model to _interface_.
+* **function [sliders](#function-sliders)** - Returns slider definitions that get declared in the sliders of the _model_.  This is used to initialize the interface.
+* **function [switches](#function-switches)** - Returns switch definitions that get declared in the switches of the _model_.  This is used to initialize the interface.
+* **function [textboxes](#function-textboxes)** - Returns textbox definitions that get declared in the textboxes of the _model_.  This is used to initialize the interface.
+* **function [view](#function-view)** - Returns the view definition that get declared in the view of the _model_.  This is used to initialize the interface.
+* **function [widget-globals](#function-widget-globals)** - Returns the globals that get declared in the model from widgets. They are interned in the keyword package package set for clnl, so that they can later be used for multiple purposes.
+* **function [world-dimensions](#function-world-dimensions)** - Returns the dimensions of _model_.  _model_ must be a valid model as parsed by CLNL, and have a valid view in it.
+
+## Function **BUTTONS**
+
+#### Syntax:
+
+**buttons** _model_ => _button-defs_
+
+```button-defs::= button-def*```  
+```button-def::= (:left left :top top :height height :width width :forever forever :display display)```  
+
+#### Arguments and Values:
+
+_model_---A valid model  
+_left_---An integer representing the left position  
+_top_---An integer representing the top position  
+_height_---An integer representing height  
+_width_---An integer representing width  
+_forever_---A boolean representing whether this button is a forever button  
+_display_---A string representing display name  
+
+#### Description:
+
+Returns button definitions that get declared in the buttons of the _model_.  This is used to initialize the interface.
+
+## Function **CODE**
+
+#### Syntax:
+
+**code** _model_ => _code_
+
+#### Arguments and Values:
+
+_model_---A valid model  
+_code_---The string representing the netlogo code in this model  
+
+#### Description:
+
+Returns the code from the model.
+
+## Function **DEFAULT-MODEL**
+
+#### Syntax:
+
+**default-model** => _model_
+
+#### Arguments and Values:
+
+_model_---an object representing the model  
+
+#### Description:
+
+Returns the default startup model.
+
+## Function **EXECUTE-BUTTON**
+
+#### Syntax:
+
+**execute-button** _name_ _&optional_ _idx_ => _result_
+
+#### Arguments and Values:
+
+_name_---the name of the button  
+_idx_---the instance of the button, defaults to 0  
+_result_---undefined  
+
+#### Description:
+
+Executes the code in the button referenced by _name_ and _idx_.
+
+_name_ refers to the display name for the button, which is usually set by the model, but sometimes defaults to the code inside.
+
+Because _name_ is not guaranteed to be unique, _idx_ is available as a specifier.  The index is in the order that the buttons are loaded, and cannot be guaranteed to be stable from run to run.
+
+## Function **FOREVER-BUTTON-ON**
+
+#### Syntax:
+
+**forever-button-on** _name_ _&optional_ _idx_ => _on_
+
+#### Arguments and Values:
+
+_name_---the name of the button  
+_idx_---the instance of the button, defaults to 0  
+_on_---a boolean  
+
+#### Description:
+
+Returns whether the button identified by _name_ and _idx_ is currently on.
+
+_name_ refers to the display name for the button, which is usually set by the model, but sometimes defaults to the code inside.
+
+Because _name_ is not guaranteed to be unique, _idx_ is available as a specifier.  The index is in the order that the buttons are loaded, and cannot be guaranteed to be stable from run to run.
+
+## Function **INTERFACE**
+
+#### Syntax:
+
+**interface** _model_ => _interface_
+
+#### Arguments and Values:
+
+_model_---an object representing the model  
+_interface_---a list of widgets for display  
+
+#### Description:
+
+_interface_ returns the widgets in _model_, used for display, or setting with SET-CURRENT-_interface_.
+
+## Function **READ-FROM-NLOGO**
+
+#### Syntax:
+
+**read-from-nlogo** _str_ => _model_
+
+#### Arguments and Values:
+
+_str_---a readable stream  
+_model_---an object representing the model  
+
+#### Description:
+
+Takes a stream _str_, reads in a nlogo file, parses it, and then returns the model object.
+
+## Function **SET-CALLBACK**
+
+#### Syntax:
+
+**set-callback** _callback_ => _result_
+
+#### Arguments and Values:
+
+_callback_---a function that can take netlogo code  
+_result_---undefined  
+
+#### Description:
+
+Sets the means by which the interface can call arbitrary netlogo code.
+
+## Function **SET-CURRENT-INTERFACE**
+
+#### Syntax:
+
+**set-current-interface** _interface_ => _result_
+
+#### Arguments and Values:
+
+_interface_---a list of widgets for display  
+_result_---undefined  
+
+#### Description:
+
+Sets the currently running model to _interface_.
+
+The widgets set here are comprised of the bare necessary to run the engine with or without an actual visual component.
+
+## Function **SLIDERS**
+
+#### Syntax:
+
+**sliders** _model_ => _slider-defs_
+
+```slider-defs::= slider-def*```  
+```slider-def::= (:left left :top top :width width :var var :display display :initial-value initial-value)```  
+
+#### Arguments and Values:
+
+_model_---A valid model  
+_left_---An integer representing the left position  
+_top_---An integer representing the top position  
+_width_---An integer representing width  
+_var_---A symbole representing variable  
+_display_---A string representing variable name  
+_initial-value_---The initial value  
+
+#### Description:
+
+Returns slider definitions that get declared in the sliders of the _model_.  This is used to initialize the interface.
+
+## Function **SWITCHES**
+
+#### Syntax:
+
+**switches** _model_ => _switch-defs_
+
+```switch-defs::= switch-def*```  
+```switch-def::= (:left left :top top :width width :var var :display display :initial-value initial-value)```  
+
+#### Arguments and Values:
+
+_model_---A valid model  
+_left_---An integer representing the left position  
+_top_---An integer representing the top position  
+_width_---An integer representing width  
+_var_---A symbole representing variable  
+_display_---A string representing variable name  
+_initial-value_---The initial value  
+
+#### Description:
+
+Returns switch definitions that get declared in the switches of the _model_.  This is used to initialize the interface.
+
+## Function **TEXTBOXES**
+
+#### Syntax:
+
+**textboxes** _model_ => _textbox-defs_
+
+```textbox-defs::= textbox-def*```  
+```textbox-def::= (:left left :top top :height height :width width :display display)```  
+
+#### Arguments and Values:
+
+_model_---A valid model  
+_left_---An integer representing the left position  
+_top_---An integer representing the top position  
+_height_---An integer representing height, in characters  
+_width_---An integer representing width, in characters  
+_display_---A string representing display name  
+
+#### Description:
+
+Returns textbox definitions that get declared in the textboxes of the _model_.  This is used to initialize the interface.
+
+## Function **VIEW**
+
+#### Syntax:
+
+**view** _model_ => _view-def_
+
+```view-def::= (:left left :top top)```  
+
+#### Arguments and Values:
+
+_model_---A valid model  
+_left_---An integer representing the left position  
+_top_---An integer representing the top position  
+
+#### Description:
+
+Returns the view definition that get declared in the view of the _model_.  This is used to initialize the interface.
+
+## Function **WIDGET-GLOBALS**
+
+#### Syntax:
+
+**widget-globals** _model_ => _globals_
+
+```globals::= global*```  
+```global::= (name default)```  
+
+#### Arguments and Values:
+
+_model_---A valid model  
+_name_---A symbol interned in the keyworkd package  
+_default_---The widget default value  
+
+#### Description:
+
+Returns the globals that get declared in the model from widgets. They are interned in the keyword package package set for clnl, so that they can later be used for multiple purposes.
+
+## Function **WORLD-DIMENSIONS**
+
+#### Syntax:
+
+**world-dimensions** _model_ => _dims_
+
+```dims::= (:xmin xmin :xmax xmax :ymin ymin :ymax ymax)```  
+
+#### Arguments and Values:
+
+_model_---A valid model containing a view  
+_xmin_---An integer representing the minimum patch coord in X  
+_xmax_---An integer representing the maximum patch coord in X  
+_ymin_---An integer representing the minimum patch coord in Y  
+_ymax_---An integer representing the maximum patch coord in Y  
+
+#### Description:
+
+Returns the dimensions of _model_.  _model_ must be a valid model as parsed by CLNL, and have a valid view in it.
+# Package CLNL-RANDOM
+
+Wrapper around mt19937.
+
+mt19937 implements a merseinne twister that must be adapted a little in order to match the implementation in the main NetLogo codebase which tries to match how java.util.Random works.  Turtles, all the way down.
+
+## Contents
+
+* **function [export](#function-export)** - _export_ dumps out the random state to be export world ready.
+* **function [next-double](#function-next-double)** - _next-double_ returns the next randomly generated double.
+* **function [next-int](#function-next-int)** - _next-int_ returns the next randomly generated integer.
+* **function [next-long](#function-next-long)** - _next-long_ returns the next randomly generated long.
+* **function [set-seed](#function-set-seed)** - _set-seed_ sets the seed on the RNG.
+
+## Function **EXPORT**
+
+#### Syntax:
+
+**export** => _random-state_
+
+#### Arguments and Values:
+
+_random-state_---A dump of the current random state  
+
+#### Description:
+
+_export_ dumps out the random state to be export world ready.
+
+When NetLogo dumps out the current state of the engine, the state of the RNG also gets dumped out so that it can be reinitialized later.  This accomplishes that.
+
+This isn't really useful for regular use.
+
+## Function **NEXT-DOUBLE**
+
+#### Syntax:
+
+**next-double** _&optional_ _n_ => _double_
+
+#### Arguments and Values:
+
+_n_---A double representing the upper bound  
+_double_---A double  
+
+#### Description:
+
+_next-double_ returns the next randomly generated double.
+
+It does so in a way that's in accordance with java.util.Random and the MerseinneTwisterFast that's in _n_etLogo.  It also advances the R_n_G and is bounded by _n_.
+
+## Function **NEXT-INT**
+
+#### Syntax:
+
+**next-int** _n_ => _int_
+
+#### Arguments and Values:
+
+_n_---An integer representing the upper bound  
+_int_---An integer  
+
+#### Description:
+
+_next-int_ returns the next randomly generated integer.
+
+It does so in a way that's in accordance with java.util.Random and the MerseinneTwisterFast that's in _n_etLogo.  It also advances the R_n_G and is bounded by _n_.
+
+## Function **NEXT-LONG**
+
+#### Syntax:
+
+**next-long** _n_ => _long_
+
+#### Arguments and Values:
+
+_n_---A long representing the upper bound  
+_long_---A long  
+
+#### Description:
+
+_next-long_ returns the next randomly generated long.
+
+It does so in a way that's in accordance with java.util.Random and the MerseinneTwisterFast that's in _n_etLogo.  It also advances the R_n_G and is bounded by _n_.
+
+## Function **SET-SEED**
+
+#### Syntax:
+
+**set-seed** => _result_
+
+#### Arguments and Values:
+
+_result_---undefined  
+
+#### Description:
+
+_set-seed_ sets the seed on the RNG.