ahk 0.1.1

The ahk language: a lexer, an AST, a parser and an interpreter for AutoHotkey-style scripts
Documentation
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
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
//! The `Array` class.
//!
//! An array is a row of values. The places count from one, the way
//! AutoHotkey counts them, and a place can be left without a value of
//! its own.

use alloc::collections::BTreeMap;
use alloc::format;
use alloc::rc::Rc;
use alloc::string::{String, ToString};
use alloc::vec;
use alloc::vec::Vec;
use core::cell::RefCell;

use crate::classes::enumerator;
use crate::runtime::{Object, Runtime, RuntimeError, RuntimeFailure, Value, put};

/// The key the state of an array lives under.
///
/// The name is not one a script can write: the name of a property in a
/// script is always an identifier, and this one is not. It is not a
/// property of the array either, so it stays out of the answers about
/// the properties.
const STATE: &str = "array state";

/// The class of the object that carries the state of an array.
const STATE_CLASS: &str = "array-state";

/// The properties an array owns.
const PROPERTIES: [&str; 3] = ["length", "capacity", "__item"];

/// The methods an array has: the ones of the class, and the ones every
/// object has.
const METHODS: [&str; 19] = [
    "push",
    "pop",
    "insertat",
    "removeat",
    "delete",
    "get",
    "has",
    "clone",
    "__new",
    "__enum",
    "ownprops",
    "hasownprop",
    "defineprop",
    "deleteprop",
    "getownpropdesc",
    "hasprop",
    "hasmethod",
    "getmethod",
    "hasbase",
];

/// The names an array answers: its properties and its methods.
pub(crate) fn names() -> Vec<&'static str> {
    PROPERTIES.iter().chain(METHODS.iter()).copied().collect()
}

/// The object an `Array` makes.
///
/// The values of the constructor go in, the way `Push` puts them in.
pub(crate) fn construct(
    arguments: &[Value],
    _rt: &mut Runtime,
    _line: u32,
) -> Result<Value, RuntimeFailure> {
    let array = crate::classes::object_with("array", vec![(STATE, new_state(Vec::new(), 0))]);
    for value in arguments {
        push_value(&array, value.clone());
    }
    Ok(array)
}

/// The object the literal of an array makes.
///
/// Measured on the binary of v2.0.19 on 2026-11-01: the literal may have a
/// hole, and the place of the hole is a place of the array that has no
/// value of its own.
pub(crate) fn construct_with_holes(
    values: &[Option<Value>],
    _rt: &mut Runtime,
    _line: u32,
) -> Value {
    let array = crate::classes::object_with("array", vec![(STATE, new_state(Vec::new(), 0))]);
    for value in values {
        push_element(&array, value.clone());
    }
    array
}

/// A method of an `Array`.
pub(crate) fn call(
    method: &str,
    this: &Value,
    arguments: &[Value],
    rt: &mut Runtime,
    line: u32,
) -> Option<Result<Value, RuntimeFailure>> {
    let method = method.to_lowercase();
    let failure = |message: &str| {
        Some(Err(RuntimeFailure::Error(RuntimeError {
            message: message.to_string(),
            line,
        })))
    };
    // The failure of a member that complains about a value carries the
    // value in the `Extra` of the error.
    let failure_with = |message: &str, extra: &str| {
        Some(Err(crate::classes::the_failure_with(message, extra, line)))
    };
    // The place of an array is a parameter of the methods that take one,
    // and a place that is not there is an invalid parameter.
    let invalid_place = |method: &str, index: i64| {
        failure_with(
            &format!(
                "Parameter #1 of {} is invalid.",
                crate::classes::the_name_of("array", method)
            ),
            &index.to_string(),
        )
    };
    match method.as_str() {
        // `Push` and `__New` are the same thing in v2: both put the values
        // at the end, and both answer the array, so that the calls can be
        // chained.
        "push" | "__new" => {
            for value in arguments {
                push_value(this, value.clone());
            }
            Some(Ok(this.clone()))
        }
        "pop" => {
            let Some(state) = state(this) else {
                return failure("Invalid index.");
            };
            let mut state = state.borrow_mut();
            let mut items = items(&state);
            let Some(last) = items.pop() else {
                return failure("Array is empty.");
            };
            set_items(&mut state, items);
            Some(Ok(
                element_value(&last).unwrap_or(Value::Text(String::new()))
            ))
        }
        "insert" if rt.dialect().the_array_has_the_methods_of_the_v1() => {
            // Measured on the binary of AutoHotkey v1.1.37.02 on 2026-11-04:
            // the `Insert` of the v1 takes the index and the value: the
            // `a.Insert(1, 9)` puts the nine at the first place. A value on
            // its own goes to the end: the `a.Insert(9)` puts the nine at
            // the end of the array.
            let Some(state) = state(this) else {
                return failure("Invalid index.");
            };
            let mut state = state.borrow_mut();
            let mut items = items(&state);
            let length = items.len() as i64;
            if arguments.len() < 2 {
                if let Some(value) = arguments.first() {
                    items.push(element(Some(value.clone())));
                }
                set_items(&mut state, items);
                return Some(Ok(Value::Text(String::new())));
            }
            let index = match rt.integer(&arguments[0], line) {
                Ok(number) => number,
                Err(failure) => return Some(Err(failure)),
            };
            let Some(place) = insert_place(index, length) else {
                return invalid_place("Insert", index);
            };
            for (offset, value) in arguments.iter().skip(1).enumerate() {
                items.insert(place + offset, element(Some(value.clone())));
            }
            set_items(&mut state, items);
            Some(Ok(Value::Text(String::new())))
        }
        "remove" if rt.dialect().the_array_has_the_methods_of_the_v1() => {
            // Measured on the binary of AutoHotkey v1.1.37.02 on 2026-11-04:
            // the `Remove` of the v1 takes the index: the `a.Remove(1)`
            // takes the first one away. Without an index the last one goes
            // away: the `a.Remove()` is the `a.Pop()`.
            let Some(state) = state(this) else {
                return failure("Invalid index.");
            };
            let mut state = state.borrow_mut();
            let mut items = items(&state);
            let length = items.len() as i64;
            let Some(index) = arguments.first() else {
                let Some(last) = items.pop() else {
                    return failure("Array is empty.");
                };
                set_items(&mut state, items);
                return Some(Ok(
                    element_value(&last).unwrap_or(Value::Text(String::new()))
                ));
            };
            let index = match rt.integer(index, line) {
                Ok(number) => number,
                Err(failure) => return Some(Err(failure)),
            };
            let Some(place) = place(index, length) else {
                return invalid_place("Remove", index);
            };
            let removed = items.remove(place);
            set_items(&mut state, items);
            Some(Ok(
                element_value(&removed).unwrap_or(Value::Text(String::new()))
            ))
        }
        "insertat" => {
            let Some(index) = arguments.first() else {
                return failure("Too few parameters passed to function.");
            };
            // There is something to insert: an index on its own inserts
            // nothing.
            if arguments.len() < 2 {
                return failure("Too few parameters passed to function.");
            }
            let index = match rt.integer(index, line) {
                Ok(number) => number,
                Err(failure) => return Some(Err(failure)),
            };
            let Some(state) = state(this) else {
                return failure("Invalid index.");
            };
            let mut state = state.borrow_mut();
            let mut items = items(&state);
            let length = items.len() as i64;
            // A zero is the end of the array, and a negative index counts
            // from the end.
            let Some(place) = insert_place(index, length) else {
                return invalid_place("InsertAt", index);
            };
            for (offset, value) in arguments.iter().skip(1).enumerate() {
                items.insert(place + offset, element(Some(value.clone())));
            }
            set_items(&mut state, items);
            Some(Ok(Value::Text(String::new())))
        }
        "removeat" => {
            let Some(index) = arguments.first() else {
                return failure("Too few parameters passed to function.");
            };
            let index = match rt.integer(index, line) {
                Ok(number) => number,
                Err(failure) => return Some(Err(failure)),
            };
            let Some(state) = state(this) else {
                return failure("Invalid index.");
            };
            let mut state = state.borrow_mut();
            let mut items = items(&state);
            let length = items.len() as i64;
            let Some(place) = place(index, length) else {
                return invalid_place("RemoveAt", index);
            };
            match arguments.get(1) {
                // One place: the value that was there is the answer.
                None => {
                    let removed = items.remove(place);
                    set_items(&mut state, items);
                    Some(Ok(
                        element_value(&removed).unwrap_or(Value::Text(String::new()))
                    ))
                }
                // A range: the answer is the number of the values that were
                // in it.
                Some(count) => {
                    let count = match rt.integer(count, line) {
                        Ok(number) => number,
                        Err(failure) => return Some(Err(failure)),
                    };
                    let mut removed = 0;
                    for _ in 0..count.max(1) {
                        if place >= items.len() {
                            break;
                        }
                        if element_value(&items[place]).is_some() {
                            removed += 1;
                        }
                        items.remove(place);
                    }
                    set_items(&mut state, items);
                    Some(Ok(Value::Int(removed)))
                }
            }
        }
        "delete" => {
            let Some(index) = arguments.first() else {
                return failure("Too few parameters passed to function.");
            };
            let index = match rt.integer(index, line) {
                Ok(number) => number,
                Err(failure) => return Some(Err(failure)),
            };
            let Some(state) = state(this) else {
                return failure("Invalid index.");
            };
            let mut state = state.borrow_mut();
            let mut items = items(&state);
            let length = items.len() as i64;
            let Some(place) = place(index, length) else {
                return invalid_place("Delete", index);
            };
            // The place stays, and it has no value of its own any more.
            let removed = element_value(&items[place]).unwrap_or(Value::Text(String::new()));
            items[place] = element(None);
            set_items(&mut state, items);
            Some(Ok(removed))
        }
        "get" => {
            let Some(index) = arguments.first() else {
                return failure("Too few parameters passed to function.");
            };
            let index = match rt.integer(index, line) {
                Ok(number) => number,
                Err(failure) => return Some(Err(failure)),
            };
            let Some(state) = state(this) else {
                return failure("Invalid index.");
            };
            let state = state.borrow();
            let items = items(&state);
            let length = items.len() as i64;
            let Some(place) = place(index, length) else {
                return failure_with("Invalid index.", &index.to_string());
            };
            match element_value(&items[place]) {
                Some(value) => Some(Ok(value)),
                // The default of the call comes first, and then the default
                // the script gave to the array.
                None => match arguments.get(1) {
                    Some(default) => Some(Ok(default.clone())),
                    None => match default_property(this) {
                        Some(default) => Some(Ok(default)),
                        None => failure("Item has no value."),
                    },
                },
            }
        }
        "has" => {
            let Some(index) = arguments.first() else {
                return failure("Too few parameters passed to function.");
            };
            let index = match rt.integer(index, line) {
                Ok(number) => number,
                Err(failure) => return Some(Err(failure)),
            };
            let Some(state) = state(this) else {
                return Some(Ok(Value::Int(0)));
            };
            let state = state.borrow();
            let items = items(&state);
            let length = items.len() as i64;
            // A place that is not there has no value, and that is not an
            // error: the question is answered.
            let found = match place(index, length) {
                Some(place) => element_value(&items[place]).is_some(),
                None => false,
            };
            Some(Ok(Value::Int(found as i64)))
        }
        "clone" => Some(Ok(clone(this))),
        // The enumeration of an array is the values, in the order of their
        // places. Measured on the binary of v2.0.19 on 2026-10-31: the
        // enumeration of v2 is an enumerator, and it gives the value when
        // the caller wants one value and the place and the value when the
        // caller wants two. The number of the variables is not carried by
        // the enumerator: it is the call that says how many it wants.
        "__enum" => {
            let Some(state) = state(this) else {
                return Some(Ok(enumerator::make(
                    Vec::new(),
                    enumerator::Alone::TheValue,
                )));
            };
            let state = state.borrow();
            let pairs: Vec<(Value, Value)> = items(&state)
                .iter()
                .enumerate()
                .map(|(index, item)| {
                    // Measured on the binary of v2.0.19 on 2026-11-01: the
                    // place that has no value of its own is a turn of the
                    // enumeration too, and the turn has no value of its own:
                    // the variable of the loop is left without one.
                    let value = element_value(item).unwrap_or_else(|| element(None));
                    (Value::Int(index as i64 + 1), value)
                })
                .collect();
            Some(Ok(enumerator::make(pairs, enumerator::Alone::TheValue)))
        }
        _ => base_method(&method, this, arguments, rt, line),
    }
}

/// Write an item of an array: `array[index] := value`.
///
/// The index must be an item that is there: an array grows with `Push`
/// and with `InsertAt`, and not with an assignment.
pub(crate) fn set_item(
    key: &Value,
    this: &Value,
    value: Value,
    rt: &mut Runtime,
    line: u32,
) -> Option<Result<(), RuntimeFailure>> {
    // The place of an item is a number: a value that is not one is not a
    // place at all, and v2 says that the index is invalid.
    let Some(index) = rt.the_place_of_an_item(key) else {
        // Measured on the binary of AutoHotkey v1.1.37.02 on 2026-11-04: the
        // v1 takes the item of an array with a key that is not a number for
        // the property of that name: the `a["b"] := 9` writes the property
        // "b" of the array.
        if rt
            .dialect()
            .the_item_of_an_array_with_a_key_that_is_not_a_number_is_its_property()
        {
            let name = key.to_text();
            return Some(
                rt.write_property_of(this, &name, value, line)
                    .map_err(RuntimeFailure::Error),
            );
        }
        return Some(Err(crate::classes::the_failure_with(
            "Invalid index.",
            &crate::runtime::the_extra_of_the_value(key),
            line,
        )));
    };
    let Some(state) = state(this) else {
        return Some(Err(crate::classes::the_failure_with(
            "Invalid index.",
            &index.to_string(),
            line,
        )));
    };
    let mut state = state.borrow_mut();
    let mut items = items(&state);
    let length = items.len() as i64;
    let place = if rt.dialect().the_array_grows_with_the_write_of_an_item() {
        the_place_of_the_v1(index, length)
    } else {
        place(index, length)
    };
    let Some(place) = place else {
        // Measured on the binary of AutoHotkey v1.1.37.02 on 2026-11-04: the
        // v1 makes the array grow: the `a[5] := 7` of an array of two is the
        // seven, and the places that are not there are holes.
        if rt.dialect().the_array_grows_with_the_write_of_an_item() {
            if index > length {
                while (items.len() as i64) < index - 1 {
                    items.push(element(None));
                }
                items.push(element(Some(value)));
                set_items(&mut state, items);
                return Some(Ok(()));
            }
            // The index that is not positive is not a place of the array: the
            // `a[0] := 7` writes the property "0" of the array, and the
            // `a[-1] := 7` writes the property "-1".
            let name = key.to_text();
            return Some(
                rt.write_property_of(this, &name, value, line)
                    .map_err(RuntimeFailure::Error),
            );
        }
        return Some(Err(crate::classes::the_failure_with(
            "Invalid index.",
            &index.to_string(),
            line,
        )));
    };
    items[place] = element(Some(value));
    set_items(&mut state, items);
    Some(Ok(()))
}

/// A property of an `Array`.
pub(crate) fn property(
    name: &str,
    this: &Value,
    rt: &mut Runtime,
    _line: u32,
) -> Option<Result<Value, RuntimeFailure>> {
    let state = state(this)?;
    // Measured on the binary of AutoHotkey v1.1.37.02 on 2026-11-04: the
    // array of the v1 has neither the length nor the capacity: the
    // `a.Length` is the empty text. The v1 counts the array with the
    // `a.Length()` and the `a.Count()`.
    if !rt.dialect().the_array_has_the_length_and_the_capacity() {
        return None;
    }
    let state = state.borrow();
    match name {
        "length" => Some(Ok(Value::Int(items(&state).len() as i64))),
        "capacity" => Some(Ok(Value::Int(capacity(&state)))),
        _ => None,
    }
}

/// A property of an `Array` that is written.
pub(crate) fn set_property(
    name: &str,
    this: &Value,
    value: Value,
    rt: &mut Runtime,
    line: u32,
) -> Option<Result<(), RuntimeFailure>> {
    let failure = |message: &str| {
        Some(Err(RuntimeFailure::Error(RuntimeError {
            message: message.to_string(),
            line,
        })))
    };
    match name {
        "length" => {
            let wanted = match rt.integer(&value, line) {
                Ok(number) => number,
                Err(failure) => return Some(Err(failure)),
            };
            if wanted < 0 {
                return failure("Invalid value.");
            }
            let state = state(this)?;
            let mut state = state.borrow_mut();
            let mut items = items(&state);
            // A longer array has places without a value of their own, and
            // a shorter one loses the places at the end.
            items.truncate(wanted as usize);
            while (items.len() as i64) < wanted {
                items.push(element(None));
            }
            set_items(&mut state, items);
            Some(Ok(()))
        }
        "capacity" => {
            let wanted = match rt.integer(&value, line) {
                Ok(number) => number,
                Err(failure) => return Some(Err(failure)),
            };
            if wanted < 0 {
                return failure("Invalid value.");
            }
            let state = state(this)?;
            let mut state = state.borrow_mut();
            let mut items = items(&state);
            // A capacity below the length of the array takes the places at
            // the end away.
            if (wanted as usize) < items.len() {
                items.truncate(wanted as usize);
            }
            let count = items.len() as i64;
            set_items(&mut state, items);
            set_capacity(&mut state, wanted.max(count));
            Some(Ok(()))
        }
        _ => None,
    }
}

/// The item of an `Array`: the `__Item` of the class.
///
/// A place without a value of its own is an error, unless the script
/// gave the array a default.
pub(crate) fn item(
    key: &Value,
    this: &Value,
    rt: &mut Runtime,
    line: u32,
) -> Option<Result<Value, RuntimeFailure>> {
    // The place of an item is a number: a value that is not one is not a
    // place at all, and v2 says that the index is invalid.
    let Some(index) = rt.the_place_of_an_item(key) else {
        // Measured on the binary of AutoHotkey v1.1.37.02 on 2026-11-04: the
        // v1 takes the item of an array with a key that is not a number for
        // the property of that name: the `a["b"]` reads the property "b".
        if rt
            .dialect()
            .the_item_of_an_array_with_a_key_that_is_not_a_number_is_its_property()
        {
            let name = key.to_text();
            return Some(rt.read_property(this, &name, line));
        }
        return Some(Err(crate::classes::the_failure_with(
            "Invalid index.",
            &crate::runtime::the_extra_of_the_value(key),
            line,
        )));
    };
    let Some(state) = state(this) else {
        return Some(Err(crate::classes::the_failure_with(
            "Invalid index.",
            &index.to_string(),
            line,
        )));
    };
    let state = state.borrow();
    let items = items(&state);
    let length = items.len() as i64;
    let place = if rt
        .dialect()
        .the_item_of_an_array_that_is_not_there_is_the_empty_text()
    {
        the_place_of_the_v1(index, length)
    } else {
        place(index, length)
    };
    let Some(place) = place else {
        // Measured on the binary of AutoHotkey v1.1.37.02 on 2026-11-04: the
        // v1 does not refuse the item of an array that is not there: the
        // `a[5]` of an array of two is the empty text, and the `a[0]` is the
        // property "0" of the array.
        if rt
            .dialect()
            .the_item_of_an_array_that_is_not_there_is_the_empty_text()
        {
            if index < 1 {
                let name = key.to_text();
                return Some(rt.read_property(this, &name, line));
            }
            return Some(Ok(Value::Text(String::new())));
        }
        return Some(Err(crate::classes::the_failure_with(
            "Invalid index.",
            &index.to_string(),
            line,
        )));
    };
    match element_value(&items[place]) {
        Some(value) => Some(Ok(value)),
        None => match default_property(this) {
            Some(default) => Some(Ok(default)),
            None => Some(Err(RuntimeFailure::Error(RuntimeError {
                message: "Item has no value.".into(),
                line,
            }))),
        },
    }
}

// -- the state ----------------------------------------------------------------

/// The state of an array.
fn state(array: &Value) -> Option<Rc<RefCell<Object>>> {
    let Value::Object(object) = array else {
        return None;
    };
    let state = object.borrow().value_of(STATE)?;
    match state {
        Value::Object(state) => Some(state),
        _ => None,
    }
}

/// A new state: the items in the order of their places, and how many of
/// them fit.
fn new_state(items: Vec<Value>, capacity: i64) -> Value {
    let mut state = Object {
        class: STATE_CLASS.to_string(),
        properties: BTreeMap::new(),
    };
    set_items(&mut state, items);
    set_capacity(&mut state, capacity);
    Value::Object(Rc::new(RefCell::new(state)))
}

/// The items of an array: the elements in the order of their places.
fn items(state: &Object) -> Vec<Value> {
    let Some(Value::List(items)) = state.value_of("items") else {
        return Vec::new();
    };
    items.clone()
}

/// The items of an array, for the built-ins that take one.
///
/// The `StrSplit` takes the delimiters in an array, and the `Sort` takes
/// the values of one. Neither of them may reach into the state of the
/// array: the module that owns the class is the one that answers.
pub(crate) fn the_items(array: &Value) -> Vec<Value> {
    let Some(state) = state(array) else {
        return Vec::new();
    };
    let state = state.borrow();
    items(&state)
        .iter()
        .map(|element| element_value(element).unwrap_or(Value::Text(String::new())))
        .collect()
}

/// The number of the items of an array that are there.
///
/// The places that are not there are not items: the array of two with the
/// third one written has three items, and the holes are not counted.
pub(crate) fn the_number_of_the_items(array: &Value) -> usize {
    let Some(state) = state(array) else { return 0 };
    let state = state.borrow();
    items(&state)
        .iter()
        .filter(|item| element_value(item).is_some())
        .count()
}

/// The number of the places of an array.
///
/// The places that are not there are places: the array of two with the
/// fifth one written has five places.
pub(crate) fn the_number_of_the_places(array: &Value) -> usize {
    let Some(state) = state(array) else { return 0 };
    let state = state.borrow();
    items(&state).len()
}

/// The items of an array, written back.
fn set_items(state: &mut Object, items: Vec<Value>) {
    put(&mut state.properties, "items", Value::List(items));
}

/// How many items an array holds before it has to grow.
fn capacity(state: &Object) -> i64 {
    state
        .value_of("capacity")
        .and_then(|value| value.to_number())
        .map(|number| number as i64)
        .unwrap_or(0)
}

/// How many items an array holds before it has to grow, written.
fn set_capacity(state: &mut Object, capacity: i64) {
    put(&mut state.properties, "capacity", Value::Int(capacity));
}

/// An element of an array: the value, and whether it has one.
///
/// The dialect has no value that means "nothing", so a place without a
/// value of its own is carried as a flag and an empty slot.
fn element(value: Option<Value>) -> Value {
    match value {
        Some(value) => Value::List(vec![Value::Int(1), value]),
        None => crate::runtime::the_mark_of_a_value_without_one(),
    }
}

/// The value of an element, when it has one.
fn element_value(element: &Value) -> Option<Value> {
    match element {
        Value::List(items) if items.len() == 2 && items[0] == Value::Int(1) => {
            Some(items[1].clone())
        }
        _ => None,
    }
}

/// The default of an array: the value the script gave to the `Default`
/// property, when it gave one.
fn default_property(array: &Value) -> Option<Value> {
    let Value::Object(object) = array else {
        return None;
    };
    object.borrow().value_of("default")
}

/// Put a value at the end of the array.
fn push_value(array: &Value, value: Value) {
    push_element(array, Some(value));
}

/// Put a value at the end of the array, or a hole.
///
/// The hole is a place of the array that has no value of its own, and it
/// is what the literal of an array with a hole makes.
fn push_element(array: &Value, value: Option<Value>) {
    let Some(state) = state(array) else { return };
    let mut state = state.borrow_mut();
    let mut items = items(&state);
    items.push(element(value));
    let count = items.len() as i64;
    set_items(&mut state, items);
    // The array grows to hold what is put in it.
    if count > capacity(&state) {
        set_capacity(&mut state, count);
    }
}

/// A copy of an array: the same values, in the same places, and the same
/// properties.
///
/// The values are copied the way a script copies them: a value that is
/// an object is the same object in the copy.
fn clone(array: &Value) -> Value {
    let (items, capacity) = match state(array) {
        Some(state) => {
            let state = state.borrow();
            (items(&state), capacity(&state))
        }
        None => (Vec::new(), 0),
    };
    let mut properties = BTreeMap::new();
    put(&mut properties, STATE, new_state(items, capacity));
    // The properties the script gave the array are copied as well.
    if let Value::Object(object) = array {
        for (name, property) in object.borrow().properties.iter() {
            if name != STATE {
                properties.insert(name.clone(), property.clone());
            }
        }
    }
    Value::Object(Rc::new(RefCell::new(Object {
        class: "array".to_string(),
        properties,
    })))
}

// -- the places ---------------------------------------------------------------

/// The place of an index: the places count from one, and a negative
/// index counts from the end.
fn place(index: i64, length: i64) -> Option<usize> {
    let place = if index < 0 { length + index + 1 } else { index };
    if place < 1 || place > length {
        None
    } else {
        Some(place as usize - 1)
    }
}

/// The place of an index in the dialect of the v1: the places count from
/// one, and an index that is not positive is not a place at all.
///
/// Measured on the binary of AutoHotkey v1.1.37.02 on 2026-11-04: the v1
/// does not count from the end: the `a[-1]` of an array of two is the
/// empty text, and the `a[0]` is the empty text too.
fn the_place_of_the_v1(index: i64, length: i64) -> Option<usize> {
    if index < 1 || index > length {
        None
    } else {
        Some(index as usize - 1)
    }
}

/// The place of an insert: the places count from one, a zero is the end
/// of the array, and a negative index counts from the end.
fn insert_place(index: i64, length: i64) -> Option<usize> {
    let place = if index < 0 {
        length + index + 1
    } else if index == 0 {
        length + 1
    } else {
        index
    };
    if place < 1 || place > length + 1 {
        None
    } else {
        Some(place as usize - 1)
    }
}

// -- the base object ----------------------------------------------------------

/// The methods of the base object, answered for an array.
///
/// The runtime answers them for the classes of the script, and it knows
/// nothing of the class types of the runtime: an array has no method of
/// the script, and the places of an array are not properties of it.
fn base_method(
    method: &str,
    this: &Value,
    arguments: &[Value],
    rt: &mut Runtime,
    line: u32,
) -> Option<Result<Value, RuntimeFailure>> {
    let Value::Object(object) = this else {
        return None;
    };
    // Measured on the binary of AutoHotkey v1.1.37.02 on 2026-11-04: the
    // array of the v1 has no method of the base object of the v2: the
    // `a.HasOwnProp(1)` is ignored and the answer is the empty text.
    if !rt.dialect().the_object_has_the_methods_of_the_base_object() {
        return None;
    }
    let failure = |message: &str| {
        Some(Err(RuntimeFailure::Error(RuntimeError {
            message: message.to_string(),
            line,
        })))
    };
    let name = arguments
        .first()
        .map(|value| value.to_text())
        .unwrap_or_default();
    let key = name.to_lowercase();
    match method {
        "ownprops" => {
            // Measured on the binary of v2.0.19 on 2026-10-31: the own
            // properties of v2 are an enumerator, and it gives the name
            // when the caller wants one value.
            let pairs: Vec<(Value, Value)> = object
                .borrow()
                .properties
                .iter()
                .filter(|(name, _)| name.as_str() != STATE)
                .map(|(_, property)| (Value::Text(property.name.clone()), property.value.clone()))
                .collect();
            Some(Ok(enumerator::make(pairs, enumerator::Alone::TheKey)))
        }
        "hasownprop" => Some(Ok(Value::Int(own_property(object, &key) as i64))),
        "hasprop" => Some(Ok(Value::Int(
            (PROPERTIES.contains(&key.as_str())
                // The methods of the class are the properties of the value.
                //
                // Measured on the binary of v2.0.19 on 2026-10-31:
                // `m.HasProp("Get")` answers 1.
                || METHODS.contains(&key.as_str())
                || own_property(object, &key)
                // Every value carries its class, and the base object has
                // the property of it.
                || key == "__class"
                // Every class has an initialiser, and every object has a
                // base.
                //
                // Measured on the binary of v2.0.19 on 2026-10-31:
                // `m.HasProp("__Init")` and `m.HasProp("Base")` answer 1.
                || key == "__init"
                || key == "base") as i64,
        ))),
        "hasmethod" => Some(Ok(Value::Int(
            (METHODS.contains(&key.as_str())
                // Every class has an initialiser.
                //
                // Measured on the binary of v2.0.19 on 2026-10-31:
                // `m.HasMethod("__Init")` answers 1.
                || key == "__init") as i64,
        ))),
        "getownpropdesc" => {
            let name = arguments
                .first()
                .map(|value| value.to_text())
                .unwrap_or_default();
            let value = object.borrow().value_of(&key);
            match value {
                Some(value) => {
                    // Measured on the binary of v2.0.19 on 2026-10-31: the
                    // descriptor that comes back is an object with the
                    // members of it.
                    let table = match rt.the_members_of_a_descriptor(&value) {
                        Some(members) => members,
                        None => {
                            let mut table = BTreeMap::new();
                            put(&mut table, "value", value);
                            table
                        }
                    };
                    Some(Ok(Value::Object(Rc::new(RefCell::new(Object {
                        class: "object".to_string(),
                        properties: table,
                    })))))
                }
                // The property is not there: v2 says so.
                None => Some(Err(rt.no_property(this, &name, line))),
            }
        }
        "defineprop" => {
            if key == STATE {
                return failure("the state of an array is not a property of it.");
            }
            // Measured on the binary of v2.0.19 on 2026-10-31: the second
            // parameter is a descriptor, and a value that is not one is
            // refused with the reason.
            let descriptor = match rt.the_descriptor(arguments.get(1), line) {
                Ok(descriptor) => descriptor,
                Err(failure) => return Some(Err(failure)),
            };
            put(&mut object.borrow_mut().properties, &name, descriptor);
            // The answer of v2 is the object itself.
            Some(Ok(this.clone()))
        }
        "deleteprop" => {
            if key == STATE {
                return Some(Ok(Value::Text(String::new())));
            }
            let gone = object
                .borrow_mut()
                .properties
                .remove(&key)
                .map(|property| property.value);
            // Measured on the binary of v2.0.19 on 2026-10-31: the answer
            // is the value of the property that is taken away, and an
            // empty text when there was none.
            Some(Ok(match gone {
                None => Value::Text(String::new()),
                Some(value) => match rt.the_value_of_the_descriptor(&value, this, &name, line) {
                    Ok(Some(value)) => value,
                    _ => value,
                },
            }))
        }
        _ => None,
    }
}

/// Whether the array has a property of that name.
///
/// The state of the array is not a property of it: it is the inside of
/// the array, and the script never wrote it.
fn own_property(object: &Rc<RefCell<Object>>, key: &str) -> bool {
    key != STATE && object.borrow().properties.contains_key(key)
}