├── .gitattributes
├── LICENSE
├── .gitignore
└── README.md


/.gitattributes:
--------------------------------------------------------------------------------
1 | # Auto detect text files and perform LF normalization
2 | * text=auto
3 | 


--------------------------------------------------------------------------------
/LICENSE:
--------------------------------------------------------------------------------
 1 | MIT License
 2 | 
 3 | Copyright (c) 2022 Andreas Rozek
 4 | 
 5 | Permission is hereby granted, free of charge, to any person obtaining a copy
 6 | of this software and associated documentation files (the "Software"), to deal
 7 | in the Software without restriction, including without limitation the rights
 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 9 | copies of the Software, and to permit persons to whom the Software is
10 | furnished to do so, subject to the following conditions:
11 | 
12 | The above copyright notice and this permission notice shall be included in all
13 | copies or substantial portions of the Software.
14 | 
15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21 | SOFTWARE.
22 | 


--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
  1 | # Logs
  2 | logs
  3 | *.log
  4 | npm-debug.log*
  5 | yarn-debug.log*
  6 | yarn-error.log*
  7 | lerna-debug.log*
  8 | .pnpm-debug.log*
  9 | 
 10 | # Diagnostic reports (https://nodejs.org/api/report.html)
 11 | report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json
 12 | 
 13 | # Runtime data
 14 | pids
 15 | *.pid
 16 | *.seed
 17 | *.pid.lock
 18 | 
 19 | # Directory for instrumented libs generated by jscoverage/JSCover
 20 | lib-cov
 21 | 
 22 | # Coverage directory used by tools like istanbul
 23 | coverage
 24 | *.lcov
 25 | 
 26 | # nyc test coverage
 27 | .nyc_output
 28 | 
 29 | # Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files)
 30 | .grunt
 31 | 
 32 | # Bower dependency directory (https://bower.io/)
 33 | bower_components
 34 | 
 35 | # node-waf configuration
 36 | .lock-wscript
 37 | 
 38 | # Compiled binary addons (https://nodejs.org/api/addons.html)
 39 | build/Release
 40 | 
 41 | # Dependency directories
 42 | node_modules/
 43 | jspm_packages/
 44 | 
 45 | # Snowpack dependency directory (https://snowpack.dev/)
 46 | web_modules/
 47 | 
 48 | # TypeScript cache
 49 | *.tsbuildinfo
 50 | 
 51 | # Optional npm cache directory
 52 | .npm
 53 | 
 54 | # Optional eslint cache
 55 | .eslintcache
 56 | 
 57 | # Optional stylelint cache
 58 | .stylelintcache
 59 | 
 60 | # Microbundle cache
 61 | .rpt2_cache/
 62 | .rts2_cache_cjs/
 63 | .rts2_cache_es/
 64 | .rts2_cache_umd/
 65 | 
 66 | # Optional REPL history
 67 | .node_repl_history
 68 | 
 69 | # Output of 'npm pack'
 70 | *.tgz
 71 | 
 72 | # Yarn Integrity file
 73 | .yarn-integrity
 74 | 
 75 | # dotenv environment variable files
 76 | .env
 77 | .env.development.local
 78 | .env.test.local
 79 | .env.production.local
 80 | .env.local
 81 | 
 82 | # parcel-bundler cache (https://parceljs.org/)
 83 | .cache
 84 | .parcel-cache
 85 | 
 86 | # Next.js build output
 87 | .next
 88 | out
 89 | 
 90 | # Nuxt.js build / generate output
 91 | .nuxt
 92 | dist
 93 | 
 94 | # Gatsby files
 95 | .cache/
 96 | # Comment in the public line in if your project uses Gatsby and not Next.js
 97 | # https://nextjs.org/blog/next-9-1#public-directory-support
 98 | # public
 99 | 
100 | # vuepress build output
101 | .vuepress/dist
102 | 
103 | # vuepress v2.x temp and cache directory
104 | .temp
105 | .cache
106 | 
107 | # Serverless directories
108 | .serverless/
109 | 
110 | # FuseBox cache
111 | .fusebox/
112 | 
113 | # DynamoDB Local files
114 | .dynamodb/
115 | 
116 | # TernJS port file
117 | .tern-port
118 | 
119 | # Stores VSCode versions used for testing VSCode extensions
120 | .vscode-test
121 | 
122 | # yarn v2
123 | .yarn/cache
124 | .yarn/unplugged
125 | .yarn/build-state.yml
126 | .yarn/install-state.gz
127 | .pnp.*
128 | 
129 | .DS_Store
130 | package-lock.json
131 | 


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
  1 | # hyperscript-notes #
  2 | 
  3 | ...just a few notes on _hyperscript
  4 | 
  5 | [\_hyperscript](https://github.com/bigskysoftware/_hyperscript) is a relatively new programming language inspired inspired by [HyperTalk](https://en.wikipedia.org/wiki/HyperTalk).
  6 | 
  7 | This repository is a ~~(growing)~~ collection of notes on \_hyperscript with code examples that go beyond of what a "normal" programmer would probably need.
  8 | 
  9 | > to be honest: because of the design flaws described below, I have given up working with _hyperscript - for that reason, this list of notes will not be continued
 10 | 
 11 | > Just a small note: if you like this repository and seem to benefit from its contents, consider "starring" it (you will find the "Star" button on the top right of this page), so that I know which of my repositories to take most care of.
 12 | 
 13 | ### "halt" in asynchronous Event Handlers ###
 14 | 
 15 | While "async transparency" is an important and useful characteristic of \_hyperscript, it turns out to be counter-productive, when it comes to event handling: \_hyperscript code which looks synchronous at a first glance, may still actually be asynchronous from the JavaScript perspective - but asynchronous JavaScript event handlers may have a number of unwanted side-effects:
 16 | 
 17 | * first of all, `preventDefault` and `stop(Immediate)Propagation` only work as intended when invoked _before_ the first asynchronous function call - afterwards, they are useless at best, or produce race conditions at worst!
 18 | * while a synchronous event handler prevents other events from being handled as long as it is running, an asynchronous handler does not. As a consequence, subsequent handlers may start running before previous ones have finished - widely opening a door for nasty **race conditions**!
 19 | 
 20 | As a consequence, the `halt` command becomes completely useless when placed after actually asynchronous statements - but because of "async transparency" you probably never know if your code is synchronous or not...
 21 | 
 22 | With respect to the statement from the docs "Events are at the core of hyperscript, and event handlers are the primary entry point into most hyperscript code.", these restrictions are a severe design flaw - and presumably one which cannot easily be fixed.
 23 | 
 24 | > **Conclusion:**
 25 | > * be _very_ carefull with unknown code or code that is known to be asynchronous
 26 | > * whenever possible, use `event.preventDefault()` and/or `event.stop(Immediate)Propagation()` right at the beginning of your script if you want to stop event propagation and/or prevent the browser's default action for an event
 27 | > * keep in mind, that a `halt` command may have no effect on the browser's event propagation and default handling
 28 | > 
 29 | > but worst of all
 30 | > 
 31 | > * beware of _race conditions_(!) which may occur, because another event handler has already started running before your current one has been completed
 32 | 
 33 | One of the biggest advantages of JavaScript's single-threaded execution model was the prevention of such race conditions - the fact, that \_hyperscript re-introduces them by asynchronous event handlers destroys the illusion of easy programmability
 34 | 
 35 | ### Evaluate some Code at Runtime ###
 36 | 
 37 | If you want to implement a \_hyperscript REPL or a "message box" like in HyperCard, LiveCode or similar, you will need a mechanism to evaluate \_hyperscript code at runtime. One solution (perhaps not the best one) is to insert the following script element before the \_hyperscript runtime itself:
 38 | 
 39 | ```html
 40 |  <script type="text/hyperscript">
 41 |   def evaluate (Script)
 42 |     createElement('div') on document then set Incubator to it
 43 |       js (Script)
 44 |         return Script.replace(/&/g,'&amp;').replace(/\x22/g,'&quot;')
 45 |       end
 46 |       put it into Script
 47 | 
 48 |       put `
 49 |         <div style="display:none" _="
 50 |           init
 51 |             ${Script}
 52 |           end
 53 |         "></div>
 54 |       ` into the innerHTML of Incubator
 55 |     get the first <div/> in Incubator then set auxDiv to it
 56 |       put auxDiv after document.body      -- actually evaluates the given script
 57 |     remove auxDiv
 58 |   end
 59 |  </script>
 60 | ```
 61 | 
 62 | You may then evaluate some \_hyperscript code given in text form using
 63 | 
 64 | ```
 65 |  evaluate('call alert("Hello from evaluated _hyperscript!")')
 66 | ```
 67 | 
 68 | provided that the given code fits into the `init` section of the `_` attribute for a (temporary) HTML element.
 69 | 
 70 | > Caveats:
 71 | > * because of the way `evaluate` is implemented, **the given code is evaluated after a small delay** (i.e., will not finish before `evaluate` has ended)
 72 | > * as a consequence, **the given code can not return any value** to the calling \_hyperscript
 73 | 
 74 | Does anybody have a better idea?
 75 | 
 76 | ### Define a Behavior at Runtime ###
 77 | 
 78 | If you want to dynamically load behaviors or create behaviors at runtime (e.g., as part of a \_hyperscript REPL) you will need a mechanism to define behaviors at runtime. One solution (perhaps not the best one) is to insert the following script element before the \_hyperscript runtime itself:
 79 | 
 80 | ```html
 81 |  <script type="text/hyperscript">
 82 |   def defineBehavior (Script)
 83 |     createElement('div') on document then set Incubator to it
 84 |       js (Script)
 85 |         return Script.replace(/&/g,'&amp;').replace(/\x22/g,'&quot;')
 86 |       end
 87 |       put it into Script
 88 | 
 89 |       put `
 90 |         <div style="display:none" _="
 91 |           ${Script}
 92 |         "></div>
 93 |       ` into the innerHTML of Incubator
 94 |     get the first <div/> in Incubator then set auxDiv to it
 95 |       put auxDiv after document.body      -- actually evaluates the given script
 96 |     remove auxDiv
 97 |   end
 98 |  </script>
 99 | ```
100 | 
101 | You may then define a behavior given in text form using
102 | 
103 | ```
104 |  defineBehavior(`
105 |   behavior newBehavior
106 |     ...
107 |   end
108 |  `)
109 | ```
110 | 
111 | and `install` it into new HTML elements (created _after_ defining their behavior) as usual:
112 | 
113 | ```
114 |  put `
115 |   <div _="install newBehavior">...</div>
116 |  ` after ...
117 | ```
118 | 
119 | ### Update an existing Behavior at Runtime ###
120 | 
121 | If you want to update the implementation of an already existing behavior at runtime (e.g., as part of a \_hyperscript REPL) you may do so by using the `defineBehavior` described above and a script which defines a behavior with the same name as the one you want to update.
122 | 
123 | As a result,
124 | 
125 | * any **already existing HTML elements** based on the affected behavior **will still use the old implementation**
126 | * while **any HTML elements created after updating the behavior will use the new implementation**
127 | 
128 | If you want all HTML elements to use the updated behavior you will have to reload their scripts as shown below (provided that existing element scripts remain compatible with the updated behavior - otherwise you will have to update the element scripts anyway)
129 | 
130 | ### List all currently known Behavior Names ###
131 | 
132 | If you want to know which behaviors have already been defined, you may use the following code:
133 | 
134 | ```html
135 |  <script type="text/hyperscript">
136 |   def knownBehaviorNames
137 |     set BehaviourKey to 'Behavior_' + Date.now() + '_' + Math.round(Math.random()*1000000)
138 | 
139 |     defineBehavior(`behavior ${BehaviourKey} end`)
140 | 
141 |     js (BehaviourKey)
142 |       let global = (new Function('return this'))()
143 | 
144 |       let BehaviourPattern = global[BehaviourKey].toString()
145 |       delete global[BehaviourKey]
146 | 
147 |       let NameList = []
148 |         Object.getOwnPropertyNames(global).forEach(
149 |           (Key) => {
150 |             let Descriptor = Object.getOwnPropertyDescriptor(global,Key)
151 |             if (
152 |               (typeof Descriptor.value === 'function') &&
153 |               (Descriptor.value.toString() === BehaviourPattern)
154 |             ) { NameList.push(Key) }
155 |           }
156 |         )
157 |       return NameList
158 |     end
159 |     return it
160 |   end
161 |  </script>
162 | ```
163 | 
164 | > Nota bene: function `knownBehaviorNames` depends on `defineBehavior` which has been mentioned above and should also be inserted into the HTML document.
165 | 
166 | The following examples shows how to use `knownBehaviorNames`:
167 | 
168 | ```html
169 |  <script type="text/hyperscript">
170 |   behavior Test1 end
171 |   behavior Test2 end
172 |  
173 |   init
174 |     log knownBehaviorNames()
175 |   end
176 |  </script>
177 | ```
178 | 
179 | ### Change (or just reload) some Element Scripts at Runtime ###
180 | 
181 | if you want to change the `_` attribute (containg the element's \_hyperscript script) at runtime (e.g., as part of a \_hyperscript REPL) you can not just set that attribute to a new value as \_hyperscript will not automatically re-evaluate the new attribute contents. One solution (perhaps not the best one) is to insert the following script element before the \_hyperscript runtime itself:
182 | 
183 | ```html
184 |  <script type="text/hyperscript">
185 |   def setScriptOf (Element, Script)
186 |     cloneNode() from Element then set clonedElement to it
187 |       set @_ of clonedElement to Script
188 | 
189 |       js (Element, clonedElement)
190 |         while (Element.hasChildNodes()) {
191 |           clonedElement.appendChild(Element.firstChild)
192 |         }
193 |       end
194 |     put clonedElement after Element
195 |     remove Element
196 |   end
197 |  </script>
198 | ```
199 | 
200 | You may then update the script of a given HTML element using
201 | 
202 | ```
203 |  setScriptOf(<element>,<new-script>)
204 | ```
205 | 
206 | where `<element>` refers to an existing HTML element and `<new-script>` represents the (new or initial) script for `<element>`.
207 | 
208 | `setScriptOf` is itself idempotent (i.e., may safely be called multiple times with the same arguments) provided that the given `<script>` is idempotent itself (i.e., does not produce side-effects like in an `init` block)
209 | 
210 | > Caveats: `setScriptOf` has to clone the affected HTML element in order to set the given script. While it moves any existing contents of the old HTML element to the new clone (before the new script is evaluated), some element contents could probably produce unwanted side-effects.
211 | > 
212 | > Additionally, any references to the original DOM element will now point to an orphaned HTML fragment, as the original element will no longer be part of the DOM and all its contents will have been moved into the newly created clone
213 | 
214 | ### \_hyperscript "methods" for (scripted) HTML Elements ###
215 | 
216 | If you want \_hyperscript scripted HTML elements to act like "components" offering more complex functionality you will probably want these elements to provide "methods". Fortunately, such "methods" can be implemented with ease:
217 | 
218 | * within your element define your \_hyperscript functions as usual
219 | * in order to make them "publically" available (i.e., to "export" them) set these functions as element properties:<br>&nbsp;`init set my <method> to <method> end`<br>where `<method>` is the \_hyperscript function name (warning: this may collide with already existing internal methods of the DOM element)
220 | 
221 | ```
222 |  <div _="
223 |    def publicMethod
224 |    -- insert your implementation here
225 |    end
226 |    
227 |    init
228 |      set my publicMethod to publicMethod
229 |    end
230 |  ">...</div>
231 | ```
232 | 
233 | From elsewhere in your \_hyperscript code
234 | 
235 | * the method may now be invoked using a "pseudo command": `<method>(<argument-list>) on <element>` (or similar)
236 | * any values returned from the method will then become available as `the result` or simply `it`
237 | 
238 | ## License ##
239 | 
240 | While \_hyperscript itself is under a [BSD 2-clause license](https://github.com/bigskysoftware/_hyperscript/blob/master/LICENSE), these notes are just MIT-licensed
241 | 
242 | [MIT License](LICENSE.md)
243 | 


--------------------------------------------------------------------------------