{"action":"created","comment":{"url":"https://api.github.com/repos/kripken/emscripten/pulls/comments/52132851","id":52132851,"diff_hunk":"@@ -342,6 +342,168 @@ If you add it to your own file, you should write something like\n first, so this add ``my_js`` onto ``LibraryManager.library``, the global\n object where all JavaScript library code should be.\n \n+JavaScript Limits in library files\n+----------------------------------\n+\n+If you're not familar with JavaScript, like you're a C/C++ programmer\n+and just using emscripten these issues probably won't come up but\n+if you're an experienced JavaScript programmer you need to be aware\n+many common JavaScript practices can not be used in emscripten\n+library files.\n+\n+To save space, by default, emscripten only includes library properties\n+referenced from C/C++. It does this by calling ``toString`` on each \n+used property. Conceptually you can consider it like this\n+\n+.. code-block:: javascript\n+\n+   usedLibraryFunctions.forEach(function(name) {\n+      var func = LibraryManager.library[name];\n+      emitCode(\"function _\" + name + func.toString().replace(\"function\", \"\"));\n+   });\n+   \n+It's actually not that simple as it will emit JavaScript objects\n+but any functions they reference must be expressible by calling `toString`.\n+   \n+The implications of that are as follows\n+\n+-  You can not use ES6 object shorthand function syntax.\n+-  You can not reference/bind other functions directly.\n+-  You can not use a closure directly.\n+-  You can not use ES6 arrow syntax.\n+-  You can not use other function transformations like currying.\n+\n+.. code-block:: javascript\n+\n+   mergeInto(LibraryManager.library, {\n+     // bad: ES6 object shorthand function syntax not allowwed\n+     bad_01() {\n+       alert('hi');\n+     },\n+     \n+     // bad: Can not bind/reference other functions directly.\n+     bad_02: document.querySelector.bind(document),\n+     \n+     // bad: You can not use a closure directly\n+     bad_03: (function() {\n+       var callCount = 0;\n+       return function() {\n+         console.log(\"times called: \", ++callCount);\n+       };\n+     }()),\n+     \n+     // bad: You can not use ES6 arrow syntax\n+     bad_04: () => { console.log(\"hi!\"); },\n+     \n+     // bad: You can not curry/transform\n+     bad_05: curry(scrollTo, 0),  \n+   });\n+   \n+Workarounds to the above issues\n+\n+You can put code in another file using a ``<script>`` tag \n+OR ``--pre-js`` OR ``--post-js``. Of course many of these\n+features work deeper in a function but the function directly \n+attached to the object passed to ``mergeInto`` must be a plain old \n+vanilla JavaScript ES5 function.\n+\n+One way to workaround some of these issues is to have a function\n+replace itself and have it called during initialization.\n+\n+.. code-block:: javascript\n+\n+   mergeInto(LibraryManager.library, {\n+\n+     // Can not bind/reference other functions directly workround\n+     good_02__postset: '_good_02();',\n+     good_02: function() {\n+       _good_o2 = document.querySelector.bind(document);","path":"site/source/docs/porting/connecting_cpp_and_javascript/Interacting-with-code.rst","position":79,"original_position":79,"commit_id":"a119a7d6d58f98d6ca9f9c9c4a352842efe13a7d","original_commit_id":"a119a7d6d58f98d6ca9f9c9c4a352842efe13a7d","user":{"login":"kripken","id":173661,"avatar_url":"https://avatars.githubusercontent.com/u/173661?v=3","gravatar_id":"","url":"https://api.github.com/users/kripken","html_url":"https://github.com/kripken","followers_url":"https://api.github.com/users/kripken/followers","following_url":"https://api.github.com/users/kripken/following{/other_user}","gists_url":"https://api.github.com/users/kripken/gists{/gist_id}","starred_url":"https://api.github.com/users/kripken/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/kripken/subscriptions","organizations_url":"https://api.github.com/users/kripken/orgs","repos_url":"https://api.github.com/users/kripken/repos","events_url":"https://api.github.com/users/kripken/events{/privacy}","received_events_url":"https://api.github.com/users/kripken/received_events","type":"User","site_admin":false},"body":"`o` should be `0`?","created_at":"2016-02-08T04:27:59Z","updated_at":"2016-02-08T04:27:59Z","html_url":"https://github.com/kripken/emscripten/pull/4081#discussion_r52132851","pull_request_url":"https://api.github.com/repos/kripken/emscripten/pulls/4081","_links":{"self":{"href":"https://api.github.com/repos/kripken/emscripten/pulls/comments/52132851"},"html":{"href":"https://github.com/kripken/emscripten/pull/4081#discussion_r52132851"},"pull_request":{"href":"https://api.github.com/repos/kripken/emscripten/pulls/4081"}}},"pull_request":{"url":"https://api.github.com/repos/kripken/emscripten/pulls/4081","id":58514596,"html_url":"https://github.com/kripken/emscripten/pull/4081","diff_url":"https://github.com/kripken/emscripten/pull/4081.diff","patch_url":"https://github.com/kripken/emscripten/pull/4081.patch","issue_url":"https://api.github.com/repos/kripken/emscripten/issues/4081","number":4081,"state":"open","locked":false,"title":"Document limitations and workarounds for libraries","user":{"login":"greggman","id":234804,"avatar_url":"https://avatars.githubusercontent.com/u/234804?v=3","gravatar_id":"","url":"https://api.github.com/users/greggman","html_url":"https://github.com/greggman","followers_url":"https://api.github.com/users/greggman/followers","following_url":"https://api.github.com/users/greggman/following{/other_user}","gists_url":"https://api.github.com/users/greggman/gists{/gist_id}","starred_url":"https://api.github.com/users/greggman/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/greggman/subscriptions","organizations_url":"https://api.github.com/users/greggman/orgs","repos_url":"https://api.github.com/users/greggman/repos","events_url":"https://api.github.com/users/greggman/events{/privacy}","received_events_url":"https://api.github.com/users/greggman/received_events","type":"User","site_admin":false},"body":"Here's a first stab at showing some of the limitations and workarounds for JavaScript in library files in reference to issue #4076\r\n\r\nIt's not clear to me if the `$` prefix is significant. Is it? Also the `__suffixes`.  Are all double underscore `__suffixes` reserved?","created_at":"2016-02-06T07:32:29Z","updated_at":"2016-02-08T04:27:59Z","closed_at":null,"merged_at":null,"merge_commit_sha":"b428ad47b476ecf819deaa3f053f7327566d5e3e","assignee":null,"milestone":null,"commits_url":"https://api.github.com/repos/kripken/emscripten/pulls/4081/commits","review_comments_url":"https://api.github.com/repos/kripken/emscripten/pulls/4081/comments","review_comment_url":"https://api.github.com/repos/kripken/emscripten/pulls/comments{/number}","comments_url":"https://api.github.com/repos/kripken/emscripten/issues/4081/comments","statuses_url":"https://api.github.com/repos/kripken/emscripten/statuses/a119a7d6d58f98d6ca9f9c9c4a352842efe13a7d","head":{"label":"greggman:interacting-with-code-JS-workarounds","ref":"interacting-with-code-JS-workarounds","sha":"a119a7d6d58f98d6ca9f9c9c4a352842efe13a7d","user":{"login":"greggman","id":234804,"avatar_url":"https://avatars.githubusercontent.com/u/234804?v=3","gravatar_id":"","url":"https://api.github.com/users/greggman","html_url":"https://github.com/greggman","followers_url":"https://api.github.com/users/greggman/followers","following_url":"https://api.github.com/users/greggman/following{/other_user}","gists_url":"https://api.github.com/users/greggman/gists{/gist_id}","starred_url":"https://api.github.com/users/greggman/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/greggman/subscriptions","organizations_url":"https://api.github.com/users/greggman/orgs","repos_url":"https://api.github.com/users/greggman/repos","events_url":"https://api.github.com/users/greggman/events{/privacy}","received_events_url":"https://api.github.com/users/greggman/received_events","type":"User","site_admin":false},"repo":{"id":51191578,"name":"emscripten","full_name":"greggman/emscripten","owner":{"login":"greggman","id":234804,"avatar_url":"https://avatars.githubusercontent.com/u/234804?v=3","gravatar_id":"","url":"https://api.github.com/users/greggman","html_url":"https://github.com/greggman","followers_url":"https://api.github.com/users/greggman/followers","following_url":"https://api.github.com/users/greggman/following{/other_user}","gists_url":"https://api.github.com/users/greggman/gists{/gist_id}","starred_url":"https://api.github.com/users/greggman/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/greggman/subscriptions","organizations_url":"https://api.github.com/users/greggman/orgs","repos_url":"https://api.github.com/users/greggman/repos","events_url":"https://api.github.com/users/greggman/events{/privacy}","received_events_url":"https://api.github.com/users/greggman/received_events","type":"User","site_admin":false},"private":false,"html_url":"https://github.com/greggman/emscripten","description":"Emscripten: An LLVM-to-JavaScript Compiler","fork":true,"url":"https://api.github.com/repos/greggman/emscripten","forks_url":"https://api.github.com/repos/greggman/emscripten/forks","keys_url":"https://api.github.com/repos/greggman/emscripten/keys{/key_id}","collaborators_url":"https://api.github.com/repos/greggman/emscripten/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/greggman/emscripten/teams","hooks_url":"https://api.github.com/repos/greggman/emscripten/hooks","issue_events_url":"https://api.github.com/repos/greggman/emscripten/issues/events{/number}","events_url":"https://api.github.com/repos/greggman/emscripten/events","assignees_url":"https://api.github.com/repos/greggman/emscripten/assignees{/user}","branches_url":"https://api.github.com/repos/greggman/emscripten/branches{/branch}","tags_url":"https://api.github.com/repos/greggman/emscripten/tags","blobs_url":"https://api.github.com/repos/greggman/emscripten/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/greggman/emscripten/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/greggman/emscripten/git/refs{/sha}","trees_url":"https://api.github.com/repos/greggman/emscripten/git/trees{/sha}","statuses_url":"https://api.github.com/repos/greggman/emscripten/statuses/{sha}","languages_url":"https://api.github.com/repos/greggman/emscripten/languages","stargazers_url":"https://api.github.com/repos/greggman/emscripten/stargazers","contributors_url":"https://api.github.com/repos/greggman/emscripten/contributors","subscribers_url":"https://api.github.com/repos/greggman/emscripten/subscribers","subscription_url":"https://api.github.com/repos/greggman/emscripten/subscription","commits_url":"https://api.github.com/repos/greggman/emscripten/commits{/sha}","git_commits_url":"https://api.github.com/repos/greggman/emscripten/git/commits{/sha}","comments_url":"https://api.github.com/repos/greggman/emscripten/comments{/number}","issue_comment_url":"https://api.github.com/repos/greggman/emscripten/issues/comments{/number}","contents_url":"https://api.github.com/repos/greggman/emscripten/contents/{+path}","compare_url":"https://api.github.com/repos/greggman/emscripten/compare/{base}...{head}","merges_url":"https://api.github.com/repos/greggman/emscripten/merges","archive_url":"https://api.github.com/repos/greggman/emscripten/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/greggman/emscripten/downloads","issues_url":"https://api.github.com/repos/greggman/emscripten/issues{/number}","pulls_url":"https://api.github.com/repos/greggman/emscripten/pulls{/number}","milestones_url":"https://api.github.com/repos/greggman/emscripten/milestones{/number}","notifications_url":"https://api.github.com/repos/greggman/emscripten/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/greggman/emscripten/labels{/name}","releases_url":"https://api.github.com/repos/greggman/emscripten/releases{/id}","deployments_url":"https://api.github.com/repos/greggman/emscripten/deployments","created_at":"2016-02-06T05:55:17Z","updated_at":"2016-02-06T05:55:37Z","pushed_at":"2016-02-06T07:30:09Z","git_url":"git://github.com/greggman/emscripten.git","ssh_url":"git@github.com:greggman/emscripten.git","clone_url":"https://github.com/greggman/emscripten.git","svn_url":"https://github.com/greggman/emscripten","homepage":"","size":134991,"stargazers_count":0,"watchers_count":0,"language":"C","has_issues":false,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":0,"mirror_url":null,"open_issues_count":0,"forks":0,"open_issues":0,"watchers":0,"default_branch":"master"}},"base":{"label":"kripken:master","ref":"master","sha":"42fb486c53d627b203b77af6e5d0c088c0ad03ad","user":{"login":"kripken","id":173661,"avatar_url":"https://avatars.githubusercontent.com/u/173661?v=3","gravatar_id":"","url":"https://api.github.com/users/kripken","html_url":"https://github.com/kripken","followers_url":"https://api.github.com/users/kripken/followers","following_url":"https://api.github.com/users/kripken/following{/other_user}","gists_url":"https://api.github.com/users/kripken/gists{/gist_id}","starred_url":"https://api.github.com/users/kripken/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/kripken/subscriptions","organizations_url":"https://api.github.com/users/kripken/orgs","repos_url":"https://api.github.com/users/kripken/repos","events_url":"https://api.github.com/users/kripken/events{/privacy}","received_events_url":"https://api.github.com/users/kripken/received_events","type":"User","site_admin":false},"repo":{"id":1357796,"name":"emscripten","full_name":"kripken/emscripten","owner":{"login":"kripken","id":173661,"avatar_url":"https://avatars.githubusercontent.com/u/173661?v=3","gravatar_id":"","url":"https://api.github.com/users/kripken","html_url":"https://github.com/kripken","followers_url":"https://api.github.com/users/kripken/followers","following_url":"https://api.github.com/users/kripken/following{/other_user}","gists_url":"https://api.github.com/users/kripken/gists{/gist_id}","starred_url":"https://api.github.com/users/kripken/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/kripken/subscriptions","organizations_url":"https://api.github.com/users/kripken/orgs","repos_url":"https://api.github.com/users/kripken/repos","events_url":"https://api.github.com/users/kripken/events{/privacy}","received_events_url":"https://api.github.com/users/kripken/received_events","type":"User","site_admin":false},"private":false,"html_url":"https://github.com/kripken/emscripten","description":"Emscripten: An LLVM-to-JavaScript Compiler","fork":false,"url":"https://api.github.com/repos/kripken/emscripten","forks_url":"https://api.github.com/repos/kripken/emscripten/forks","keys_url":"https://api.github.com/repos/kripken/emscripten/keys{/key_id}","collaborators_url":"https://api.github.com/repos/kripken/emscripten/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/kripken/emscripten/teams","hooks_url":"https://api.github.com/repos/kripken/emscripten/hooks","issue_events_url":"https://api.github.com/repos/kripken/emscripten/issues/events{/number}","events_url":"https://api.github.com/repos/kripken/emscripten/events","assignees_url":"https://api.github.com/repos/kripken/emscripten/assignees{/user}","branches_url":"https://api.github.com/repos/kripken/emscripten/branches{/branch}","tags_url":"https://api.github.com/repos/kripken/emscripten/tags","blobs_url":"https://api.github.com/repos/kripken/emscripten/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/kripken/emscripten/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/kripken/emscripten/git/refs{/sha}","trees_url":"https://api.github.com/repos/kripken/emscripten/git/trees{/sha}","statuses_url":"https://api.github.com/repos/kripken/emscripten/statuses/{sha}","languages_url":"https://api.github.com/repos/kripken/emscripten/languages","stargazers_url":"https://api.github.com/repos/kripken/emscripten/stargazers","contributors_url":"https://api.github.com/repos/kripken/emscripten/contributors","subscribers_url":"https://api.github.com/repos/kripken/emscripten/subscribers","subscription_url":"https://api.github.com/repos/kripken/emscripten/subscription","commits_url":"https://api.github.com/repos/kripken/emscripten/commits{/sha}","git_commits_url":"https://api.github.com/repos/kripken/emscripten/git/commits{/sha}","comments_url":"https://api.github.com/repos/kripken/emscripten/comments{/number}","issue_comment_url":"https://api.github.com/repos/kripken/emscripten/issues/comments{/number}","contents_url":"https://api.github.com/repos/kripken/emscripten/contents/{+path}","compare_url":"https://api.github.com/repos/kripken/emscripten/compare/{base}...{head}","merges_url":"https://api.github.com/repos/kripken/emscripten/merges","archive_url":"https://api.github.com/repos/kripken/emscripten/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/kripken/emscripten/downloads","issues_url":"https://api.github.com/repos/kripken/emscripten/issues{/number}","pulls_url":"https://api.github.com/repos/kripken/emscripten/pulls{/number}","milestones_url":"https://api.github.com/repos/kripken/emscripten/milestones{/number}","notifications_url":"https://api.github.com/repos/kripken/emscripten/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/kripken/emscripten/labels{/name}","releases_url":"https://api.github.com/repos/kripken/emscripten/releases{/id}","deployments_url":"https://api.github.com/repos/kripken/emscripten/deployments","created_at":"2011-02-12T05:23:30Z","updated_at":"2016-02-07T21:45:24Z","pushed_at":"2016-02-08T01:47:31Z","git_url":"git://github.com/kripken/emscripten.git","ssh_url":"git@github.com:kripken/emscripten.git","clone_url":"https://github.com/kripken/emscripten.git","svn_url":"https://github.com/kripken/emscripten","homepage":"","size":144446,"stargazers_count":9643,"watchers_count":9643,"language":"C","has_issues":true,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":1171,"mirror_url":null,"open_issues_count":728,"forks":1171,"open_issues":728,"watchers":9643,"default_branch":"master"}},"_links":{"self":{"href":"https://api.github.com/repos/kripken/emscripten/pulls/4081"},"html":{"href":"https://github.com/kripken/emscripten/pull/4081"},"issue":{"href":"https://api.github.com/repos/kripken/emscripten/issues/4081"},"comments":{"href":"https://api.github.com/repos/kripken/emscripten/issues/4081/comments"},"review_comments":{"href":"https://api.github.com/repos/kripken/emscripten/pulls/4081/comments"},"review_comment":{"href":"https://api.github.com/repos/kripken/emscripten/pulls/comments{/number}"},"commits":{"href":"https://api.github.com/repos/kripken/emscripten/pulls/4081/commits"},"statuses":{"href":"https://api.github.com/repos/kripken/emscripten/statuses/a119a7d6d58f98d6ca9f9c9c4a352842efe13a7d"}}}}