{"id":278,"date":"2012-08-14T11:15:51","date_gmt":"2012-08-14T15:15:51","guid":{"rendered":"http:\/\/sites.hampshire.edu\/ci-lab\/?p=278"},"modified":"2013-08-14T11:17:25","modified_gmt":"2013-08-14T15:17:25","slug":"clojush-environments-documentation-2","status":"publish","type":"post","link":"https:\/\/sites.hampshire.edu\/ci-lab\/2012\/08\/14\/clojush-environments-documentation-2\/","title":{"rendered":"Clojush Environments Documentation"},"content":{"rendered":"<h3>Overview<\/h3>\n<p>This update introduces environments (previously called &#8220;scopes&#8221;) to Clojush in an effort to offer encapsulation of functionality. Many times, it is nice to perform instructions and return a value but not affect the rest of the stack space, which environments allow you to do.<\/p>\n<h3>New Stacks<\/h3>\n<p>There are two new stacks,\u00a0:environment and\u00a0:return.<\/p>\n<h4>\u00a0:environment stack<\/h4>\n<p>The\u00a0:environment stack holds environments, which are essentially Push interpreter states that can be saved and later returned to. In fact, since the Push state is stored as a map, this entire map is pushed onto the stack, and later can replace the current state when popping it off the\u00a0:environment stack.<\/p>\n<p>An item on the\u00a0:environment stack can be popped in two ways. The first is by the instruction environment_end. The second automatically happens when the\u00a0:exec stack is empty and there is something on the\u00a0:environment stack. When the\u00a0:environment stack is popped, that popped state replaces the current Push interpreter state. Then, the instructions remaining on the old\u00a0:exec stack (if any) are placed at the beginning of the new\u00a0:exec stack. Finally, everything on the\u00a0:return stack is pushed onto the\u00a0:exec stack, with the top item of the\u00a0:return stack pushed first (so that the bottom item of the\u00a0:return stack will be the top item of the\u00a0:exec stack).<\/p>\n<h4>\u00a0:return stack<\/h4>\n<p>The\u00a0:return stack allows both literals and instructions to be &#8220;returned&#8221; to the pushed environment when it is popped (see above). There are instructions for moving the top item of any stack to the\u00a0:return stack, including code from the\u00a0:exec stack. Additionally, there are specialized instructions that can be used to &#8220;consume&#8221; arguments in the pushed environment by popping them, and for tagging literals in the pushed environment (see those instructions below).<\/p>\n<h3>New Instructions<\/h3>\n<h4>environment instructions<\/h4>\n<ul>\n<li><i>environment_new<\/i>\u00a0&#8211; Saves the next instruction or parenthetical grouping on the\u00a0:exec stack and pushes the state onto the\u00a0:environment stack, with the saved instruction\/grouping popped from the\u00a0:exec stack of the pushed state. The\u00a0:exec stack is replaced by this saved instruction\/grouping, the\u00a0:return stack is emptied, and the rest of the state stays the same as it was before this instruction.<\/li>\n<li><i>environment_begin<\/i>\u00a0&#8211; Pushes the state onto the\u00a0:environment stack (with an empty\u00a0:exec stack). The\u00a0:return stack is emptied in the current state, but all other stacks (including the\u00a0:exec stack) are left full.<\/li>\n<li><i>environment_end<\/i>\u00a0&#8211; If the\u00a0:environment stack is empty, no-ops. Otherwise, does the same as what happens when there is an empty\u00a0:exec stack with something on the\u00a0:environment stack, which is described above.<\/li>\n<\/ul>\n<h4>return stack instructions<\/h4>\n<ul>\n<li><i>return_from&lt;type&gt;<\/i>\u00a0&#8211; For &lt;type&gt; equivalent to the name of one of the stacks\u00a0:boolean,\u00a0:integer,\u00a0:float,\u00a0:string,\u00a0:zip, and\u00a0:exec, these instructions pop the next item off of the &lt;type&gt; stack and push that item onto the\u00a0:return stack.\n<ul>\n<li><i>return_fromcode<\/i>\u00a0&#8211; Returning something from the\u00a0:code stack is different, since normal instructions would just be performed on the\u00a0:exec stack. So,\u00a0<i>return_fromcode<\/i>\u00a0pushes (code_quote\u00a0<i>top_code_stack_item<\/i>) onto the\u00a0:return stack, which will result in the top item of the current\u00a0:code stack being quoted (and thus pushed to the\u00a0:code stack) in the popped environment.<\/li>\n<\/ul>\n<\/li>\n<li><i>return_&lt;type&gt;_pop<\/i>\u00a0&#8211; For &lt;type&gt; including each of the stacks above (including\u00a0:code), this instruction places the instruction\u00a0<i>&lt;type&gt;_pop<\/i>\u00a0<b>onto the bottom<\/b>\u00a0of the\u00a0:return stack. The effect is that in the popped environment, these popping instructions will be the first thing that is executed, and will effectively &#8220;consume&#8221; the &#8220;arguments&#8221; given on that parent environment&#8217;s stacks.<\/li>\n<li><i>return_tagspace<\/i>\u00a0&#8211; This instruction immediately copies the tagspace of the current environment to the tagspace of the first environment on the\u00a0:environment stack. This allows children environments to give their tagspace to their parent.<\/li>\n<li><i>return_tag_&lt;type&gt;_&lt;index&gt;<\/i>\u00a0&#8211; There is a new erc, the\u00a0<i>return-tag-instruction-erc<\/i>, that returns instructions of this form. These instructions, when executed, push\u00a0<i>(&lt;literal&gt; tag_&lt;type&gt;_&lt;index&gt;)<\/i>\u00a0onto the\u00a0:return stack, where &lt;literal&gt; is the top item on the &lt;type&gt; stack (and is popped from that stack). These instructions allow an environment to add tags to their parent environment.<\/li>\n<\/ul>\n<h2>Original Proposal<\/h2>\n<p>The original proposal, which is somewhat accurate still, is kept here for reference:<\/p>\n<ul>\n<li>Use environment_new (previously scope_enter) to enter a new scope. This instruction pushes a copy of the stacks onto the\u00a0:environment stack, clears the\u00a0:exec and\u00a0:return stacks, and pushes the next item on the old\u00a0:exec stack onto the new\u00a0:exec stack, popping it from the old one.<\/li>\n<li>Whenever the\u00a0:exec stack is empty during execution, Push will first check if there is anything on the\u00a0:environment stack. If so, it is popped off (replacing all the stacks with the ones stored in the top environment), and then everything on the original\u00a0:return stack is pushed onto the\u00a0:exec stack.<\/li>\n<li>No instructions fetch or push literals between environments on the\u00a0:environment stack. As of now, the only way to alter the environment stack is either through the instruction environment_push or by having an empty\u00a0:exec stack.<\/li>\n<li>Return instructions will allow environments (scopes) to pass return values, consume arguments, and tag things in other environments.\n<ul>\n<li>Instructions like return_integer will move the top item of the\u00a0:integer stack onto the\u00a0:return stack.<\/li>\n<li>Instructions like return_integer_pop will push the instruction integer_pop onto the\u00a0:return stack, so that the &#8220;parent&#8221; environment will pop the top integer before executing further. To avoid popping instructions from just popping literals that have been pushed by instructions like return_frominteger, the popping instructions will be inserted at the bottom of the\u00a0:return stack, and thus executed first in the state once the environment has ended. Since ordering of pop instructions is commutative, it is inconsequential that return_pop_stack instructions that are executed later will result in pop_stack instructions that are executed sooner.<\/li>\n<li>Instructions like return_tag_integer_123 (say 2999 is on top of the\u00a0:integer stack) will push the code &#8216;(2999 tag_integer_123) onto the\u00a0:return stack and pop 2999 from the\u00a0:integer stack. This will cause the tag 123 to be associated with 2999 in the &#8220;parent&#8221; environment.<\/li>\n<li>The instructions return_exec and return_code are legal and pull the top code item off the respective stack to the\u00a0:return stack. return_code will put a code_quote before the code, so that it will be moved to the\u00a0:code stack in the &#8220;parent&#8221; environment. For example, the code &#8216;(return_code (2 integer_add)) will put (code_quote (2 integer_add)) on the\u00a0:return stack. return_exec will just pull the next instruction grouping itself, meaning that the code will be executed in the &#8220;parent&#8221; environment. Note: Since this leads to permeability of the scoping of environments, it may often be best to leave return_exec out of the instruction set to avoid undesirable messing of stacks between environments.<\/li>\n<\/ul>\n<\/li>\n<\/ul>\n","protected":false},"excerpt":{"rendered":"<p>Overview This update introduces environments (previously called &#8220;scopes&#8221;) to Clojush in an effort to offer encapsulation of functionality. Many times, it is nice to perform instructions and return a value but not affect the rest of the stack space, which environments allow you to do. New Stacks There are two new stacks,\u00a0:environment and\u00a0:return. \u00a0:environment stack [&hellip;]<\/p>\n","protected":false},"author":622,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[1],"tags":[],"class_list":["post-278","post","type-post","status-publish","format-standard","hentry","category-uncategorized"],"_links":{"self":[{"href":"https:\/\/sites.hampshire.edu\/ci-lab\/wp-json\/wp\/v2\/posts\/278"}],"collection":[{"href":"https:\/\/sites.hampshire.edu\/ci-lab\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/sites.hampshire.edu\/ci-lab\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/sites.hampshire.edu\/ci-lab\/wp-json\/wp\/v2\/users\/622"}],"replies":[{"embeddable":true,"href":"https:\/\/sites.hampshire.edu\/ci-lab\/wp-json\/wp\/v2\/comments?post=278"}],"version-history":[{"count":1,"href":"https:\/\/sites.hampshire.edu\/ci-lab\/wp-json\/wp\/v2\/posts\/278\/revisions"}],"predecessor-version":[{"id":279,"href":"https:\/\/sites.hampshire.edu\/ci-lab\/wp-json\/wp\/v2\/posts\/278\/revisions\/279"}],"wp:attachment":[{"href":"https:\/\/sites.hampshire.edu\/ci-lab\/wp-json\/wp\/v2\/media?parent=278"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/sites.hampshire.edu\/ci-lab\/wp-json\/wp\/v2\/categories?post=278"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/sites.hampshire.edu\/ci-lab\/wp-json\/wp\/v2\/tags?post=278"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}