/
README.html
1093 lines (925 loc) · 43.5 KB
/
README.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
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
<head>
<!-- 2022-11-25 Fri 19:13 -->
<meta http-equiv="Content-Type" content="text/html;charset=utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>‎</title>
<meta name="author" content="mzimmermann" />
<meta name="generator" content="Org Mode" />
<style>
#content { max-width: 60em; margin: auto; }
.title { text-align: center;
margin-bottom: .2em; }
.subtitle { text-align: center;
font-size: medium;
font-weight: bold;
margin-top:0; }
.todo { font-family: monospace; color: red; }
.done { font-family: monospace; color: green; }
.priority { font-family: monospace; color: orange; }
.tag { background-color: #eee; font-family: monospace;
padding: 2px; font-size: 80%; font-weight: normal; }
.timestamp { color: #bebebe; }
.timestamp-kwd { color: #5f9ea0; }
.org-right { margin-left: auto; margin-right: 0px; text-align: right; }
.org-left { margin-left: 0px; margin-right: auto; text-align: left; }
.org-center { margin-left: auto; margin-right: auto; text-align: center; }
.underline { text-decoration: underline; }
#postamble p, #preamble p { font-size: 90%; margin: .2em; }
p.verse { margin-left: 3%; }
pre {
border: 1px solid #e6e6e6;
border-radius: 3px;
background-color: #f2f2f2;
padding: 8pt;
font-family: monospace;
overflow: auto;
margin: 1.2em;
}
pre.src {
position: relative;
overflow: auto;
}
pre.src:before {
display: none;
position: absolute;
top: -8px;
right: 12px;
padding: 3px;
color: #555;
background-color: #f2f2f299;
}
pre.src:hover:before { display: inline; margin-top: 14px;}
/* Languages per Org manual */
pre.src-asymptote:before { content: 'Asymptote'; }
pre.src-awk:before { content: 'Awk'; }
pre.src-authinfo::before { content: 'Authinfo'; }
pre.src-C:before { content: 'C'; }
/* pre.src-C++ doesn't work in CSS */
pre.src-clojure:before { content: 'Clojure'; }
pre.src-css:before { content: 'CSS'; }
pre.src-D:before { content: 'D'; }
pre.src-ditaa:before { content: 'ditaa'; }
pre.src-dot:before { content: 'Graphviz'; }
pre.src-calc:before { content: 'Emacs Calc'; }
pre.src-emacs-lisp:before { content: 'Emacs Lisp'; }
pre.src-fortran:before { content: 'Fortran'; }
pre.src-gnuplot:before { content: 'gnuplot'; }
pre.src-haskell:before { content: 'Haskell'; }
pre.src-hledger:before { content: 'hledger'; }
pre.src-java:before { content: 'Java'; }
pre.src-js:before { content: 'Javascript'; }
pre.src-latex:before { content: 'LaTeX'; }
pre.src-ledger:before { content: 'Ledger'; }
pre.src-lisp:before { content: 'Lisp'; }
pre.src-lilypond:before { content: 'Lilypond'; }
pre.src-lua:before { content: 'Lua'; }
pre.src-matlab:before { content: 'MATLAB'; }
pre.src-mscgen:before { content: 'Mscgen'; }
pre.src-ocaml:before { content: 'Objective Caml'; }
pre.src-octave:before { content: 'Octave'; }
pre.src-org:before { content: 'Org mode'; }
pre.src-oz:before { content: 'OZ'; }
pre.src-plantuml:before { content: 'Plantuml'; }
pre.src-processing:before { content: 'Processing.js'; }
pre.src-python:before { content: 'Python'; }
pre.src-R:before { content: 'R'; }
pre.src-ruby:before { content: 'Ruby'; }
pre.src-sass:before { content: 'Sass'; }
pre.src-scheme:before { content: 'Scheme'; }
pre.src-screen:before { content: 'Gnu Screen'; }
pre.src-sed:before { content: 'Sed'; }
pre.src-sh:before { content: 'shell'; }
pre.src-sql:before { content: 'SQL'; }
pre.src-sqlite:before { content: 'SQLite'; }
/* additional languages in org.el's org-babel-load-languages alist */
pre.src-forth:before { content: 'Forth'; }
pre.src-io:before { content: 'IO'; }
pre.src-J:before { content: 'J'; }
pre.src-makefile:before { content: 'Makefile'; }
pre.src-maxima:before { content: 'Maxima'; }
pre.src-perl:before { content: 'Perl'; }
pre.src-picolisp:before { content: 'Pico Lisp'; }
pre.src-scala:before { content: 'Scala'; }
pre.src-shell:before { content: 'Shell Script'; }
pre.src-ebnf2ps:before { content: 'ebfn2ps'; }
/* additional language identifiers per "defun org-babel-execute"
in ob-*.el */
pre.src-cpp:before { content: 'C++'; }
pre.src-abc:before { content: 'ABC'; }
pre.src-coq:before { content: 'Coq'; }
pre.src-groovy:before { content: 'Groovy'; }
/* additional language identifiers from org-babel-shell-names in
ob-shell.el: ob-shell is the only babel language using a lambda to put
the execution function name together. */
pre.src-bash:before { content: 'bash'; }
pre.src-csh:before { content: 'csh'; }
pre.src-ash:before { content: 'ash'; }
pre.src-dash:before { content: 'dash'; }
pre.src-ksh:before { content: 'ksh'; }
pre.src-mksh:before { content: 'mksh'; }
pre.src-posh:before { content: 'posh'; }
/* Additional Emacs modes also supported by the LaTeX listings package */
pre.src-ada:before { content: 'Ada'; }
pre.src-asm:before { content: 'Assembler'; }
pre.src-caml:before { content: 'Caml'; }
pre.src-delphi:before { content: 'Delphi'; }
pre.src-html:before { content: 'HTML'; }
pre.src-idl:before { content: 'IDL'; }
pre.src-mercury:before { content: 'Mercury'; }
pre.src-metapost:before { content: 'MetaPost'; }
pre.src-modula-2:before { content: 'Modula-2'; }
pre.src-pascal:before { content: 'Pascal'; }
pre.src-ps:before { content: 'PostScript'; }
pre.src-prolog:before { content: 'Prolog'; }
pre.src-simula:before { content: 'Simula'; }
pre.src-tcl:before { content: 'tcl'; }
pre.src-tex:before { content: 'TeX'; }
pre.src-plain-tex:before { content: 'Plain TeX'; }
pre.src-verilog:before { content: 'Verilog'; }
pre.src-vhdl:before { content: 'VHDL'; }
pre.src-xml:before { content: 'XML'; }
pre.src-nxml:before { content: 'XML'; }
/* add a generic configuration mode; LaTeX export needs an additional
(add-to-list 'org-latex-listings-langs '(conf " ")) in .emacs */
pre.src-conf:before { content: 'Configuration File'; }
table { border-collapse:collapse; }
caption.t-above { caption-side: top; }
caption.t-bottom { caption-side: bottom; }
td, th { vertical-align:top; }
th.org-right { text-align: center; }
th.org-left { text-align: center; }
th.org-center { text-align: center; }
td.org-right { text-align: right; }
td.org-left { text-align: left; }
td.org-center { text-align: center; }
dt { font-weight: bold; }
.footpara { display: inline; }
.footdef { margin-bottom: 1em; }
.figure { padding: 1em; }
.figure p { text-align: center; }
.equation-container {
display: table;
text-align: center;
width: 100%;
}
.equation {
vertical-align: middle;
}
.equation-label {
display: table-cell;
text-align: right;
vertical-align: middle;
}
.inlinetask {
padding: 10px;
border: 2px solid gray;
margin: 10px;
background: #ffffcc;
}
#org-div-home-and-up
{ text-align: right; font-size: 70%; white-space: nowrap; }
textarea { overflow-x: auto; }
.linenr { font-size: smaller }
.code-highlighted { background-color: #ffff00; }
.org-info-js_info-navigation { border-style: none; }
#org-info-js_console-label
{ font-size: 10px; font-weight: bold; white-space: nowrap; }
.org-info-js_search-highlight
{ background-color: #ffff00; color: #000000; font-weight: bold; }
.org-svg { width: 90%; }
</style>
</head>
<body>
<div id="content" class="content">
<div id="table-of-contents" role="doc-toc">
<h2>Table of Contents</h2>
<div id="text-table-of-contents" role="doc-toc">
<ul>
<li><a href="#org7066a97">1. About this Package: Org Babel Dart (ob-dart).</a></li>
<li><a href="#org51e1b2d">2. A Simple Example of running Dart code in Emacs org-mode (Babel source blocks)</a></li>
<li><a href="#org37012a3">3. Installation of ob-dart from MELPA</a>
<ul>
<li><a href="#orgd63cbd9">3.1. ob-dart prerequisite - Dart language is installed on your system, for example in <code>$HOME/software/dart-sdk</code></a></li>
<li><a href="#org0c8e732">3.2. Installing ob-dart and adding Dart to list of Org Babel supported languages</a>
<ul>
<li><a href="#org0504406">3.2.1. Installation from MELPA</a></li>
<li><a href="#org9b9a2d9">3.2.2. Post installation: Adding Dart to list of Org Babel supported languages</a>
<ul>
<li><a href="#org621ec0b">3.2.2.1. Current post-installation</a></li>
<li><a href="#org9547fd4">3.2.2.2. Future post-installation</a></li>
</ul>
</li>
</ul>
</li>
</ul>
</li>
<li><a href="#orge70a6f1">4. Alternative to installation from MELPA (probably no reason to use)</a></li>
<li><a href="#orgb342774">5. About Emacs Org Mode, and Babel</a></li>
<li><a href="#org761b280">6. How Org Babel Dart works</a></li>
<li><a href="#orgd204c95">7. Current Limitations</a></li>
<li><a href="#org7921792">8. A Brief Presentation of Dart using this package (ob-dart)</a>
<ul>
<li><a href="#org1d12228">8.1. Using Org Babel Dart - quick summary.</a>
<ul>
<li><a href="#org1c8d8f7">8.1.1. Dart Language basics</a></li>
<li><a href="#orgbb7269f">8.1.2. Dart sample code in org babel.</a></li>
<li><a href="#orgf31601f">8.1.3. Conditionals (flow control)</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="#org9e9785d">9. Presenting :results value and :results output and :results output(or value) raw</a></li>
<li><a href="#orga264977">10. Resolving Current Limitations</a></li>
<li><a href="#orgfe14116">11. Security</a></li>
<li><a href="#org89886ff">12. Todos (apart from resolving the limitations above)</a></li>
<li><a href="#orgc5dff9b">13. Bugs</a></li>
<li><a href="#org6c702e9">14. Notes</a></li>
</ul>
</div>
</div>
<p>
This document is a (relatively) short description of using Dart as one of the languages in Emacs org-mode Babel.
</p>
<div id="outline-container-org7066a97" class="outline-2">
<h2 id="org7066a97"><span class="section-number-2">1.</span> About this Package: Org Babel Dart (ob-dart).</h2>
<div class="outline-text-2" id="text-1">
<p>
This emacs package (ob-dart.el) supports running Dart code in Emacs org-mode (Babel source blocks).
</p>
</div>
</div>
<div id="outline-container-org51e1b2d" class="outline-2">
<h2 id="org51e1b2d"><span class="section-number-2">2.</span> A Simple Example of running Dart code in Emacs org-mode (Babel source blocks)</h2>
<div class="outline-text-2" id="text-2">
<p>
After installation (see the <a href="#org0504406">3.2.1</a> section), try this:
</p>
<ul class="org-ul">
<li>In this README.org file, viewed in emacs</li>
<li>Put cursor anywhere inside the <code>#+begin_src ... #+end_src</code> block below (this block is hidden if you are reading this on Github)</li>
<li>Hit C-c C-c (holding down the Ctrl button, hit c twice). Thi will run the code snippet in Dart, and show result below in the <code>#+results</code> section.</li>
</ul>
<div class="org-src-container">
<pre class="src src-dart"><span style="color: #b4fa70;">return</span> [<span style="color: #e9b2e3;">1</span>,<span style="color: #e9b2e3;">2</span>, <span style="color: #e9b2e3;">11</span>,<span style="color: #e9b2e3;">15</span>].reduce(max);
</pre>
</div>
<pre class="example">
15
</pre>
<p>
There are more examples in the Examples section.
</p>
</div>
</div>
<div id="outline-container-org37012a3" class="outline-2">
<h2 id="org37012a3"><span class="section-number-2">3.</span> Installation of ob-dart from MELPA</h2>
<div class="outline-text-2" id="text-3">
</div>
<div id="outline-container-orgd63cbd9" class="outline-3">
<h3 id="orgd63cbd9"><span class="section-number-3">3.1.</span> ob-dart prerequisite - Dart language is installed on your system, for example in <code>$HOME/software/dart-sdk</code></h3>
<div class="outline-text-3" id="text-3-1">
<p>
If you do not have Dart installed, follow steps below to install Dart first
</p>
<ul class="org-ul">
<li>Download and extract Dart from <a href="https://www.dartlang.org/downloads/">https://www.dartlang.org/downloads/</a></li>
<li>For the rest of this installation, let us assume Dart was extracted to <code>$HOME/software/dart-sdk</code></li>
<li><p>
Add the Dart installation bin directory to your PATH. Add to your profile (such as .bashrc or .bash_profile if you use bash) :
</p>
<pre class="example" id="org76c6eec">
export PATH=${PATH}:$HOME/software/dart-sdk/bin
</pre></li>
</ul>
</div>
</div>
<div id="outline-container-org0c8e732" class="outline-3">
<h3 id="org0c8e732"><span class="section-number-3">3.2.</span> Installing ob-dart and adding Dart to list of Org Babel supported languages</h3>
<div class="outline-text-3" id="text-3-2">
</div>
<div id="outline-container-org0504406" class="outline-4">
<h4 id="org0504406"><span class="section-number-4">3.2.1.</span> Installation from MELPA</h4>
<div class="outline-text-4" id="text-3-2-1">
<p>
The ob-dart package is now published on MELPA, so, assuming you have MELPA in the list of your package repositories, you can install ob-dart directly from Emacs. Follow the steps below:
</p>
<ul class="org-ul">
<li>In emacs, use the <code>M-x package-list-packages</code> command.
<ul class="org-ul">
<li>Search for the string <code>ob-dart</code>, and put your cursor on the <code>ob-dart</code> line.</li>
<li>Press the <code>i</code> key (select line for Install).</li>
<li>Press the <code>x</code> key (Execute installs).</li>
</ul></li>
</ul>
</div>
</div>
<div id="outline-container-org9b9a2d9" class="outline-4">
<h4 id="org9b9a2d9"><span class="section-number-4">3.2.2.</span> Post installation: Adding Dart to list of Org Babel supported languages</h4>
<div class="outline-text-4" id="text-3-2-2">
</div>
<div id="outline-container-org621ec0b" class="outline-5">
<h5 id="org621ec0b"><span class="section-number-5">3.2.2.1.</span> Current post-installation</h5>
<div class="outline-text-5" id="text-3-2-2-1">
<p>
Currently, even though you now have ob-dart installed, you need to add Dart to the list of Org Babel supported languages.
</p>
<ul class="org-ul">
<li><p>
Add the following code to your emacs init file (such as <code>$HOME/.emacs.d/init.el</code>)
</p>
<div class="org-src-container">
<pre class="src src-emacs-lisp">
<span style="color: #73d216;">;; </span><span style="color: #73d216;">For Dart to appear as one of the values of </span>
<span style="color: #73d216;">;; </span><span style="color: #73d216;">customize-variable org-babel-load-languages, add this code:</span>
(<span style="color: #b4fa70;">require</span> '<span style="color: #e9b2e3;">ob-dart</span>)
(add-to-list 'org-babel-load-languages '(dart . t))
</pre>
</div></li>
</ul>
</div>
</div>
<div id="outline-container-org9547fd4" class="outline-5">
<h5 id="org9547fd4"><span class="section-number-5">3.2.2.2.</span> Future post-installation</h5>
<div class="outline-text-5" id="text-3-2-2-2">
<p>
After we add Dart to Babel list of supported languages, we will be able to just add Dart support using customize (as opposed to org-babel-do-load-languages)
</p>
<ul class="org-ul">
<li>In emacs, use the <code>M-x customize-variables</code> command</li>
<li>On the prompt, respond <code>org-babel-load-languages</code></li>
<li>In the Org Babel Load Languages section, INS (insert) a new item, named Dart, and click State->Save for future session</li>
</ul>
<p>
Last step: Test a Dart code block in a org file. To do this, you can edit this file README.org in emacs, and follow the description of the simple example above.
</p>
</div>
</div>
</div>
</div>
</div>
<div id="outline-container-orge70a6f1" class="outline-2">
<h2 id="orge70a6f1"><span class="section-number-2">4.</span> Alternative to installation from MELPA (probably no reason to use)</h2>
<div class="outline-text-2" id="text-4">
<p>
It you are not using MELPA, following the steps below will ensure everything needed is installed.
</p>
<ul class="org-ul">
<li>Make sure org-mode is installed in your emacs. Recent versions of emacs do include org mode.</li>
<li>Download and install ob-dart.el in emacs from this Github repository:
<ul class="org-ul">
<li>Download ob-dart.el from Github <a href="https://github.com/mzimmerm/ob-dart">https://github.com/mzimmerm/ob-dart</a> and save it to a directory.
For the rest of this installation, let us assume you have saved ob-dart.el in
<code>$HOME/.emacs.d/ob-dart.el</code></li>
<li><p>
Add the following code to your emacs init file (such as <code>$HOME/.emacs.d/init.el</code>)
</p>
<div class="org-src-container">
<pre class="src src-emacs-lisp">
<span style="color: #73d216;">;; </span><span style="color: #73d216;">Step 1: Add ob-dart to /path/to/ob-dart.el, for example:</span>
(load-file <span style="color: #e9b96e;">"~/.emacs.d/ob-dart.el"</span>)
(<span style="color: #b4fa70;">require</span> '<span style="color: #e9b2e3;">ob-dart</span>)
<span style="color: #73d216;">;; </span><span style="color: #73d216;">Step 2: For Dart to appear as one of the values of </span>
<span style="color: #73d216;">;; </span><span style="color: #73d216;">customize-variable org-babel-load-languages, add this code:</span>
(org-babel-do-load-languages
'org-babel-load-languages
'(
(dart . t)
<span style="color: #73d216;">;; </span><span style="color: #73d216;">other languages may be added here</span>
<span style="color: #73d216;">;; </span><span style="color: #73d216;">(python . t)</span>
<span style="color: #73d216;">;; </span><span style="color: #73d216;">etc</span>
)
)
</pre>
</div></li>
</ul></li>
</ul>
<ul class="org-ul">
<li>Once you have ob-dart installed, test a Dart code block in a org file. To do this, you can edit this file README.org in emacs, and follow the description of the simple example above.</li>
</ul>
</div>
</div>
<div id="outline-container-orgb342774" class="outline-2">
<h2 id="orgb342774"><span class="section-number-2">5.</span> About Emacs Org Mode, and Babel</h2>
<div class="outline-text-2" id="text-5">
<p>
Org Mode (org-mode) is a mode for editing files in text, in a "wysiwyggy" way.
</p>
<p>
(org-mode) Babel is used in literal programming, reproducible research, for documentation and more.
</p>
<p>
You can read about org-mode and org-mode babel on these links:
</p>
<ul class="org-ul">
<li><a href="http://org-babel.readthedocs.io/en/latest/">http://org-babel.readthedocs.io/en/latest/</a></li>
<li><a href="http://orgmode.org/worg/org-contrib/babel/intro.html">http://orgmode.org/worg/org-contrib/babel/intro.html</a></li>
<li><a href="http://ehneilsen.net/notebook/orgExamples/org-examples.html">http://ehneilsen.net/notebook/orgExamples/org-examples.html</a></li>
<li><a href="http://orgmode.org/">http://orgmode.org/</a></li>
</ul>
</div>
</div>
<div id="outline-container-org761b280" class="outline-2">
<h2 id="org761b280"><span class="section-number-2">6.</span> How Org Babel Dart works</h2>
<div class="outline-text-2" id="text-6">
<p>
Before executing Dart code between the <code>#+begin_src and #+end_src</code>, a temporary file is generated with several standard Dart library imports (core, async, collection etc) on top. Below, the code is wrapped in a main() method. This temporary file is then run as command line dart. Org mode inserts it's output back in the document in the #+RESULTS section, just below the code.
</p>
<p>
This is the similar as code between the <code>#+begin_src and #+end_src</code> in main(), executed from Dart, with all security implications.
</p>
</div>
</div>
<div id="outline-container-orgd204c95" class="outline-2">
<h2 id="orgd204c95"><span class="section-number-2">7.</span> Current Limitations</h2>
<div class="outline-text-2" id="text-7">
<ol class="org-ol">
<li>Major: The :var Input to org babel code blocks is not supported in this ob-dart version (neither scalar variables nor tables).</li>
<li>Medium: The section of code between <code>#+begin_src and #end_src</code> can only run Dart code that would normally be placed <i>inside a top-level Dart function</i> (top-level functions: see <a href="https://www.dartlang.org/dart-tips/dart-tips-ep-6.html">https://www.dartlang.org/dart-tips/dart-tips-ep-6.html</a> ). Ob-dart wraps this code as <code>main() { begin_src to end_src }</code>. This is to support the main intended use of Babel to write functions in a mix of languages in a simple way. As a result of this implementation, the ability to run "any" Dart code that would normally be placed in a file and run as if we ran <code>dart my-app.dart</code> is missing. See <i>Resolving Current Limitations</i> for detail discussion.</li>
<li>Medium: Ability to pass a flag specifying to run in checked / production mode</li>
<li>Medium: Need to figure out how to support packages. Should support packages.yaml somehow. How is this done in dartpad?.</li>
<li>Medium: Asserts failures cause org mode result formatting error. Likely an org-mode issue</li>
<li>Minor(?): Missing support for Org Babel "session mode" which allows to run Dart in and "incremental" mode (as in iPython/Jupiter): This may not be resonably doable at this time, as Dart does not have a REPL yet - although it looks like <a href="http://news.dartlang.org/2016/05/unboxing-packages-vmserviceclient.html">the vm_service_client</a> may allow to write a Dart REPL. So perhaps one day.</li>
<li>Minor(?): Strings outputted by Dart to stdio by methods other than print() (e.g. loggers?) would still show up in the :results value mode. Need to look more into loggers, not sure how to resolve this yet. Maybe this is not so important due to the audience size.</li>
</ol>
</div>
</div>
<div id="outline-container-org7921792" class="outline-2">
<h2 id="org7921792"><span class="section-number-2">8.</span> A Brief Presentation of Dart using this package (ob-dart)</h2>
<div class="outline-text-2" id="text-8">
<p>
Dart already has excellent tools for learning and quickly running Dart code and code snippets, such as <a href="https://dartpad.dartlang.org/">https://dartpad.dartlang.org/</a>. The usefulness of this package (Dart in org mode) is thus to be seen.
</p>
<p>
Perhaps it can be useful to make use of the easy editing in org mode, and then use the amazing org-mode tools to convert org documents to other formats, ODT, html, PDF and others. So having Dart working in org mode babel can be used for documenting, generating pdf, or html for blogs or pages that need include Dart code and results.
</p>
<p>
The following paragraph is a simple example of how Org Babel Dart might be used.
</p>
</div>
<div id="outline-container-org1d12228" class="outline-3">
<h3 id="org1d12228"><span class="section-number-3">8.1.</span> Using Org Babel Dart - quick summary.</h3>
<div class="outline-text-3" id="text-8-1">
</div>
<div id="outline-container-org1c8d8f7" class="outline-4">
<h4 id="org1c8d8f7"><span class="section-number-4">8.1.1.</span> Dart Language basics</h4>
<div class="outline-text-4" id="text-8-1-1">
<p>
This table shows Dart basics.
</p>
<table border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides">
<colgroup>
<col class="org-left" />
<col class="org-left" />
</colgroup>
<thead>
<tr>
<th scope="col" class="org-left">Syntax</th>
<th scope="col" class="org-left">Desc</th>
</tr>
</thead>
<tbody>
<tr>
<td class="org-left"><code>// This is a comment in Dart</code></td>
<td class="org-left">Comment</td>
</tr>
<tr>
<td class="org-left"><code>var length = 10;</code></td>
<td class="org-left">Variable declaration, untyped</td>
</tr>
<tr>
<td class="org-left"><code>print("Hello");</code></td>
<td class="org-left">print to stdout</td>
</tr>
<tr>
<td class="org-left"> </td>
<td class="org-left">etc</td>
</tr>
</tbody>
</table>
</div>
</div>
<div id="outline-container-orgbb7269f" class="outline-4">
<h4 id="orgbb7269f"><span class="section-number-4">8.1.2.</span> Dart sample code in org babel.</h4>
<div class="outline-text-4" id="text-8-1-2">
<p>
If we want to include a piece of Dart code in a Org document, we could use a block similar to this.
</p>
<div class="org-src-container">
<pre class="src src-dart"><span style="color: #b4fa70;">var</span> <span style="color: #fcaf3e;">str</span> = <span style="color: #e9b96e;">"hello"</span> + <span style="color: #e9b96e;">" there"</span>;
print (str == <span style="color: #e9b96e;">"hello there"</span>);
print (str == <span style="color: #e9b96e;">"not hello there"</span>);
</pre>
</div>
<pre class="example">
true
false
</pre>
<p>
Entering C-c C-c (Control down, enter the c key twice) with cursor between <code>#+begin_src and #+end_src</code> will produce the results section - printing true and false. This is because the code block arguments specify the following:
</p>
<p>
<code>:results output</code>
</p>
<p>
If we were to export the Org documents, say to PDF, both source code and the results would appear in the PDF. This is because we specify:
</p>
<p>
<code>:exports both</code>
</p>
</div>
</div>
<div id="outline-container-orgf31601f" class="outline-4">
<h4 id="orgf31601f"><span class="section-number-4">8.1.3.</span> Conditionals (flow control)</h4>
<div class="outline-text-4" id="text-8-1-3">
<p>
We can use any valid Dart code, including functions, except class definitions.
</p>
<p>
Here we use <code>if..else</code> for flow control.
</p>
<div class="org-src-container">
<pre class="src src-dart"><span style="color: #b4fa70;">var</span> <span style="color: #fcaf3e;">status</span> = <span style="color: #e9b2e3;">true</span>;
<span style="color: #b4fa70;">if</span> (status) {
print (<span style="color: #e9b96e;">'Status was true'</span>);
} <span style="color: #b4fa70;">else</span> {
print(<span style="color: #e9b96e;">'Status was false'</span>);
}
</pre>
</div>
<pre class="example">
Status was true
</pre>
</div>
</div>
</div>
</div>
<div id="outline-container-org9e9785d" class="outline-2">
<h2 id="org9e9785d"><span class="section-number-2">9.</span> Presenting :results value and :results output and :results output(or value) raw</h2>
<div class="outline-text-2" id="text-9">
<p>
Examples show the rather boring differences between various collection types (:results output/value with potential format raw). See <a href="http://orgmode.org/manual/results.html">http://orgmode.org/manual/results.html</a>
</p>
<p>
First, source block which asks for <code>:results value</code> should result in the string representation of the last statement in the source block which <b>must be marked with the <code>return</code> keyword</b>.
</p>
<div class="org-src-container">
<pre class="src src-dart"><span style="color: #b4fa70;">var</span> <span style="color: #fcaf3e;">listMax</span> = [<span style="color: #e9b2e3;">1</span>,<span style="color: #e9b2e3;">2</span>,<span style="color: #e9b2e3;">3</span>].reduce(max);
print (<span style="color: #e9b96e;">"In output mode, all printed lines show in result"</span>);
print (<span style="color: #e9b96e;">"List max printed = "</span> + listMax.toString());
<span style="color: #b4fa70;">return</span> <span style="color: #e9b96e;">"List max returned = "</span> + listMax.toString(); <span style="color: #73d216;">// </span><span style="color: #73d216;">Note: bug in Org export (C-c C-e h o) prevents a syntactically correct: return "List max returned = ${listMax}"; </span>
</pre>
</div>
<pre class="example">
List max returned = 3
</pre>
<p>
The same source block which asks for <code>:results value table</code> should result in the string representation of the last statement, converted to a Org-table on pipe characters if the resulting object is a collection. As the result is not a collection, the whole string representation is surrounded with pipe characters as one table cell.
</p>
<div class="org-src-container">
<pre class="src src-dart"><span style="color: #b4fa70;">var</span> <span style="color: #fcaf3e;">listMax</span> = [<span style="color: #e9b2e3;">1</span>,<span style="color: #e9b2e3;">2</span>,<span style="color: #e9b2e3;">3</span>].reduce(max);
print (<span style="color: #e9b96e;">"In output mode, all printed lines show in result"</span>);
print (<span style="color: #e9b96e;">"List max printed = "</span> + listMax.toString());
<span style="color: #b4fa70;">return</span> <span style="color: #e9b96e;">"List max returned = "</span> + listMax.toString();
</pre>
</div>
<table border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides">
<colgroup>
<col class="org-left" />
</colgroup>
<tbody>
<tr>
<td class="org-left">List max returned = 3</td>
</tr>
</tbody>
</table>
<p>
To output an actual table, return a list. Like this:
</p>
<div class="org-src-container">
<pre class="src src-dart"><span style="color: #b4fa70;">return</span> [<span style="color: #e9b2e3;">1</span>,<span style="color: #e9b2e3;">2</span>];
</pre>
</div>
<table border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides">
<colgroup>
<col class="org-right" />
<col class="org-right" />
</colgroup>
<tbody>
<tr>
<td class="org-right">1</td>
<td class="org-right">2</td>
</tr>
</tbody>
</table>
<p>
Or if you want to return a table with headers, like this:
</p>
<div class="org-src-container">
<pre class="src src-dart"><span style="color: #b4fa70;">return</span> [
[<span style="color: #e9b96e;">"col_1"</span>, <span style="color: #e9b96e;">"col_2"</span>], <span style="color: #73d216;">// </span><span style="color: #73d216;">no spaces in headers; default impl breaks on them</span>
[<span style="color: #e9b2e3;">1</span>, <span style="color: #e9b2e3;">2</span>],
[<span style="color: #e9b2e3;">3</span>, <span style="color: #e9b2e3;">4</span>]
];
</pre>
</div>
<table border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides">
<colgroup>
<col class="org-right" />
<col class="org-right" />
</colgroup>
<tbody>
<tr>
<td class="org-right">col_1</td>
<td class="org-right">col_2</td>
</tr>
<tr>
<td class="org-right">1</td>
<td class="org-right">2</td>
</tr>
<tr>
<td class="org-right">3</td>
<td class="org-right">4</td>
</tr>
</tbody>
</table>
<p>
Next, evaluation of a source block which asks for <code>:results output</code> results in showing every string in the code which was directed to stdout (all print statements are directed).
</p>
<div class="org-src-container">
<pre class="src src-dart"><span style="color: #b4fa70;">var</span> <span style="color: #fcaf3e;">listMax</span> = [<span style="color: #e9b2e3;">1</span>,<span style="color: #e9b2e3;">2</span>,<span style="color: #e9b2e3;">3</span>].reduce(max);
print (<span style="color: #e9b96e;">"In output mode, all printed lines show in result"</span>);
print (<span style="color: #e9b96e;">"List max printed = "</span> + listMax.toString());
<span style="color: #b4fa70;">return</span> <span style="color: #e9b96e;">"List max returned = "</span> + listMax.toString();
</pre>
</div>
<pre class="example">
In output mode, all printed lines show in result
List max printed = 3
</pre>
<p>
In this example, a table is correctly ignored with <code>:results output</code>, showing quoted results, as shown below:
</p>
<div class="org-src-container">
<pre class="src src-dart"><span style="color: #b4fa70;">var</span> <span style="color: #fcaf3e;">listMax</span> = [<span style="color: #e9b2e3;">1</span>,<span style="color: #e9b2e3;">2</span>,<span style="color: #e9b2e3;">3</span>].reduce(max);
print (<span style="color: #e9b96e;">"In output mode, all printed lines show in result"</span>);
print (<span style="color: #e9b96e;">"List max printed = "</span> + listMax.toString());
<span style="color: #b4fa70;">return</span> <span style="color: #e9b96e;">"List max returned = "</span> + listMax.toString();
</pre>
</div>
<pre class="example">
In output mode, all printed lines show in result
List max printed = 3
</pre>
<p>
<code>:results value raw</code> and <code>:results output raw</code> do not add any formatting to the result, and results appear as regular text, as shown below. Also note that because org mode joins lines of regular text, multiple printed lines of results are joined.
</p>
<p>
Result of <code>:results value raw</code>:
</p>
<div class="org-src-container">
<pre class="src src-dart"><span style="color: #b4fa70;">var</span> <span style="color: #fcaf3e;">listMax</span> = [<span style="color: #e9b2e3;">1</span>,<span style="color: #e9b2e3;">2</span>,<span style="color: #e9b2e3;">3</span>].reduce(max);
print (<span style="color: #e9b96e;">"In output mode, all printed lines show in result"</span>);
print (<span style="color: #e9b96e;">"List max printed = "</span> + listMax.toString());
<span style="color: #b4fa70;">return</span> <span style="color: #e9b96e;">"List max returned = "</span> + listMax.toString();
</pre>
</div>
<p>
List max returned = 3
List max returned = 3
</p>
<p>
Result of <code>:results output raw</code>
</p>
<div class="org-src-container">
<pre class="src src-dart"><span style="color: #b4fa70;">var</span> <span style="color: #fcaf3e;">listMax</span> = [<span style="color: #e9b2e3;">1</span>,<span style="color: #e9b2e3;">2</span>,<span style="color: #e9b2e3;">3</span>].reduce(max);
print (<span style="color: #e9b96e;">"In output mode, all printed lines show in result"</span>);
print (<span style="color: #e9b96e;">"List max printed = "</span> + listMax.toString());
<span style="color: #b4fa70;">return</span> <span style="color: #e9b96e;">"List max returned = "</span> + listMax.toString();
</pre>
</div>
<p>
In output mode, all printed lines show in result
List max printed = 3
In output mode, all printed lines show in result
List max printed = 3
</p>
</div>
</div>
<div id="outline-container-orga264977" class="outline-2">
<h2 id="orga264977"><span class="section-number-2">10.</span> Resolving Current Limitations</h2>
<div class="outline-text-2" id="text-10">
<p>
Below, a discussion for each numbered item in the Limitations section.
</p>
<ol class="org-ol">
<li>:var not passed to Dart. Should deal with this first, for Dart code blocks to play nice in org context, and accept, rather than just return, information.</li>
<li>Code that will work (and not work) inside the <code>#+begin_src and #end_src</code>.
<ul class="org-ul">
<li>Issues with solving this limitation: I want to add support for "any" Dart code soon, so functions, classes, and methods can be defined, then used in Org Babel Dart. Ideally, any valid Dart code that would run from the Dart command line can be pasted in the Org code sections and support the basic results modes. But this would make it impossible to support the :results value, because the Dart <code>main()</code> function does not return a value. Currently, ob-dart works around the :results value problem by wrapping the code and a combination pf running Zoned to ignore print(), and relying on return present in the org code, wraping it as print(). But to solve this in a general case, would require a deeper level of code manipulation either with emacs Semantic or Dart Analyser (<a href="https://github.com/dart-lang/sdk/tree/master/pkg/analyzer">https://github.com/dart-lang/sdk/tree/master/pkg/analyzer</a>) (to wrap a return as print or similar).</li>
<li>Suggested solutions: I think for now I arrived at supporting the following "Styles" - When Org Babel Dart code uses any of the styles below, it will work without adding further org mode special flags, headers, or markers.
<ul class="org-ul">
<li><b>Dart Style Top Level Functional</b>: This is the currently supported style.The <code>#+begin_src and #end_src</code> section can contain any code that can be inside a top-level Dart function without any class context from "above" the top level method. Some basic imports are added before the conde runs. Both ":results value" and ":results output" do work as expected.
<ul class="org-ul">
<li><p>
Valid examples (this works becaue functions can be nested, so this works wrapped in main):
</p>
<div class="org-src-container">
<pre class="src src-dart"><span style="color: #fce94f;">square</span>(<span style="color: #fcaf3e;">x</span>) {
<span style="color: #b4fa70;">return</span> x * x;
}
<span style="color: #b4fa70;">return</span> square(<span style="color: #e9b2e3;">2</span>);
</pre>
</div>
<pre class="example">
4
</pre>
<div class="org-src-container">
<pre class="src src-dart"><span style="color: #b4fa70;">var</span> <span style="color: #fcaf3e;">x</span> = <span style="color: #e9b2e3;">1.5</span>;
<span style="color: #b4fa70;">var</span> <span style="color: #fcaf3e;">y</span> = <span style="color: #e9b2e3;">2</span>;
<span style="color: #b4fa70;">return</span> max(pow(x, <span style="color: #e9b2e3;">4</span>), pow(y, <span style="color: #e9b2e3;">2</span>));
</pre>
</div>
<pre class="example">
5.0625
</pre></li>
<li><p>
Invalid Example (does not work because class cannot be nested in a function, and we are wrapping all code in main())
</p>
<div class="org-src-container">
<pre class="src src-dart"><span style="color: #73d216;">/* nesting class in a top-level function fails</span>
<span style="color: #73d216;">class C {</span>
<span style="color: #73d216;"> square(x) {</span>
<span style="color: #73d216;"> return x * x;</span>
<span style="color: #73d216;"> }</span>
<span style="color: #73d216;">}</span>
<span style="color: #73d216;">var c = new C();</span>
<span style="color: #73d216;">return c.square(2);</span>
<span style="color: #73d216;">*/</span>
</pre>
</div>
<pre class="example">
null
</pre></li>
</ul></li>
<li><b>Dart Style Aided Functional</b>: This will be extension of the mode above. It will allow to define classes above code, and use them in code. It will require user to enter a special marker in code; code above the marker will be evaluated on top level, and so classes and functions defined above the marker can be used below it. This will make the example from above valid. Both ":results value" and ":results output" will work as expected.
<ul class="org-ul">
<li><p>
Valid Example (does work because we split code on the marker, and only wrap the code below the "separator" string)
</p>
<div class="org-src-container">
<pre class="src src-dart"><span style="color: #73d216;">/* todo - uncomment once support added</span>
<span style="color: #73d216;">class C {</span>
<span style="color: #73d216;"> square(x) {</span>
<span style="color: #73d216;"> return x * x;</span>
<span style="color: #73d216;"> }</span>
<span style="color: #73d216;">}</span>
<span style="color: #73d216;">// Org-Dart-Functional</span>
<span style="color: #73d216;">var c = new C();</span>
<span style="color: #73d216;">return c.square(2);</span>
<span style="color: #73d216;">*/</span>
</pre>
</div></li>
<li>todo: provide an invalid example</li>
</ul></li>
<li><b>Dart Style Dart Program</b>: This will be different from either styles above. Any fully valid Dart program can be entered; it must include the main() method. Only ":results output" will be a valid option, ":results value" will cause an error..
<ul class="org-ul">
<li><p>
Valid Example:
</p>
<div class="org-src-container">
<pre class="src src-dart"><span style="color: #73d216;">/* todo - uncomment once support added</span>
<span style="color: #73d216;">class C {</span>
<span style="color: #73d216;"> square(x) {</span>
<span style="color: #73d216;"> return x * x;</span>
<span style="color: #73d216;"> }</span>
<span style="color: #73d216;">}</span>
<span style="color: #73d216;">main() {</span>
<span style="color: #73d216;"> var c = new C();</span>
<span style="color: #73d216;"> print( c.square(2) );</span>
<span style="color: #73d216;">}</span>
<span style="color: #73d216;">*/</span>
</pre>
</div>
<pre class="example">
null
</pre></li>
</ul></li>
</ul></li>
</ul></li>
</ol>
</div>
</div>
<div id="outline-container-orgfe14116" class="outline-2">
<h2 id="orgfe14116"><span class="section-number-2">11.</span> Security</h2>
<div class="outline-text-2" id="text-11">
<p>
Do not execute randomly downloaded code in Org Babel. Do not execute code you do not understand. There is no guarantee using insecure code such as "delete all" will not harm your data.. The issues would be similar to running the code as <code>dart some-file.dart</code>.
</p>
<p>
As a result, use at own risk. There are no guarantees running a random code safely - please read the org-mode babel documentation regarding security.
</p>
</div>
</div>
<div id="outline-container-org89886ff" class="outline-2">
<h2 id="org89886ff"><span class="section-number-2">12.</span> Todos (apart from resolving the limitations above)</h2>
<div class="outline-text-2" id="text-12">
<ol class="org-ol">
<li>Check language of ob-dart.el comments:</li>
<li>Add a babel directive :import if specified, the wrapper will not add any import packages. Imported packages must be in code (later, we may allow to specify and list in the :import directive)</li>
</ol>
</div>
</div>
<div id="outline-container-orgc5dff9b" class="outline-2">
<h2 id="orgc5dff9b"><span class="section-number-2">13.</span> Bugs</h2>
<div class="outline-text-2" id="text-13">
<ol class="org-ol">
<li><p>
:results value table does not allow space in the header name.
</p>
<div class="org-src-container">
<pre class="src src-dart" id="org064db7e"><span style="color: #b4fa70;">return</span> [