-
Notifications
You must be signed in to change notification settings - Fork 1
/
index.html
1224 lines (1138 loc) · 47 KB
/
index.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<html lang="en">
<head>
<title>HTML: The Programming Language</title>
<meta name="viewport" content="width=device-width, initial-scale=1" />
<style>
body {
font-family: Verdana,sans-serif;
max-width: 768px;
margin: auto;
padding: 16px 16px 800px;
}
pre {
background-color: bisque;
padding: 16px 16px 0;
border-radius: 8px;
overflow: auto;
margin:24px;
border: 3px solid dimgray;
}
main {
border: 1px solid black;
padding: 16px;
margin: 16px;
}
p {
margin: 16px;
line-height: 1.8em;
}
aside {
margin: 24px;
font-style: italic;
}
code {
color: forestgreen;
font-weight: bold;
}
</style>
<script src="html.js"></script>
<script>
html.meta.debug = function(hdb, elt, env)
{
// you can set a JavaScript breakpoint here
hdb.break();
}
</script>
</head>
<body>
<header>
<h1>
HTML, The Programming Language <br/>
<small>A Programming Language</small>
</h1>
<nav>
<center>
<a href=".">Documentation</a> ⩔
<a href="./test.html">Tests</a> ⩔
<a href="./html.js">html.js</a> (<a href="./html.js" download="">download</a>) ⩔
<a href="https://htmx-shop.fourthwall.com/products/html-pl-btw-shirt">t-shirt</a> ⩔
<a href="./LICENSE.txt">LICENSE</a>
</center>
</nav>
</header>
<section>
<h2 id="intro"><a href="#intro">Introduction</a></h2>
<p>
HTML, the programming language, is a practical, <a href="https://en.wikipedia.org/wiki/Turing_completeness">turing-complete</a><a href="#turning-complete">[1]</a>,
<a href="https://en.wikipedia.org/wiki/Stack-oriented_programming">stack-based</a> programming language based on <a href="https://en.wikipedia.org/wiki/HTML">HTML</a>,
the markup language. It uses <a href="https://developer.mozilla.org/en-US/docs/Web/HTML/Element">elements
defined in HTML</a>, the markup language, in order to do computations.
</p>
<p>
To give you a sense of what HTML, the programming langauge, looks like, below is a sample program that prints
the values from 1 to 10 to standard out (<code>console.log</code>)
</p>
<figure>
<figcaption>A Sample HTML Program</figcaption>
<pre>
<data value="1"></data> <!-- push 1 onto the stack -->
<output id="loop"></output> <!-- print the top of the stack -->
<data value="1"></data> <!-- push 1 onto the stack -->
<dd></dd> <!-- add 1 -->
<dt></dt> <!-- dup new value -->
<data value="11"></data> <!-- push 11 to compare -->
<small></small> <!-- test new value is smaller than 11 -->
<i> <!-- if bigger than zero pushed true -->
<a href="#loop"></a> <!-- then jump back to the loop -->
</i>
</pre>
</figure>
<p>
HTML programs are specified in HTML, the markup language. Elements from HTML, the markup language, (informally
referred to as "tags") are interpreted as <i>commands</i> by the HTML interpreter. Note that HTML programs
are <em>not</em> required to be legal <a href="https://en.wikipedia.org/wiki/HTML5">HTML5</a>, the markup
language, documents.
</p>
<p>
HTML is a <a href="#extending">fully customizable</a> programming language and you may add new
commands or alter existing commands by mutating the <code>html.meta.commands</code> object.
</p>
</section>
<section>
<h2 id="installation"><a href="#installation">Installation</a></h2>
<p>
To install HTML, the programming language, <a href="html.js" download>download</a> and include the
<code>html.js</code> file via a script tag:
</p>
<pre>
<script src="html.js"></script>
</pre>
<p>
You may now begin programming in HTML.
</p>
</section>
<section>
<h2 id="getting-started"><a href="#getting-started">Getting Started</a></h2>
<p>
To get started with HTML, the programming language, you must first understand how a
<i>stack-oriented</i> programming language works. In a stack-oriented programming language, most operations are
done with reference to a <i>stack</i> of values.
</p>
<p>
In HTML, this is referred to as <i>the value stack</i> or, informally, as "the stack". In HTML, the stack is
maintained in the current <em>execution frame</em> (either the main HTML program or within a function defined in HTML),
rather than as a global stack, as in
<a href="https://en.wikipedia.org/wiki/Forth_(programming_language)">forth-like</a> languages. (In this regard,
HTML, the programming language, is <a href="https://docs.oracle.com/javase/specs/jvms/se8/html/jvms-2.html#jvms-2.6">similar to the JVM</a>.)
</p>
<p>
Stack-oriented programming can seem strange to developers who have not worked with it before, so let's begin
with a simple "Hello World" program in HTML:
</p>
<pre>
<main>
<s>Hello World!</s> <!-- push 'Hello World!' onto the stack -->
<output></output> <!-- print the top of the stack -->
</main>
</pre>
<p>
The first thing to note is that in HTML a program is defined in a <code><main></code> tag.
</p>
<p>
The next thing to notice is that the program consists of a series of HTML tags within the <code><main></code> tag.
For the "Hello World" program, the first command is a <code><s></code> tag. This will <a href="#strings">"push"
the string value <code>"Hello World!"</code></a> onto the stack.
</p>
<p>
The next command is the <code><output></code> tag. This will <a href="#output">output the top of the
value stack to standard out</a>, which is <code>console.log</code>.
</p>
<p>
(Note that the <code>output</code> tag <b>does not</b> consume the top of the value stack.)
</p>
<p>
A more elaborate example of using the value stack would be adding 2 and 3, like so:
</p>
<pre>
<main>
<data value="2"></data> <!-- push 2 onto the stack -->
<data value="3"></data> <!-- push 3 onto the stack -->
<dd></dd> <!-- add the top two values on the stack -->
<output></output> <!-- print the sum now on the top of the stack -->
</main>
</pre>
<p>
In this HTML program, we push the values 2 and 3 onto the value stack <a href="#numbers">using <code><data></code> tags</a>, and
then invoke the <code>dd</code> command to <a href="#addition">"a(dd)" the top two values on the stack</a> .
The <code><dd></code> command will "pop", or remove, the top two values of the value stack, add
them together, and then "push" the result onto the top of the value stack. Next, we print the result out
using the <code>output</code> tag.
</p>
<p>
In a stack-oriented language like HTML, this is how things are done: pushing and popping values on the
stack in order to do computations.
</p>
<p>
With that brief introduction out of the way, let's go over the entire language so you can add HTML, the
programming language, to your resume.
</p>
</section>
<section>
<h2 id="comments"><a href="#comments">Comments</a></h2>
<p>
HTML uses HTML's normal comment mechanism for comments:
</p>
<pre>
<!-- This is a comment -->
</pre>
</section>
<section>
<h2 id="literals"><a href="#literals">Literal Values</a></h2>
<p>
HTML supports many different literals that can be used to push values onto the value stack.
</p>
<h3 id="numbers"><a href="#numbers">Numbers</a></h3>
<p>
Numbers can be pushed onto the value stack using the <code><data></code> tag:
</p>
<pre>
<!-- this pushes the numeric value 1 onto the value stack -->
<data value="1"></data>
</pre>
<h3 id="strings"><a href="#strings">Strings</a></h3>
<p>
Strings can be pushed onto the value stack using the <code><s></code> tag. The inner content
of the tag will be treated as a string.
</p>
<pre>
<!-- this pushes the string "Hello Strings!" onto the value stack -->
<s>Hello Strings!</s>
</pre>
<h3 id="arrays"><a href="#arrays">Arrays</a></h3>
<p>
Arrays can be pushed onto the value stack using the <code><ol></code> tag, containing <code><li></code>
elements. The child elements of the <code><li></code> will be executed and the top value of the stack
after they are evaluated will be inserted into the array. If there are excess values on the value stack
after an <code><li></code> has executed its children, they will be removed.
</p>
<pre>
<!-- this pushes the array [1, 2] onto the stack -->
<ol>
<li>
<data value="1"></data>
</li>
<li>
<data value="2"></data>
</li>
</ol>
</pre>
<h3 id="objects"><a href="#objects">Objects</a></h3>
<p>
Objects can be pushed onto the value stack using the <code><table></code> tag, containing <code><th></code>
and <code><td></code>elements. <code><th></code> elements will be used as property names, using the
innerText of the elements. The child elements of the <code><td></code> will be executed and the top value of
the stack after they are evaluated will be used as the value for the corresponding <code><th></code> . If
there are excess values on the value stack after a <code><td></code> has executed its children, they will be
removed.
</p>
<pre>
<!-- this pushes the object {foo:"Foo", bar:10} onto the stack -->
<table>
<tr>
<th>
foo
</th>
<th>
bar
</th>
</tr>
<tr>
<td>
<s>Foo</s>
</td>
<td>
<data value="10"></data>
</td>
</tr>
</table>
</pre>
<h3 id="true"><a href="#true">true, false & null</a></h3>
<p>
The values <code>true</code>, <code>false</code> and <code>null</code> can all be accessed with the
<code><cite></code> command. These are defined as <a href="#variables">variables</a> at the start of every
new activation frame (aka scope). Note that it is possible to override these variables with different values,
such as setting <code>null</code> to <code>"lmao"</code>, but that we do not recommend doing so in most cases.
</p>
<pre>
<!-- this pushes true onto the stack -->
<cite>true</cite>
</pre>
</section>
<section>
<h2 id="math"><a href="#math">Math</a></h2>
<p>
HTML offers support for common mathematical operators, utilizing the value stack.
</p>
<h3 id="addition"><a href="#addition">Addition</a></h3>
<p>
Addition can be performed with the <code><dd></code> (a<b>dd</b>) tag. This tag will pop the top
two values off the value stack, add the top value to the second to the top value, and
then push the result back onto the value stack.
</p>
<pre>
<data value="2"></data>
<data value="1"></data>
<!-- this dd tag will add 1 to 2 and push the result onto
the value stack -->
<dd></dd>
</pre>
<p>
Note that addition can also be used for string concatenation, as in JavaScript.
</p>
<h3 id="subtraction"><a href="#subtraction">Subtraction</a></h3>
<p>
Subtraction can be performed with the <code><sub></code> tag. This tag will pop the top
two values off the value stack, subtracting the top value from the second to the top value, and
then push the result back onto the value stack.
</p>
<pre>
<data value="2"></data>
<data value="1"></data>
<!-- this sub tag will subtract 1 from 2 and push the result onto
the value stack -->
<sub></sub>
</pre>
<h3 id="multiplication"><a href="#multiplication">Multiplication</a></h3>
<p>
Multiplication can be performed with the <code><ul></code> (m<b>ul</b>) tag. This tag will pop the top
two values off the value stack, multiply the top value by the second to the top value, and
then push the product back onto the value stack.
</p>
<pre>
<data value="2"></data>
<data value="3"></data>
<!-- this ul tag will multiply 2 to 3 and push the result onto
the value stack -->
<ul></ul>
</pre>
<h3 id="division"><a href="#division">Division</a></h3>
<p>
Division can be performed with the <code><div></code> tag. This tag will pop the top
two values off the value stack, divide the second to the top value by the top value, and
then push the result back onto the value stack.
</p>
<pre>
<data value="6"></data>
<data value="3"></data>
<!-- this div tag will divide 6 by 3 and push the result onto
the value stack -->
<div></div>
</pre>
</section>
<section>
<h2 id="stack"><a href="#stack">Stack Operations</a></h2>
<p>
HTML offers commands for direct manipulation the stack.
</p>
<h3 id="duplicate"><a href="#duplicate">Duplicate</a></h3>
<p>
You can duplicate the value on the top of the stack using the <code><dt></code> (duplicate top) tag. This
is useful in cases where you want to use a value more than once for operations that would consume the value, such
as <a href="#if">an if/else</a> situation.
</p>
<pre>
<data value="1"></data>
<!-- this will push a second 1 onto the top of
the value stack -->
<dt></dt>
</pre>
<h3 id="delete"><a href="#delete">Delete</a></h3>
<p>
You can delete/pop the value on the top of the stack using the <code><del></code> tag.
</p>
<pre>
<data value="1"></data>
<!-- this will remove the 1 on the top of the stack -->
<del></del>
</pre>
</section>
<section>
<h2 id="comparison"><a href="#comparison">Comparison Operations</a></h2>
<p>
In HTML, comparisons such as less than, equal, etc. are done on the value stack. Comparison
commands compare two values and leave a boolean on the top of the value stack, which can then
be used with the <a href="#if">"if" command</a> to do conditional execution.
</p>
<h3 id="smaller"><a href="#smaller">Less Than</a></h3>
<p>
You can test if a value is smaller than another value by using the <code><small></code>
tag. This will pop the top two values off the value stack and push true second to top value
is smaller (<) than the top value, false otherwise.
</p>
<pre>
<data value="1"></data>
<data value="2"></data>
<!-- this will push true onto the stack, since 1 is smaller than 2 -->
<small></small>
</pre>
<h3 id="big"><a href="#big">Greater Than</a></h3>
<p>
You can test if a value is smaller than another value by using the <code><big></code>
tag. This will pop the top two values off the value stack and push true second to top value
is larger (>) than the top value, false otherwise.
</p>
<pre>
<data value="1"></data>
<data value="2"></data>
<!-- this will push false onto the stack, since 1 is not bigger than 2 -->
<big></big>
</pre>
<h3 id="eq"><a href="#eq">Equal (Mostly)</a></h3>
<p>
You can test if a value is equal (mostly) than another value by using the <code><em></code>
tag. This will pop the top two values off the value stack and push true second to top value
is equal (==) than the top value, false otherwise.
</p>
<p>
Note that we say "equal (mostly)" because the equality operator in JavaScript (which HTML, the programming language,
is implemented in) has
<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Equality">interesting</a>
semantics.
</p>
<pre>
<s>1</s>
<data value="1"></data>
<!-- this will push true onto the stack, since "1" is equal to 1 -->
<em></em>
</pre>
</section>
<section>
<h2 id="logical"><a href="#logical">Logical Operations</a></h2>
<p>
As with comparisons in HTML, logical operations such as <code>and</code>, <code>or</code>, etc. are done on the value stack.
Logical operations apply to values on the value stack and will leave a boolean on the top of the value stack.
</p>
<p>
All logical operators start with a "b" for "boolean", to make things easier to remember.
</p>
<p>
Note that HTML, the programming language, follows JavaScript, the programming language's (sic)
semantics regarding <a href="https://developer.mozilla.org/en-US/docs/Glossary/Truthy"> "truthiness"</a>.
</p>
<h3 id="and"><a href="#and">And</a></h3>
<p>
You can logically "and" the top two values on the value stack using the <code><b></code>
command. This will pop the top two values off the stack and push the result of them being "anded"
together.
</p>
<pre>
<cite>true</cite>
<data value="1"></data>
<!-- this will push true onto the stack, since true && 1 is true -->
<b></b>
</pre>
<h3 id="or"><a href="#or">Or</a></h3>
<p>
You can logically "or" the top two values on the value stack using the <code><bdo></code>
command. This will pop the top two values off the stack and push the result of them being "ord"
together.
</p>
<pre>
<cite>true</cite>
<cite>false</cite>
<!-- this will push true onto the stack, since true || false is true -->
<bdo></bdo>
</pre>
<h3 id="invert"><a href="#invert">Invert/Not</a></h3>
<p>
You can invert the top value on the value stack using the <code><bdi></code>
command. This will pop the top value off the stack and push the result of it being inverted (<code>true</code>
becomes <code>false</code>, <code>false</code> becomes <code>true</code>).
</p>
<pre>
<cite>false</cite>
<!-- this will push true onto the stack, since !false is true -->
<bdi></bdi>
</pre>
</section>
<section>
<h2 id="control-flow"><a href="#control-flow">Control Flow</a></h2>
<p>
HTML, the programming language, provides three mechanisms for control flow. While these mechanisms may seem primitive,
the can be used to implement any sort of arbitrary control flow pattern you would like.
</p>
<h3 id="if"><a href="#if">If (Conditional Execution)</a></h3>
<p>
Conditional execution can be achieved by using the <code><i></code> (if) tag/command.
This command will pop the top value off the value stack, and, if it is "truthy", will execute
all children commands/tags defined inside of it.
</p>
<pre>
<data value="1"></data>
<data value="1"></data>
<!-- test if 1 is equal to 1 -->
<em></em>
<!-- Since true is on the stack, the child tags/commands will execute here -->
<i>
<s>Yep, 1 == 1</s>
<output></output>
</i>
</pre>
<p>
If you wish to achieve and if/else like flow, you can conveniently <a href="#duplicate">duplicate</a> the boolean
on the top of the stack, use an <code><i/></code> to test the first case (which will consume the top boolean)
and then invert the boolean using <a href="#invert"><code><bdi></code> </a> and test again using <code><i></code>.
</p>
<p>
This gives you a clean and easy to use "if/else" style statement:
</p>
<pre>
<data value="1"></data>
<data value="2"></data>
<!-- test if 1 is equal to 1 -->
<em></em>
<!-- duplicate the result (false) -->
<dt></dt>
<!-- Since false is on the stack, the child tags/commands will not execute here -->
<i>
<s>Yep, 1 == 2</s>
<output></output>
<!-- remove the string from the top of the stack to be clean -->
<del></del>
</i>
<!-- The second copy of false is at the top of the stack, so invert it to true -->
<bdi></bdi>
<i>
<s>Nope, 1 == 2 isn't true, even in JavaScript</s>
<output></output>
</i>
</pre>
<h3 id="return"><a href="#return">Returning</a></h3>
<p>
If you wish to return from <a href="#functions">a function</a> (discussed below) or simply terminate the execution of
a program, you may use the <code><rt></code> tag. This will immediately stop execution in the
current context and either return from a function or halt the execution of a program.
</p>
<pre>
<s>This will print...</s>
<output></output>
<rt></rt>
<s>This will not print...</s>
<output></output>
</pre>
<h3 id="branching"><a href="#branching">Branching</a></h3>
<p>
To execute arbitrary jumps in an HTML, the programming language, you use the anchor tag: <code><a></code>,
by setting the <code>href</code> attribute to the id of the command you wish to jump to. This allows you
to implement things like loops, and can be coupled with conditional execution via the <code><i></code>
tag to implement powerful control flow patterns.
</p>
<p>
Here is a loop that will print from 1 to 10:
</p>
<pre>
<data value="1"></data> <!-- push 1 onto the stack -->
<output id="loop"></output> <!-- print the top of the stack -->
<data value="1"></data> <!-- push 1 onto the stack -->
<dd></dd> <!-- add 1 to the original value -->
<dt></dt> <!-- dup new value -->
<data value="11"></data> <!-- push 11 to compare -->
<small></small> <!-- test new value is smaller than 11 -->
<i> <!-- if smaller than 11 pushed true -->
<a href="#loop"></a> <!-- then jump back to the loop -->
</i>
</pre>
<p>
The crux here is the anchor tag that references the <code><output></code> tag with the id
<code>loop</code>. When this anchor tag is executed it will send control back to that element
to continue in the next iteration of the loop.
</p>
<p>
Note that this jump back to the beginning of the loop is conditional on the top of the stack being
less than 11. Thus you can see that powerful control flow patterns can be created out of these primitive
branching mechanisms.
</p>
<aside>
We are aware of the <a href="https://homepages.cwi.nl/~storm/teaching/reader/Dijkstra68.pdf"> criticisms of GOTO</a>,
which, given a superficial understanding of the anchor tag in HTML, the programming language, may come
to mind for some programmers (mainly juniors). A full response to this criticism is beyond the scope of this document,
but, in summary: you are wrong.
</aside>
</section>
<section>
<h2 id="variables"><a href="#variables">Variables</a></h2>
<p>
Variables in HTML, the programming language, are always "local" to the current context. Global variables,
defined in <code>window</code> can be resolved by name, but cannot be written to. (You must use a property
access on the <code>window</code> object to do that).
</p>
<p>
Note that the values <code>true</code>, <code>false</code> and <code>null</code> are defined as variables
and can be overwritten. Again, we do not recommend this practice, but we are not judgy about it either.
</p>
<h3 id="cite"><a href="#cite">Referencing Variables</a></h3>
<p>
You push a variable onto the top of the value stack by using the <code><cite></code> tag. This will resolve
the variable against the local scope first, and then against <code>window</code>, allowing you to load globally
scoped variables.
</p>
<pre>
<!-- this will push true onto the stack, since
true is a variable with the value true -->
<cite>true</cite>
<output></output>
</pre>
<h3 id="var"><a href="#var">Declaring & Setting a Variable</a></h3>
<p>
You declare or set (same thing) a variable using the <code><var></code>
tag. This will pop the top value off the stack and save it into the variable slot with the
name taken from the <code>title</code> attribute of the variable.
</p>
<pre>
<!-- push 1 onto the value stack -->
<data value="1"></data>
<!-- this creates a locally scoped variable
named 'x' with the value 1 in it -->
<var title="x"></var>
</pre>
<p>
Again, declaring and assigning variables in HTML, the programming language, is the same thing, so you may
have multiple <code><var></code> tags that refer to the same variable name.
</p>
</section>
<section>
<h2 id="io"><a href="#io">I/O</a></h2>
<p>
It's a little late in the game, since we've been using <code><output></code> a bunch already, but HTML, the programming language,
supports simple I/O operations. Of course, HTML, the programming language, can interact with the DOM using
<a href="#functions">functions</a> in order to do I/O as well, but simple I/O can be accomplished directly in
the language itself.
</p>
<h3 id="output"><a href="#output">Outputting Values</a></h3>
<p>
You can output the top of the stack by using the <code><output></code> tag. This will <em>not</em> consume
the value.
</p>
<p>
By default the value will be printed to standard out (<code>console.log</code>). You may change this by
setting the <code>html.meta.out</code> configuration variable to another value.
</p>
<pre>
<!-- this will print "Hello World!" to standard out -->
<s>Hello World!</s>
<output></output>
</pre>
<h3 id="input"><a href="#input">Getting User Input</a></h3>
<p>
Of course you can use the DOM to get user input if you would like. But you can also use the <code><input></code>
tag to get user input.
</p>
<p>
This tag will prompt the user for input using the <code>prompt()</code> method in JavaScript. The message
shown to the user will be taken from the <code>placeholder</code> attribute.
</p>
<p>
If you wish to ask for a number, rather than a string, from the user, you can set the <code>type</code> attribute
of the <code><input></code> to <code>number</code>.
</p>
<p>
The result of the prompt will be pushed onto the top of the value stack.
</p>
<pre>
<!-- this will ask the user for their name, then say hello in the console -->
<input placeholder="What is your name?"/>
<var title="name"></var>
<s>Nice to meet you,</s>
<cite>name</cite>
<dd></dd>
<output></output>
</pre>
</section>
<section>
<h2 id="properties"><a href="#properties">Working With Object Properties</a></h2>
<p>
You can both read and write the properties of objects in HTML, the programming language.
</p>
<h3 id="reading-props"><a href="#reading-props">Reading Properties</a></h3>
<p>
You can read a property of the value on the top of the stack by using the <code><rp></code> (read property)
tag. The name of the property read will be the inner text of the tag. This will consume the element the property is being
read on, so duplicate the top of the stack if you wish to preserve it.
</p>
<pre>
<!-- load the document onto the stack -->
<cite>document</cite>
<!-- load the body property onto the stack -->
<rp>body</rp>
</pre>
<h3 id="setting-props"><a href="#setting-props">Setting Properties</a></h3>
<p>
You can set a property of an object using the <code><samp></code> (set am property)
tag. The name of the property to set will be the inner text of the tag. The value to set into the property
must be on the top of the stack, and the object to set the property of must be second from the top of the stack.
</p>
<p>
Both the value being set into the object and the object will be consumed from the value stack.
</p>
<pre>
<!-- load the document onto the stack -->
<cite>document</cite>
<!-- load the body property onto the stack -->
<rp>body</rp>
<!-- push "Hello World!" onto the stack -->
<s>Hello World!</s>
<!-- set the innerHTML property of the body to "Hello World!" -->
<samp>innerHTML</samp>
</pre>
</section>
<section>
<h2 id="array-access"><a href="#array-access">Working With Arrays</a></h2>
<p>
You can both read and write to indices in arrays in HTML, the programming language.
</p>
<h3 id="reading-arrays"><a href="#reading-arrays">Reading An Array Value</a></h3>
<p>
You can read the value at an index in an array <code><address></code>tag. This command will
consume the top value of the value stack as the index to read from, and the second value from the
top of the stack as the array to read the index from.
</p>
<p>
Note that this tag can also be used to reflectively access properties, by putting a string on the
top of the stack rather than an integer.
</p>
<pre>
<!-- this pushes the array [42, 33] onto the stack -->
<ol>
<li>
<data value="42"></data>
</li>
<li>
<data value="33"></data>
</li>
</ol>
<!-- push the value 0 onto the stack -->
<data value="0"></data>
<!-- consumes the 0 and the array, indexes into the array at position 0,
leaving the value 42 on the top of the value stack-->
<address></address>
</pre>
<h3 id="writing-arrays"><a href="#writing-arrays">Writing An Array Value</a></h3>
<p>
You can write the value at an index in an array <code><ins></code>tag. This command will
consume the top value of the value stack as the value to insert, the second value from the
top of the stack as index to write the value into and the third value from the top of the
stack as the array to set the value into.
</p>
<p>
Note that this tag can also be used to reflectively set properties, by putting a string on the
top of the stack rather than an integer.
</p>
<pre>
<!-- this pushes the array [42, 33] onto the stack -->
<ol>
<li>
<data value="42"></data>
</li>
<li>
<data value="33"></data>
</li>
</ol>
<!-- push the value 0 onto the stack -->
<data value="0"></data>
<!-- push the value 22 onto the stack -->
<data value="22"></data>
<!-- consumes the 22, 0 and the array, indexes into the array at position 0,
and sets it to the value 22-->
<ins></ins>
</pre>
</section>
<section>
<h2 id="functions"><a href="#functions">Functions</a></h2>
<p>
HTML, the programming language, supports the declaration and invocation of functions.
</p>
<h3 id="defining-functions"><a href="#defining-functions">Defining Functions</a></h3>
<p>
You can define functions using the <code><dfn></code> tag. The name of the function will be
taken from the <code>id</code> property of the <code><dfn></code> tag. The body of the function are the
commands/tags within the <code><dfn></code> tag.
</p>
<p>
Arguments passed to the function will be pushed onto the value stack. So, if a function is invoked
with the values (1, 2, 3), the initial value stack will be 3 on top, then 2, then 1.
</p>
<p>
It is common for HTML, the programming language, programmers to save the arguments to a function int variables
using the <code><var></code> command at the beginning of complex functions, in order to make it easier to
refer to them. (Note that this must be done in reverse order to the order that the parameters are received.)
</p>
<p>
The return value of a function defined in HTML, the programming language, is the top value
left on the value stack at the end of the function's execution. There is no need to explicitly return this value
with syntax.
</p>
<p>
Note that you can terminate a functions execution early by using the <a href="#return"><code><rt></code></a> command.
</p>
<pre>
<!-- this defines a simple function that squares the argument -->
<dfn id="square">
<!-- duplicate the argument to the function, implicitly on the top of the stack -->
<dt></dt>
<!-- multiply it and return (leaving it on the top of the stack -->
<ul></ul>
</dfn>
</pre>
<h3 id="invoking-functions"><a href="#invoking-functions">Invoking Functions</a></h3>
<p>
To invoke functions, HTML, the programming language, reuses the <code><a></code> tag.
If the <code><a></code>'s <code>href</code> attribute begins with <code>javascript:</code>,
it will invoke a function rather than jump to an element.
</p>
<p>
The function that will be invoked is resolved by the name after the <code>javascript:</code>, but
before the first open-parenthesis, <code>(</code>. Note that arguments to the function defined
in the <code>href</code> attribute are ignored.
</p>
<p>
Instead, arguments are passed by executing <em>child</em> elements within the <code><a></code>
tag. All elements within the <code><a></code> tag will be executed and then the <em>new</em> values
that are pushed onto the value stack by the children will be removed from the stack and used as the arguments to the
function.
</p>
<p>
When a function is invoked, it's return value (if any), will be pushed onto the stack.
</p>
<pre>
<!-- invoke the square() function defined above, with the argument 12 -->
<a href="javascript:square()">
<data value="12"></data>
</a>
<!-- output the result (144) -->
<output></output>
</pre>
<h4 id="invoking-functions-objects"><a href="#invoking-functions-objects">Invoking Functions On Objects</a></h4>
<p>
If you wish to invoke a function on an object (rather than on the global <code>window</code> object), you
can set the <code>target</code> attribute of the anchor tag to <code>_top</code>. This will make it consume
the top of the value stack and invoke the method on that object.
</p>
<pre>
<!-- load the document -->
<cite>document<cite>
<!-- load all elements with the class .highlighted onto the stack
by invoking the querySelectorAll() method on the docuemtn-->
<a href="javascript:querySelectorAll()"
target="_top">
<s>.highlighted</s>
</a>
<!-- output the result -->
<output></output>
</pre>
</section>
<section>
<h2 id="js"><a href="#js">JavaScript Integration</a></h2>
<p>
HTML, the programming language, integrates cleanly with JavaScript. You can invoke JavaScript
functions just like normal functions, and JavaScript functions can invoke HTML, The Programming
Language as well.
</p>
<p>
JavaScript developers should be able to get comfortable with HTML, the programming language,
very quickly.
</p>
<p>
You can also execute HTML, the programming language, "scriptlets" as strings in JavaScript,
using the <code>html.exec()</code> utility function.
</p>
</section>
<section>
<h2 id="config"><a href="#config">Configuring/Extending</a></h2>
<p>
You can configure the standard out and standard error of HTML, The Programming Langauge bu
setting the <code>html.meta.out</code> and <code>html.meta.err</code> values to functions
of your design.
</p>
<h3 id="extending"><a href="#extending">Extending</a></h3>
<p>
HTML, the programming language, can be extended or modified by adding or modifying the entries
found in <code>html.meta.commands</code>, which map a tag name to a function that takes an element
and context, and implements some sort of behavior.
</p>
<p>
As an example, if we wanted to make the <code><pre></code> tag print the entire value stack
we could write something like this in JavaScript:
</p>
<pre>
html.meta.commands["pre"] = function(elt, env) {
console.log(env.stack);
}
</pre>
<p>
With this definition you could then write the following code:
</p>
<pre>
<data value="1"></data>
<data value="2"></data>
<data value="3"></data>
<!-- will print the stack [1, 2, 3] to console.out -->
<pre></pre>
</pre>
<p>
You can also implement arbitrary control flow by returning the next element in the DOM to execute
from this function.
</p>
</section>
<section>
<h2 id="debugging"><a href="#debugging">Debugging</a></h2>
<p>
In HTML, the programming language, simple "log" style debugging can be done via the <wbr> tag, which will
print out the content of the tags <code>title</code> attribute, as well as the current stack and variable values.
</p>
<p>
HTML, the programming language, also includes an integrated debugger, HDB, the HTML Debugger, to assist in debugging
HTML programs. To access the debugger, insert a function callback into the <code>html.meta.debugger</code> field.
</p>
<pre>
html.meta.debug = function(hdb, elt, env, cmd)
{
// you can set a JavaScript breakpoint here
hdb.break();
}
</pre>
<p>
You can then add a breakpoint to an HTML element by adding the <code>data-hdb-breakpoint</code> attribute to it.
This will cause the runtime to invoke the HDB debugger <em>before</em> the element is executed.
</p>
<p>
The callback can have up to four parameters:
</p>
<ul>
<li><code>hdb</code> - The debugger</li>
<li><code>elt</code> - The element to be executed</li>
<li><code>env</code> - The current environment (including vars and the value stack)</li>
<li><code>cmd</code> - The implementation of the command</li>
</ul>
<p>
By setting a JavaScript breakpoint in the callback, you can inspect the current environment and command. You
can also invoke one of the following methods on the <code>hdb</code> object:
</p>
<ul>
<li><code>step()</code> - Execute the current instruction and stop before the next one.</li>
<li><code>continue()</code> - Stop debugging and continue until the next breakpoint (or the program finishes)</li>
<li><code>jumpTo(elt)</code> - Don't execute the current element, instead jump to the given HTML element</li>
</ul>
</section>
<section>
<h2 id="faq"><a href="#faq">Frequently Asked Questions</a></h2>
<ul>
<li>
<i>
I have found a bug in HTML, the programming language. What should I do?
</i>
<p>
HTML, the programming language, is correct, by definition. The bug therefore is not in the programming
language, but rather it is in you.
</p>
</li>
<li>
<i>