-
Notifications
You must be signed in to change notification settings - Fork 2
/
index.html
2554 lines (2002 loc) · 109 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
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta http-equiv="X-UA-Compatible" content="IE=edge" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>A guide to Kode basics</title>
<link rel="stylesheet" href="css/index.css?v=0.1.8" />
<script src="js/index.js?v=0.1.8"></script>
<link rel="shortcut icon" type="image/x-icon" href="favicon.ico" />
<link rel="apple-touch-icon" sizes="180x180" href="img/favicon/apple-touch-icon.png" />
<link rel="icon" type="image/png" sizes="32x32" href="img/favicon/favicon-32x32.png" />
<link rel="icon" type="image/png" sizes="16x16" href="img/favicon/favicon-16x16.png" />
<link rel="manifest" href="manifest.webmanifest" />
<link rel="mask-icon" href="img/favicon/safari-pinned-tab.svg" color="#101010" />
<meta name="msapplication-TileColor" content="#101010" />
<meta name="theme-color" content="#101010" />
<meta name="description" content="An in-depth guide to Kustom formula basics (mainly KLWP and KWGT)." />
<!-- open graph for embeds on social media etc. -->
<meta property="og:title" content="Kode Guide" />
<meta property="og:description" content="An in-depth guide to Kustom formula basics (mainly KLWP and KWGT)." />
<meta property="og:url" content="https://theothertored.github.io/kode-guide" />
<meta property="og:image" content="https://theothertored.github.io/kode-guide/img/og-img.png" />
<meta property="og:type" content="article" />
<meta property="og:article:author" content="Tored" />
</head>
<body>
<div id="toc" class="toc">
<button type="button" class="toc-fab" title="Expand/Collapse the table of contents">
<div class="top"></div>
<div class="mid"></div>
<div class="bot"></div>
</button>
<header>Table of contents</header>
<main></main>
<footer>
<div class="theme-switcher">
<label class="sec">Theme</label>
<div class="buttons">
<label class="radio dark" title="Use dark theme">
<input type="radio" name="theme" value="dark" />
<span>Dark</span>
</label>
<label class="radio" title="Select automatically based on system theme">
<input type="radio" name="theme" value="system" />
<span>System</span>
</label>
<label class="radio light" title="Use light theme">
<input type="radio" name="theme" value="light" />
<span>Light</span>
</label>
</div>
</div>
</footer>
</div>
<div class="toc-scrim"></div>
<main class="guide">
<h1>
<span class="nowrap">A guide to</span>
<span class="nowrap">Kode basics</span>
<div class="small">(by Tored)</div>
</h1>
<!--
<div class="theme-switcher">
<label>What theme would you like to read this guide in?</label>
<div class="buttons">
<label class="radio dark" title="Use dark theme">
<input type="radio" name="theme2" value="dark" />
<span>Dark</span>
</label>
<label class="radio" title="Select automatically based on system theme">
<input type="radio" name="theme2" value="system" />
<span>System</span>
</label>
<label class="radio light" title="Use light theme">
<input type="radio" name="theme2" value="light" />
<span>Light</span>
</label>
</div>
</div> -->
<h2 id="introduction">Introduction</h2>
<p>
What even is Kode? If you've used Kustom apps before, you probably are familiar with the formula editor window.
Everything you write in the Formula Editor field is Kode.
</p>
<div class="image-container">
<img src="img/intro-screenshot.png" alt="The formula editor window in KLWP." />
<label>The formula editor window in KLWP.</label>
</div>
<p>
By default, what you write in the formula editor is displayed as-is (plain text).
However, anything you put between dollar signs <span class="nowrap">(<code>$</code>)</span> will be evaluated.
</p>
<p>
Evaluation means that Kustom will take what you wrote, interpret it as a set of commands telling it what to do,
and then produce a result (output) that will then be displayed (printed) instead of the entire text between dollar signs.
</p>
<h3 id="guide-meta">Important notes regarding this guide</h3>
<p>
A quick note for the very start - experimenting and testing stuff for yourself is highly encouraged.
If you encounter something you don't get, try doing it in the editor and seeing how it works in practice.
</p>
<p>
If you want to test the examples for yourself:
</p>
<ul>
<li>
You can <strong>double-tap/double-click any example box</strong> to copy its contents to clipboard,
</li>
<li>
For readability, I won't use dollar signs where there's no need to combine Kode and normal text.
Don't forget to <strong>wrap anything you want evaluated in dollar signs <span class="nowrap">(<code>$</code>)</span></strong>.
</li>
</ul>
<p>
There is a light/dark theme switch available in the sidebar. By default, the guide uses your system's theme.
</p>
<p>
If you'd like to refer someone to a section of this guide:
</p>
<ul>
<li>Each section title is also a link to that section,</li>
<li>
<strong>Long press/right click</strong> the section title and then use "copy link address" to get a <strong>link that will open the guide on that section</strong>.
</li>
</ul>
<p id="sw-caching-available" class="no-display">
Because your browser supports service workers, this page will be available even if you visit it while offline.
</p>
<p id="pwa-install-prompt" class="no-display">
This guide is also a PWA that can be installed like an app on your device. You can install it from your browser's menu, or by click the button below:
</p>
<p id="pwa-install-button" class="no-display text-center">
<button type="button" class="btn">Install as an app</button>
</p>
<p>
With all that out of the way, let's talk about how Kustom transforms your Kode text into a result value.
</p>
<p>
Have fun!
</p>
<h2 id="values-and-operators">Values and operators</h2>
<h3 id="numbers-and-math">Numbers and math</h3>
<p>
Let's start with introducing basic Kode syntax elements with an example:
</p>
<div class="snippet first">
<label class="ex-no"></label>
<code><span class="hl hl-1">1</span> <span class="hl hl-2">+</span> <span class="hl hl-1">2</span></code>
<div class="note">
Tip: Double click or double tap any example to copy it.
For your convenience, copying this way automatically adds dollar signs around the formula. And there is a cool animation!
Try it out :)
</div>
</div>
<p>
This entire example is a mathematical expression, consisting of two <span class="hl hl-1">values</span> and one
<span class="hl hl-2">operator</span>.
We can write longer expressions by adding more <span class="hl hl-1">numbers</span> and <span class="hl hl-2">operators</span>:
</p>
<div class="snippet">
<label class="ex-no"></label>
<code>
<span class="hl hl-1">6</span>
<span class="hl hl-2">+</span>
<span class="hl hl-1">5</span>
<span class="hl hl-2">-</span>
<span class="hl hl-1">4</span>
<span class="hl hl-2">*</span>
<span class="hl hl-1">3</span>
<span class="hl hl-2">/</span>
<span class="hl hl-1">2</span>
<span class="hl hl-2">^</span>
<span class="hl hl-1">1</span>
</code>
</div>
<p>
The table below shows all mathematical operators available in Kustom:
</p>
<div class="table-container">
<table id="math-symbol-table">
<thead>
<tr>
<th>Symbol</th>
<th>Name</th>
<th>Example</th>
<th>Output</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>+</code></td>
<td>Addition</td>
<td><code>3 + 2</code></td>
<td><code>5</code></td>
</tr>
<tr>
<td><code>-</code></td>
<td>Subtraction</td>
<td><code>3 - 2</code></td>
<td><code>1</code></td>
</tr>
<tr>
<td><code>*</code></td>
<td>Multiplication</td>
<td><code>3 * 2</code></td>
<td><code>6</code></td>
</tr>
<tr>
<td><code>/</code></td>
<td>Division</td>
<td><code>3 / 2</code></td>
<td><code>1.5</code></td>
</tr>
<tr>
<td><code>%</code></td>
<td>Modulo</td>
<td><code>3 % 2</code></td>
<td><code>1</code></td>
</tr>
<tr>
<td><code>^</code></td>
<td>Exponentiation</td>
<td><code>3 ^ 2</code></td>
<td><code>9</code></td>
</tr>
</tbody>
</table>
</div>
<p>
The order of operations in Kustom follows the standard mathematical order of operations.
</p>
<p>
In this example, <code>2 ^ 1</code> gets evaluated first. Then the output of that evaluation gets put in
place
of <code>2 ^ 1</code>, and the formula is evaluated further:
</p>
<div class="snippet">
<label class="ex-no subex"></label>
<div class="step">
<code>6 + 5 - 4 * 3 / <span class="hl hl-before">2 ^ 1</span></code>
<div class="arrow"></div>
<code>6 + 5 - 4 * 3 / <span class="hl hl-after">2</span></code>
</div>
</div>
<p>
Next there are two operators of equal "weight", so the leftmost one is evaluated first:
</p>
<div class="snippet">
<label class="ex-no subex"></label>
<div class="step">
<code>6 + 5 - <span class="hl hl-before">4 * 3</span> / 2</code>
<div class="arrow"></div>
<code>6 + 5 - <span class="hl hl-after">12</span> / 2</code>
</div>
</div>
<p>
Then division:
</p>
<div class="snippet">
<label class="ex-no subex"></label>
<div class="step">
<code>6 + 5 - <span class="hl hl-before">12 / 2</span></code>
<div class="arrow"></div>
<code>6 + 5 - <span class="hl hl-after">6</span></code>
</div>
</div>
<p>
Finally, the two remaining operators again get evaluated from left to right:
</p>
<div class="snippet">
<label class="ex-no subex"></label>
<div class="step">
<code><span class="hl hl-before">6 + 5</span> - 6</code>
<div class="arrow"></div>
<code><span class="hl hl-after">11</span> - 6</code>
</div>
<label class="ex-no subex"></label>
<div class="step">
<code><span class="hl hl-before">11 - 6</span></code>
<div class="arrow"></div>
<code><span class="hl hl-after">5</span></code>
</div>
</div>
<p>
And we arrive at an output:
</p>
<div class="snippet">
<label class="output"></label>
<code>5</code>
</div>
<p>
Note that for certain calculations the output might not be 100% accurate due to rounding errors - a number
inside your phone/computer can only store so many decimal places.
</p>
<p>
You can influence the order in which operators are evaluated using parentheses:
</p>
<div class="snippet">
<label class="ex-no"></label>
<code>3 * (2 + 1)</code>
</div>
<p>
Because of the parentheses, addition gets evaluated before multiplication:
</p>
<div class="snippet">
<label class="ex-no subex"></label>
<div class="step">
<code>3 * <span class="hl hl-before">(2 + 1)</span></code>
<div class="arrow"></div>
<code>3 * <span class="hl hl-after">3</span></code>
</div>
<label class="ex-no subex"></label>
<div class="step">
<code><span class="hl hl-before">3 * 3</span></code>
<div class="arrow"></div>
<code><span class="hl hl-after">9</span></code>
</div>
<label class="output"></label>
<code>9</code>
</div>
<h3 id="strings">Strings (text values)</h3>
<h4 id="quoted-strings">Quoted strings</h4>
<p>
Text values, often referred to as strings, are used very, very frequently.
To add one to your formula, wrap some text in quotation marks ("), which I'll also refer to as doublequotes.
The quotation marks won't be part of the output.
</p>
<div class="snippet">
<label class="ex-no"></label>
<code><span class="hl hl-1">"I am a quoted string"</span></code>
<label class="output"></label>
<code><span class="hl hl-1">I am a quoted string</span></code>
</div>
<p>
Strings have one operator that uses the same symbol as addition: <code>+</code> (concatenation).
It joins two strings together:
</p>
<div class="snippet">
<label class="ex-no"></label>
<code>
<span class="hl hl-1">"abc"</span>
<span>+</span>
<span class="hl hl-2">"def"</span>
</code>
<label class="output"></label>
<code><span class="hl hl-1">abc</span><span class="hl hl-2">def</span></code>
</div>
<p>
Expressions inside quoted strings are not evaluated:
</p>
<div class="snippet">
<label class="ex-no"></label>
<code><span class="hl hl-1">"2 + 1"</span></code>
<label class="output"></label>
<code><span class="hl hl-1">2 + 1</span></code>
</div>
<p>
A common misconception I've seen is trying to use <code>$</code> to evaluate a part of a string.
Instead, calculate the result separately and concatenate it with the other parts of the string.
</p>
<div class="snippet">
<label class="ex-no subex first">
<span class="error">incorrect, no evaluation will happen.</span>
</label>
<code><span class="hl hl-1">"2 + 2 is $2 + 2$!"</span></code>
<label class="output"></label>
<code><span class="hl hl-1">2 + 2 is $2 + 2$!</span></code>
</div>
<div class="snippet">
<label class="ex-no subex">
<span class="success">
corrrect, note the parentheses
</span>
</label>
<code>
<span class="hl hl-1">"2 + 2 is "</span>
<span>+</span>
<span class="hl hl-2">(2 + 2)</span>
<span>+</span>
<span class="hl hl-3">"!"</span>
</code>
<label class="output"></label>
<code><span class="hl hl-1">2 + 2 is </span><span class="hl hl-2">4</span><span class="hl hl-3">!</span></code>
</div>
<h4 id="quoteless-strings">Quoteless strings</h4>
<p>
If you add text to a formula without using doublequotes, Kustom will interpret it as text:
</p>
<div class="snippet">
<label class="ex-no"></label>
<code><span class="hl hl-1">I am a quoteless string</span></code>
<label class="output"></label>
<code><span class="hl hl-1">I am a quoteless string</span></code>
</div>
<p>
Quoteless strings cannot contain special characters, like operator symbols, dollar signs or parentheses:
</p>
<div class="snippet">
<label class="ex-no subex first">
<span class="error">
incorrect, the second <code>$</code> will be treated as the end of the Kode part, making <code>1000</code> plain text and the last <code>$</code> an unclosed evaluated part.
</span>
</label>
<code class="no-dollars"><span class="hl hl-false strong">$</span><span class="hl hl-false">Please give me </span><span class="hl hl-false strong">$</span>1000$</code>
</div>
<p>
In those cases, quoted strings should be used:
</p>
<div class="snippet">
<label class="ex-no subex">
<span class="success">
correct, the $ is treated as part of the string
</span>
</label>
<code><span class="hl hl-1">"Please give me $1000"</span></code>
</div>
<p>
They can contain whitespace (like spaces or even new line characters), but any whitespace at the beginning or end will be trimmed out:
</p>
<div class="snippet">
<label class="ex-no"></label>
<code>
<span>first</span><span class="hl hl-1"> </span><span>string</span><span class="hl hl-2"> </span><span>+</span><span class="hl hl-2"> </span><span>second</span><span class="hl hl-1"> </span><span>string</span>
</code>
<label class="output"></label>
<code><span>first</span><span class="hl hl-1"> </span><span>stringsecond</span><span class="hl hl-1"> </span><span>string</span></code>
</div>
<p>
Notice that the <span class="hl hl-2">spaces around the + operator</span> <span>are not present in the output, but the</span> <span class="hl hl-1">spaces inside the quoteless strings</span> are preserved.
</p>
<p>
If you are unsure which type of string to use, I'd recommend only using quoteless strings when the text you're writing is a constant value Kustom expects,
like <code>ALWAYS</code> or <code>NEVER</code> for visibility, or when it's a function mode like <code>low</code> or <code>up</code> (more on those later).
</p>
<h4 id="operator-string-mode">The default string mode of operators</h4>
<p>
If you try using mathematical operators on text, you might notice something weird happening:
</p>
<div class="snippet">
<label class="ex-no"></label>
<code>"a" * "b"</code>
<label class="output"></label>
<code>a*b</code>
</div>
<p>
A very similar result occurs with most operators in Kode, except for ones specifically made to work differently with strings.
Its main purpose is to allow strings containing operator characters to remain without doublequotes.
You might have encountered it (and not noticed) when writing things like icon names:
</p>
<div class="snippet">
<label class="ex-no"></label>
<code><span class="hl hl-1">weather</span><span class="hl hl-2">-</span><span class="hl hl-1">sunny</span></code>
<label class="output"></label>
<code>weather-sunny</code>
</div>
<p>
Notice that the example above is two <span class="hl hl-1">quoteless strings</span> and the <span class="hl hl-2">subtraction operator</span>, and not one continuous long string.
This becomes far more obvious if you choose to quote the strings and add whitespace, which does not change the output:
</p>
<div class="snippet">
<label class="ex-no subex"></label>
<code><span class="hl hl-1">"weather"</span> <span class="hl hl-2">-</span> <span class="hl hl-1">"sunny"</span></code>
<label class="output"></label>
<code>weather-sunny</code>
</div>
<p>
This behavior is present for all operators, except ones listed in the table below:
</p>
<div class="table-container">
<table id="string-mode-table">
<thead>
<tr>
<th>Operator</th>
<th>String mode</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>+</code></td>
<td>Concatenation</td>
</tr>
<tr>
<td><code>=</code></td>
<td>Check if two strings are the same</td>
</tr>
<tr>
<td><code>!=</code></td>
<td>Check if two strings are different</td>
</tr>
<tr>
<td><code>~=</code></td>
<td>Check if a string contains another string/regex test</td>
</tr>
</tbody>
</table>
</div>
<h4 id="note-on-combining-strings-and-numbers">Note on Combining strings and numbers</h4>
<p>
Kustom converts value types from one to another on the fly.
Because of that, any string that can be parsed as a number (decimals like "<code>5.23</code>" count as numbers too!) will be converted to a number when using the <code>+</code> operator (and other operators too), as well as before being passed to (most) functions (more on those later).
That parsed number will be used instead of the original string.
</p>
<div class="snippet">
<label class="ex-no"></label>
<code>" 00002.0000 " + abc</code>
<label class="output"></label>
<code>2abc</code>
</div>
<p>
This can lead to problems when trying to preserve things like leading zeroes or a trailing decimal point, or trying to concatenate numbers instead of adding them.
A workaround for this issue is presented in the <a href="#concatenating-numbers">"Additional tips & tricks"</a> section at the end of this guide.
</p>
<h2 id="functions">Functions</h2>
<h3 id="functions-intro">Introduction to functions</h3>
<p>
Functions are the main part of Kode.
Some of them can be used to get information, like the current time, weather, system information, calendar events and much more.
Other functions can be used to perform mathematical calculations or transform text.
Asking the function to do something is called "calling" the function. The basic structure of a function call is as follows:
</p>
<ol>
<li>
The <span class="hl hl-1">name</span> of the function to be called.<br />
In Kode, functions have two letter names that are usually short for the full name of the function.
For example, <code>df</code> is short for "Date Format", while <code>tc</code> is short for "Text Converter".
</li>
<li>
<code class="hl hl-2">(</code> (an opening parenthesis),
</li>
<li>
<span class="hl hl-3">Arguments</span> <span>separated by</span> <span class="hl hl-2">commas</span> <span class="nowrap">(<code class="hl hl-2">,</code>)</span>
</li>
<li>
<code class="hl hl-2">)</code> (a closing parenthesis),
</li>
</ol>
<div class="snippet">
<label class="ex-no subex first"></label>
<code><span class="hl hl-1">tc</span><span class="hl hl-2">(</span><span class="hl hl-3">low</span><span class="hl hl-2">,</span> <span class="hl hl-3">"Make Me Lowercase"</span><span class="hl hl-2">)</span></code>
</div>
<p>
A function can also only take one argument:
</p>
<div class="snippet">
<label class="ex-no subex"></label>
<code><span class="hl hl-1">ai</span><span class="hl hl-2">(</span><span class="hl hl-3">isday</span><span class="hl hl-2">)</span></code>
</div>
<p>
Or not take any:
</p>
<div class="snippet">
<label class="ex-no subex"></label>
<code><span class="hl hl-1">dp</span><span class="hl hl-2">()</span></code>
</div>
<p>
Arguments can be expressions with values and operators or other function calls - anything that returns a value.
Before a function is evaluated, all its arguments have to be evaluated.
Consider this example of calling <code>tc()</code> (Text Converter), with one of the arguments being a concatenation of two strings:
</p>
<div class="snippet">
<label class="ex-no"></label>
<code>tc(low, "Make Me " + "Lowercase")</code>
</div>
<p>
In this example, the concatenation gets evaluated first:
</p>
<div class="snippet">
<label class="ex-no subex"></label>
<div class="step">
<code>tc(low, <span class="hl hl-before">"Make Me " + "Lowercase"</span>)</code>
<div class="arrow"></div>
<code>tc(low, <span class="hl hl-after">"Make Me Lowercase"</span>)</code>
</div>
</div>
<p>
Now, the function can take both arguments and turn them into a result. In this case, the first argument is a mode string, which tells the function what to do with the other argument.
The <code>low</code> mode of <code>tc()</code> converts the string given in the second argument to lowercase:
</p>
<div class="snippet">
<label class="ex-no subex"></label>
<div class="step">
<code><span class="hl hl-before">tc(low, "Make Me Lowercase")</span></code>
<div class="arrow"></div>
<code><span class="hl hl-after">"make me lowercase"</span></code>
</div>
<label class="output"></label>
<code>make me lowercase </code>
</div>
<p>
If we instead changed the mode argument to <code>up</code>, <code>tc()</code> would instead convert the string to uppercase:
</p>
<div class="snippet">
<label class="ex-no subex"></label>
<div class="step">
<code><span class="hl hl-before">tc(up, "Make Me Lowercase")</span></code>
<div class="arrow"></div>
<code><span class="hl hl-after">"MAKE ME LOWERCASE"</span></code>
</div>
<label class="output"></label>
<code>MAKE ME LOWERCASE </code>
</div>
<p>
You can also use another function call as an argument. Because arguments need to be evaluated before the function call, these calls will be evaluated from the inside out.
In this example, <code>mi()</code> stands for Music Info, and mode <code>title</code> returns the title of the currently playing music.
</p>
<div class="snippet">
<label class="ex-no"></label>
<code>tc(low, mi(title))</code>
</div>
<p>
The "deeper" function gets evaluated first:
</p>
<div class="snippet">
<label class="ex-no subex"></label>
<div class="step">
<code>tc(low, <span class="hl hl-before">mi(title)</span>)</code>
<div class="arrow"></div>
<code>tc(low, <span class="hl hl-after">"Music Title"</span>)</code>
</div>
</div>
<p>
Now the <code>tc()</code> call can be evaluated:
</p>
<div class="snippet">
<label class="ex-no subex"></label>
<div class="step">
<code><span class="hl hl-before">tc(low, "Music Title")</span></code>
<div class="arrow"></div>
<code><span class="hl hl-after">"music title"</span></code>
</div>
<label class="output"></label>
<code>music title</code>
</div>
<p>
You can also combine function calls with operators:
</p>
<div class="snippet">
<label class="ex-no"></label>
<code>tc(low, mi(artist) + " - " + mi(title))</code>
</div>
<p>
Before a <code>+</code> (concatenation) operation can be evaluated, both its sides need to be evaluated.
This means that in this example, <code>mi(artist)</code> (returns the artist behind currently playing music)
will get evaluated first:
</p>
<div class="snippet">
<label class="ex-no subex"></label>
<div class="step">
<code>tc(low, <span class="hl hl-before">mi(artist)</span> + " - " + mi(title))</code>
<div class="arrow"></div>
<code>tc(low, <span class="hl hl-after">"Artist Name"</span> + " - " + mi(title))</code>
</div>
</div>
<p>
After that, the first concatenation can be evaluated:
</p>
<div class="snippet">
<label class="ex-no subex"></label>
<div class="step">
<code>tc(low, <span class="hl hl-before">"Artist Name" + " - "</span> + mi(title))</code>
<div class="arrow"></div>
<code>tc(low, <span class="hl hl-after">"Artist Name - "</span> + mi(title))</code>
</div>
</div>
<p>
Then <code>mi(title)</code> and the second concatenation:
</p>
<div class="snippet">
<label class="ex-no subex"></label>
<div class="step">
<code>tc(low, "Artist Name - " + <span class="hl hl-before">mi(title)</span>)</code>
<div class="arrow"></div>
<code>tc(low, "Artist Name - " + <span class="hl hl-after">"Music Title"</span>)</code>
</div>
<label class="ex-no subex"></label>
<div class="step">
<code>tc(low, <span class="hl hl-before">"Artist Name - " + "Music Title"</span>)</code>
<div class="arrow"></div>
<code>tc(low, <span class="hl hl-after">"Artist Name - Music Title"</span>)</code>
</div>
</div>
<p>
Finally, the <code>tc()</code> call can get evaluated:
</p>
<div class="snippet">
<label class="ex-no subex"></label>
<div class="step">
<code><span class="hl hl-before">tc(low, "Artist Name - Music Title")</span></code>
<div class="arrow"></div>
<code><span class="hl hl-after">"artist name - music title"</span></code>
</div>
<label class="output"></label>
<code>artist name - music title</code>
</div>
<p>
Keep in mind that all the problems you'd see with strings containing numbers also apply to function return
values.
If you try to concatenate a function's result that is a number and a string number, you'll get addition
instead.
</p>
<h4 id="note-on-regex">Note on Regex (regular expressions)</h3>
<p>
While Regex/regular expressions might sound scary if you haven't used them before, they are a very powerful tool that is worth learning.
They are not used only in Kustom, you can make use of them in other tools and programming languages for advanced text searching and replacing.
</p>
<p>
A regular expression is a string consisting of regular characters and special characters that can match different characters or multiple characters, called a <span class="hl hl-2">pattern</span>.
Regular expressions are used to search for a <span class="hl hl-2">pattern</span> <span>in a</span>
<hl class="hl hl-1">string</hl><span>, and often also to replace whatever it matches with</span> <span class="hl hl-3">something else</span>.
</p>
<p>
In Kustom, <code>tc()</code> has a mode that allows you to make use of regular expressions - <code>tc(reg)</code>. This function accepts 3 arguments after the mode:
</p>
<div class="snippet">
<label class="ex-no"></label>
<code>tc(reg, <span class="hl hl-1">string</span>, <span class="hl hl-2">pattern</span>, <span class="hl hl-3">replacement</span>)</code>
</div>
<p>
If you don't want to learn regex, please just note that you can use <code>tc(reg)</code> to simply replace all occurences of a string with another string:
</p>
<div class="snippet">
<label class="ex-no"></label>
<code>tc(reg, <span class="hl hl-1">"I like trains"</span>, <span class="hl hl-2">"like"</span>, <span class="hl hl-3">"don't like"</span>)</code>
<label class="output"></label>
<code>I don't like trains</code>
</div>
<p>
Here is an example of using a pattern to remove everything after a dash by replacing it with an empty string:
</p>
<div class="snippet">
<label class="ex-no"></label>
<code>tc(reg, <span class="hl hl-1">"This part is wanted - this part isn't"</span>, "<span class="hl hl-2"> -.*</span>", <span class="hl hl-3">""</span>)</code>
<label class="output"></label>
<code>This part is wanted</code>
</div>
<p>
Here is what the <span class="hl hl-2">pattern</span> does:
</p>
<ul>
<li><code><pre> -</pre></code> matches a space and a dash,</li>
<li><code>.*</code> matches any character <span class="nowrap">(<code>.</code>)</span> 0 or more times <span class="nowrap">(<code>*</code>)</span></li>
</ul>
<p>
Note that in the <span class="hl hl-3">replacement string</span>, <code>$0</code> can be used to refer to the entire match, and <code>$1</code>,
<code>$2</code>, …, <code>$9</code> to groups 1-9 of the match.
</p>
<p>
I won't go in depth about regex here, as it'd be repeating work already done better elsewhere.
I'll instead provide you some links if you'd like to learn, but don't know where to begin:
</p>
<ul>
<li>
<a href="https://regexone.com/">RegexOne</a> can help you master the basics by giving you exercises as you go,
</li>
<li>
<a href="https://regex101.com/">Regex101</a> is a great tool to build patterns with, letting you test on any text you want, as well as highlighting what your pattern selects and why,
</li>
<li>
<a href="https://regexr.com/">Regexr</a> is a similar tool, but with a different user interface,
</li>
<li>
<a href="https://www.autoregex.xyz/">AutoRegex</a> is a tool that attempts to translate english into a regex pattern. It is not 100% accurate all the time, but it might help you learn.
</li>
</ul>
<p>
</p>
<h3 id="doing-a-or-b-depending-on-x">Doing A or B depending on X</h3>
<h4 id="boolean-intro">Introduction to boolean values</h4>
<p>
A boolean value is either <span class="hl hl-true">true</span> (represented as <code class="hl-true">1</code> in Kustom)
or <span class="hl hl-false">false</span> (represented as <code class="hl-false">0</code> in Kustom).
</p>
<p>
In most cases, we'll obtain a boolean value from a function like <code>ai(isday)</code>
(<code class="hl-true">1</code> when it is day, <code class="hl-false">0</code> otherwise)
or <code>si(locked)</code> (<code class="hl-true">1</code> when the phone is locked, <code class="hl-false">0</code> otherwise),
or, alternatively, from comparing two values using one of the comparison operators listed below:
</p>
<div class="table-container">
<table id="comparison-operator-table">
<thead>
<tr>
<th>Symbol</th>
<th>Name</th>
<th>Returns <code>1</code></th>
<th>Returns <code>0</code></th>
</tr>
</thead>