Up  

Module Browser.Impl


module Impl: sig .. end

Internal browser types



type win_ref = {
   win_ref_value : int;
}
A type representing the address of a window's data in memory.
val fresh_win_ref : unit -> win_ref
Generates a fresh win_ref.

type page_ref = {
   page_ref_value : int;
}
A type for referencing a "page", which is a window's contents at a point in time.
val fresh_page_ref : unit -> page_ref
Generates a fresh page_ref.

type node_ref = {
   node_ref_value : int;
}
A type representing the address of a document node in memory.
val fresh_node_ref : unit -> node_ref
Generates a fresh node_ref.

type act_ref = {
   act_ref_value : int;
}
A type representing the address of an activation record in memory.
val fresh_act_ref : unit -> act_ref
Generates a fresh act_ref.

type context = {
   context_win : win_ref;
   context_act : act_ref;
}
A type for the static context of an expression.

type inner =
| Scoped_expr of context * inner expr (*Scoped_expr(cxt, e) is a subexpression that executes in a different context than the enclosing expression.*)
| R of rslt (*A final result.*)
A type for the additional constructs in the internal language of * expressions.

type rslt =
| Null_value
| Bool_value of bool
| Int_value of int
| String_value of string
| Url_value of url
| Type_value of typ
| Code_value of void expr
| Win_value of win_ref
| Node_value of node_ref
| Closure of context * var * var list * inner expr (*Closure(cxt, param, locals, body) is a function closure, where locals are the additional variable names that will be used in the body.*)
| Error of string (*An error result (with an informative message).*)
A type for the results of evaluating script expressions.
val prim1 : string -> rslt -> rslt
The implementation of some primitive unary operations.
val prim2 : string -> rslt -> rslt -> rslt
The implementation of some primitive binary operations.
val to_inner_expr : void expr -> inner expr
The obvious coercion from source expressions to internal expresions.

type node =
| Para_node of elt_id option * string (*Represents a text node.*)
| Link_node of elt_id option * url * string (*Represents a link node.*)
| Textbox_node of elt_id option * string * rslt list (*Textbox_Node(id, text, handlers) represents a text input box along with its current handlers.*)
| Button_node of elt_id option * string * rslt list (*Button_node(id, button_text, handlers) represents a button along with its current handlers. If a handler is a function closure, it will be run by applying the function to the button node with which it's associated. If a handler is any other result, it will be a no-op.*)
| Inl_script_node of elt_id option * void expr * bool (*Represents a script node with an inline script, along with a flag that indicates whether or not the script has been queued for execution.*)
| Rem_script_node of elt_id option * url * bool (*Represents a script node that references an external script, along with a flag that indicates whether or not the script has been requested.*)
| Div_node of elt_id option * node_ref list (*Represents a sequence of nodes in the document.*)
The type of document nodes.

type queued_expr =
| Known_expr of inner expr (*A known script.*)
| Unknown_expr of node_ref (*A script that has been requested but not yet received.*)
The type of the objects in a page's queue of scripts to execute.

type page = {
   page_location : url; (*The location of this page.*)
   page_document : node_ref option; (*The root of the page's document node tree.*)
   page_environment : act_ref; (*The scripting environment for the page.*)
   page_script_queue : queued_expr list; (*A queue of scripts to execute. If the browser is in a waiting state, then the item in the front of the queue should be a marker for a remote script that has not yet been received.*)
}
The type of a page, i.e., a window's contents at a particular point in time.

type win_name =
| No_name
| Str_name of string
A type of a window's "name" property.

type win_opener =
| No_opener
| Win_opener of win_ref
A type for a window's "opener" property.

type win = {
   win_name : win_name; (*The window's name.*)
   win_opener : win_opener; (*The window's opener.*)
   win_page : page_ref; (*The window's page.*)
}
The type of a window.

type act = {
   act_parent : act_ref option;
   act_vars : (var * rslt) list;
}
The type of an activation record in the scripting language.

type cookie_id = {
   cookie_id_domain : domain;
   cookie_id_path : path;
   cookie_id_key : string;
}
The type of data that indexes cookies.

type dst =
| Xhr_dst of page_ref * rslt (*Xhr_dst(pr, f) represents a requested script that should be supplied as an argument to the closure f and run on the page referenced by pr.*)
| Doc_dst of win_ref (*Doc_dst(wr) represents a requested document that should replace the contents of the window referenced by wr.*)
| Script_dst of page_ref * node_ref (*Script_dst(pr, dr) represents a requested script that should be used to replace a marker in the page_script_queue of the page referenced by pr.*)
The type of a marker indicating the purpose and destination of a resource that has been requested but not yet been received.

type b = {
   browser_windows : (win_ref * win) list; (*A map from window references to windows. A window is assumed to be visible to the user if and only if it is in this list. The order of the list is significant due to the meaning of the user_window type.*)
   browser_pages : (page_ref * page) list; (*A map from page references to pages. A page should not be in this list if it is not visible in some window.*)
   browser_nodes : (node_ref * node) list; (*A map from node references to nodes. These nodes may or may not be in a particular window's node tree and hence may or may not be visible to the user. The graph of nodes defined by following the children of "div" nodes should be a DAG, and each node should appear as the root of at most one window.*)
   browser_environments : (act_ref * act) list; (*A map from activation record references to activation records. Activation records are paird with a domain to indicate their "origin" but this has no operational effect in this model.*)
   browser_cookies : (cookie_id * string) list; (*A map representing the browser's cookie store.*)
   browser_connections : (domain * req_uri * dst) list; (*A list of the open network connections on which no response has yet been received. The ordering of the entries represents the order in which the corresponding requests were sent and will be used to correctly pair multiple requests to the same domain with their responses.*)
}
A type for the basic state of a browser.

type task = {
   task_win : win_ref;
   task_expr : inner expr;
}
The type of a script expression queued for execution.

Internal browser implementation



Manipulating the browser's stores



General map functions


val upd_assoc : 'a -> 'b -> ('a * 'b) list -> ('a * 'b) list
Adds or updates a binding in a mapping.
val find_pos : 'a -> ('a * 'b) list -> int
Finds the position of a key in a mapping.

Browser page store


val page_valid : page_ref -> b -> bool
page_valid pr b returns true if pr is in the page store of b.
val page_assoc : page_ref -> b -> page option
page_assoc pr b returns the page associated with pr in the page store of b, if one exists.
val page_assoc_valid : page_ref -> b -> page
page_assoc_valid pr b returns the page associated with pr in the page store of b.
val page_update : page_ref -> page -> b -> b
page_update pr p b associates pr with the new page p in b.
val page_new : page -> b -> page_ref * b
page_new p b adds p to the page store of b and returns its fresh key.
val page_remove : page_ref -> b -> b
page_remove pr b removes pr and its page from from b.
val page_win : page_ref -> b -> win_ref option
page_win pr b returns the win_ref that refers to the unique window that contains the page referenced by pr.

Browser window store


val win_valid : win_ref -> b -> bool
win_valid wr b returns true if wr is in the window store of b.
val win_assoc : win_ref -> b -> win option
win_assoc wr b returns the win associated with wr in the window store of b, if one exists.
val win_assoc_valid : win_ref -> b -> win
win_assoc_valid wr b returns the win associated with wr in the window store of b.
val win_update : win_ref -> win -> b -> b
win_update wr w b associates wr with the new window w in b.
val win_new : win -> b -> win_ref * b
win_new w b adds w to the window store of b and returns its fresh key.
val win_remove : win_ref -> b -> b
win_remove wr b removes wr and its window from from b.
val win_from_win_name : string -> b -> win_ref option
win_from_win_name str b returns the window reference corresponding to the window name str in b.
val win_from_user_window : user_window -> b -> win_ref option
win_from_user_window uw b returns a reference to the open window in b that corresponds to the domain and number given by uw.
val win_to_user_window : win_ref -> b -> user_window
win_to_user_window wr b returns the user window description corresponding to the valid window reference wr.

Browser node store


val node_valid : node_ref -> b -> bool
node_valid dr b returns true if dr is in the node store of b.
val node_assoc_valid : node_ref -> b -> node
node_assoc_valid dr b returns the node associated with dr in the node store of b.
val node_update : node_ref -> node -> b -> b
node_update dr dn b associates dr with the node dn in b.
val node_new : node -> b -> node_ref * b
node_new dn b adds dn to the node store of b and returns its fresh key.

type node_parent =
| No_parent
| Page_parent of page_ref
| Parent_node of node_ref
The type of a node's parent object.
val node_parent : node_ref -> b -> node_parent
Finds the parent of a node.
val node_page : node_ref -> b -> page_ref option
Finds the page displaying a node if there is one.

Browser activation record store and variables


val act_valid : act_ref -> b -> bool
act_valid ar b returns true if ar is in the variable store of b.
val act_assoc_valid : act_ref -> b -> act
act_assoc_valid ar b returns the activation record associated with ar in b.
val act_update : act_ref -> act -> b -> b
act_update ar l act b associates ar with the new domain l and the new activation record act in b.
val act_new : act -> b -> act_ref * b
act_new l act b adds act, paired with l, to the activation record store of b and returns its fresh key.
val get_var : var -> act_ref -> b -> rslt option
get_var x ar b gets the result associated with x in b in the scope defined by ar, if x exists in that scope.
val create_var : var -> rslt -> act_ref -> b -> b
create_var x r ar b creates (or overwrites) the binding of x with the rslt r in the activation record referenced by ar in b.
val set_var : var -> rslt -> act_ref -> b -> b
set_var x r ar b updates the nearest enclosing binding of x (with the rslt r) under the scope defined by ar in b. If no current binding is found, a new binding is created in the outermost scope.

Browser cookie store


val get_site_cookies : domain -> path -> b -> (string * string) list
get_site_cookies d p b builds the mapping of cookie keys and values that is specific for the domain d and the path p in b.
val del_site_cookie : domain -> path -> string -> b -> b
del_site_cookie d p k b removes the mapping for of cookie key k for the domain d and path p in b.
val del_site_cookies : domain -> path -> string list -> b -> b
del_site_cookies d p ks b removes the mapping of all of the cookies with keys in ks from the cookie store for the domain d and path p in b.
val set_site_cookie : domain -> path -> string * string -> b -> b
set_site_cookie d p (k, v) b adds the mapping of the cookie key k to the rslt v for the domain d and path p in b.
val set_site_cookies : domain -> path -> (string * string) list -> b -> b
set_site_cookies d p pairs b adds all of the key-rslt mappings in pairs to the cookie store for the domain d and path p in b.
val upd_cookies : domain -> req_uri -> resp -> b -> b
upd_cookies d uri resp b executes all of the cookie updates requested by resp, which was received in response to a request to d for resource req_uri.

Browser network connections


val net_connection_domain_nth : domain -> int -> b -> (req_uri * dst) option
net_connection_domain_nth d n b returns the nth req_uri and dst associated with d (based on the order in which they were opened) among the open network connections of b, if one exists.
val net_connection_domain_remove_nth : domain -> int -> b -> b
net_connection_domain_remove_nth d n b removes the nth req_uri and dst associated with d (based on the order in which they were opened) among the open network connections of b, if one exists.
val http_send : domain -> req_uri -> string -> dst -> b -> b * output_event
http_send d uri body dst b updates the appropriate browser structures and creates the necessary output events for sending a new HTTP request whose response will be received by dst.

Rendering documents for user output


val render_page : page_ref -> b -> rendered_doc option
render_page pr b returns the rendered representation of the document in pr. A result of None indicates there are no visible contents. The behavior of this function is undefined if pr is not a valid page reference.
val page_update_event : page_ref -> b -> output_event
page_update_event pr b returns a UI_page_updated_event for the page reference pr.

Window operations


val build_win : win_name -> url -> win_opener -> node_ref option -> b -> win * b
build_win wn u doc b builds a new window structure with the window name wn. A new page is created in b using u for the page's location. If the contents can be displayed immediately, then a new activation record is also created for the window's environment.
val fetch_url : url -> win_ref -> b -> b * output_event list
fetch_url u wr b performs whatever action is required by the URL u.
val open_win : win_name -> url -> win_opener -> b -> win_ref * b * output_event list
open_win wn u b creates a new window in the browser with the window name wn, directed to the URL u. It returns a reference to the newly created window.
val close_doc_request_connections : win_ref -> b -> b
close_doc_request_connections wr b removes any network connection that is waiting for a document to load into the window referenced by wr.
val direct_win : win_ref -> url -> b -> b * output_event list
direct_win wr u b directs the window referenced by wr to the URL u.

Node tree operations


val build_node_tree : doc -> node_ref * (node_ref * node) list
build_node_tree doc allocates all of the node references needed to represent doc and returns the association list of these nodes with their appropriate node data. It also returns the reference to the root of the node tree that was created.
val split_queued_exprs : queued_expr list -> inner expr list * queued_expr list
split_queued_exprs qes returns the prefix of qes that are known scripts, as an inner expr list, along with the remainder of qes.
val process_node_scripts : page_ref -> node_ref -> b -> b * output_event list * task list
process_node_scripts pr dr b prepares for execution all of the scripts that are found among the descendents of dr and have not yet been executed. (Preparing them for execution means putting them in the proper queue.) It also generates network requests for all of the remote scripts that have not been requested.
val textbox_handlers_in_pos : win_ref -> int -> b -> (node_ref * rslt list) option
textbox_handlers_in_pos wr pos b returns the textbox handlers associated with the textbox in position pos in the window referenced by wr in b, along with the corresponding node_ref.
val button_handlers_in_pos : win_ref -> int -> b -> (node_ref * rslt list) option
button_handlers_in_pos wr pos b returns the button handlers associated with the button in position pos in the window referenced by wr in b, along with the corresponding node_ref.

Inserting and removing document nodes


val node_remove : node_ref -> b -> b * output_event list
Removes a node from its location in its node tree or page.
val node_insert : node_ref -> node_ref -> int -> b -> b * output_event list * task list
insert_node parent child pos b inserts child into the children of parent at position pos.

Executing scripts


val step_expr : context -> b -> inner expr -> b * inner expr * output_event list * task list
Carries out a single step of executing a script expression.

Top-level browser functionality



type waiting = {
   waiting_state : b;
}
The type of a browser waiting for input.

type running = {
   running_state : b;
   running_task_queue : task list;
}
The type of a browser in the middle of processing the current input.
type input_event = input_event 
type output_event = output_event

type state =
| Waiting of waiting
| Running of running
The type of a browser state, in general.
val start : state
The initial configuration of a browser.
val handle_load_in_new_win_event : win_opener -> win_name -> url -> b -> state * output_event list
Handling a User_load_in_new_win_event.
val handle_load_in_win_event : win_ref -> url -> b -> state * output_event list
Handling a User_load_in_win_event.
val handle_close_win_event : win_ref -> b -> state * output_event list
Handling a User_close_win_event.
val handle_input_text_event : win_ref -> int -> string -> b -> state * output_event list
Handling an User_input_text_event.
val handle_click_button_event : win_ref -> int -> b -> state * output_event list
Handling a User_click_button_event.
val get_ready_exprs : win_ref -> b -> task list * b
Return the known expressions at the head of the script queue for the page in the window referenced by wr as browser tasks, and remove them from the page's script queue.
val handle_network_response_event : net_connection -> resp -> b -> state * output_event list
Handling a Network_response_event.
val receive : input_event -> waiting -> state * output_event list
Respond to an incoming event.
val continue : running -> state * output_event list
Advance the browser state one step.