Control Flow Macros: Adopt FALL_THROUGH_TO

inexorabletash · inexorabletash · commit 4932bc02094b · 2026-03-12T19:55:30.000-07:00
No binary changes
diff --git a/docs/Coding_Style.md b/docs/Coding_Style.md
@@ -138,8 +138,7 @@ xcoord  .word
 
 ```asm
         ...
-        lda     #alert_num
-        FALL_THROUGH_TO ShowAlert
+        FALL_THROUGH_TO ShowAlert, A=#alert_num
 .endproc
 
 .proc ShowAlert
diff --git a/src/desk_acc/change.type.s b/src/desk_acc/change.type.s
@@ -425,8 +425,7 @@ yes:    RETURN  C=0
 .endproc ; ExitOK
 
 .proc ExitCancel
-        lda     #0
-        FALL_THROUGH_TO Exit
+        FALL_THROUGH_TO Exit, A=#0
 .endproc ; ExitCancel
 
 .proc Exit
diff --git a/src/desk_acc/international.s b/src/desk_acc/international.s
@@ -270,8 +270,7 @@ ret:    rts
         adc     #1
         cmp     #Field::LAST+1
         bcc     UpdateSelection
-        lda     #Field::FIRST
-        FALL_THROUGH_TO UpdateSelection
+        FALL_THROUGH_TO UpdateSelection, A=#Field::FIRST
 .endproc ; OnKeyNext
 
 .proc UpdateSelection
diff --git a/src/desk_acc/print.catalog.s b/src/desk_acc/print.catalog.s
@@ -949,8 +949,7 @@ vector: jsr     SLOT1                    ; self-modified
         copy8   #0, ch
 
         CALL    COut, A=#CHAR_RETURN
-        lda     #CHAR_DOWN
-        FALL_THROUGH_TO COut
+        FALL_THROUGH_TO COut, A=#CHAR_DOWN
 .endproc ; CROut
 
 .proc COut
diff --git a/src/desk_acc/show.image.file.s b/src/desk_acc/show.image.file.s
@@ -621,8 +621,7 @@ next:
     IF NS
         JUMP_TABLE_MLI_CALL READ, read_lores_params
     END_IF
-        lda     #$80            ; main
-        FALL_THROUGH_TO convert
+        FALL_THROUGH_TO convert, A=#$80 ; main
 
 convert:
         sta     is_main
@@ -1509,8 +1508,7 @@ saw_header_flag:                ; bit7
         beq     ChangeFile  ; always
 .endproc ; PreviousFile
 .proc FirstFile
-        lda     #$40
-        FALL_THROUGH_TO ChangeFile
+        FALL_THROUGH_TO ChangeFile, A=#$40
 .endproc ; FirstFile
 
 ;;; Input: A = flags, bit6 = modified, bit7 = advance
diff --git a/src/desktop/auxmem.s b/src/desktop/auxmem.s
@@ -583,8 +583,7 @@ start:
 
         copy8   #AlertOptions::Beep|AlertOptions::SaveBack, alert_params+AlertParams::options
 
-        ldax    #alert_params
-        FALL_THROUGH_TO Alert
+        FALL_THROUGH_TO Alert, AX=#alert_params
 .endproc ; AlertByIdImpl
 AlertById := AlertByIdImpl::start
 
diff --git a/src/desktop/lc.s b/src/desktop/lc.s
@@ -169,8 +169,7 @@ params: .res    3
 
 ;;; A=alert number, with default options
 .proc ShowAlert
-        ldx     #kShowAlertUseDefaultOptionsForId
-        FALL_THROUGH_TO ShowAlertOption
+        FALL_THROUGH_TO ShowAlertOption, X=#kShowAlertUseDefaultOptionsForId
 .endproc ; ShowAlert
 
 ;;; A=alert number, X=`AlertButtonOptions::*`
diff --git a/src/desktop/main.s b/src/desktop/main.s
@@ -2196,8 +2196,7 @@ CmdAbout := AboutDialogProc
 ;;; ============================================================
 
 .proc CmdAboutThisApple
-        ldax    #str_about_this_apple
-        FALL_THROUGH_TO LaunchPassedPathOnSystemDisk
+        FALL_THROUGH_TO LaunchPassedPathOnSystemDisk, AX=#str_about_this_apple
 .endproc ; CmdAboutThisApple
 
 ;;; ============================================================
@@ -2274,8 +2273,7 @@ CmdDeskAcc      := CmdDeskAccImpl::start
     END_IF
         CALL    IconToAnimate, AX=#tmp_path_buf
         tay
-        ldax    #tmp_path_buf
-        FALL_THROUGH_TO InvokeDeskAccWithIcon
+        FALL_THROUGH_TO InvokeDeskAccWithIcon, AX=#tmp_path_buf
 .endproc ; InvokeDeskAccByPath
 
 ;;; ============================================================
@@ -5343,8 +5341,7 @@ alert:  jmp     ShowAlert       ; either `ERR_INVALID_PATHNAME` or `ERR_FILE_NOT
 ;;; Same inputs/outputs as `ActivateAndRefreshWindowOrClose`
 
 .proc UpdateActivateAndRefreshSelectedWindow
-        lda     selected_window_id
-        FALL_THROUGH_TO UpdateActivateAndRefreshWindow
+        FALL_THROUGH_TO UpdateActivateAndRefreshWindow, A=selected_window_id
 .endproc ; UpdateActivateAndRefreshSelectedWindow
 
 .proc UpdateActivateAndRefreshWindow
@@ -5412,8 +5409,7 @@ alert:  jmp     ShowAlert       ; either `ERR_INVALID_PATHNAME` or `ERR_FILE_NOT
         ITK_CALL IconTK::UnhighlightIcon, icon_param
         ITK_CALL IconTK::DrawIcon, icon_param
 
-        lda     icon_param
-        FALL_THROUGH_TO RemoveFromSelectionList
+        FALL_THROUGH_TO RemoveFromSelectionList, A=icon_param
 .endproc ; UnhighlightAndDeselectIcon
 
 ;;; ============================================================
@@ -5776,8 +5772,7 @@ beyond:
 
 ;;; Close the active window
 .proc CloseActiveWindow
-        lda     active_window_id
-        FALL_THROUGH_TO CloseSpecifiedWindow
+        FALL_THROUGH_TO CloseSpecifiedWindow, A=active_window_id
 .endproc ; CloseActiveWindow
 
 ;;; Inputs: A = window_id
@@ -5898,8 +5893,7 @@ validate_windows_flag:
 ;;; ============================================================
 
 .proc ApplyActiveWinfoToWindowGrafport
-        lda     active_window_id
-        FALL_THROUGH_TO ApplyWinfoToWindowGrafport
+        FALL_THROUGH_TO ApplyWinfoToWindowGrafport, A=active_window_id
 .endproc ; ApplyActiveWinfoToWindowGrafport
 
 .proc ApplyWinfoToWindowGrafport
@@ -6687,8 +6681,7 @@ slash:  cpy     #1
 ;;; ============================================================
 
 .proc FindWindowForSrcPath
-        ldax    #src_path_buf
-        FALL_THROUGH_TO FindWindowForPath
+        FALL_THROUGH_TO FindWindowForPath, AX=#src_path_buf
 .endproc ; FindWindowForSrcPath
 
 ;;; ============================================================
@@ -7595,8 +7588,7 @@ draw:   MGTK_CALL MGTK::DrawString, text_input_buf
 .endproc ; _PrepAvailable
 
 .proc _Measure
-        ldax    #text_input_buf
-        FALL_THROUGH_TO _MeasureString
+        FALL_THROUGH_TO _MeasureString, AX=#text_input_buf
 .endproc ; _Measure
 
 ;;; Measure text, pascal string address in A,X; result in A,X
@@ -8324,8 +8316,7 @@ set_pos:
 
         blocks := list_view_filerecord + FileRecord::blocks
 
-        ldax    blocks
-        FALL_THROUGH_TO ComposeSizeString
+        FALL_THROUGH_TO ComposeSizeString, AX=blocks
 .endproc ; _PrepareColSize
 
 .endproc ; DrawListViewRow
@@ -8790,8 +8781,7 @@ map_delta_y:    .word   0
 ;;; Trashes: $08
 
 .proc PrepActiveWindowScreenMapping
-        lda     active_window_id
-        FALL_THROUGH_TO PrepWindowScreenMapping
+        FALL_THROUGH_TO PrepWindowScreenMapping, A=active_window_id
 .endproc ; PrepActiveWindowScreenMapping
 
         PROC_USED_CLEARING_UPDATES
@@ -13353,8 +13343,7 @@ RestoreDynamicRoutine   := LoadDynamicRoutineImpl::restore
 ;;; A,X = A * 64
         PROC_USED_IN_OVERLAY
 .proc ATimes64
-        ldx     #6
-        FALL_THROUGH_TO AShiftX
+        FALL_THROUGH_TO AShiftX, X=#6
 .endproc ; ATimes64
 
 ;;; A,X = A << X
@@ -13679,8 +13668,7 @@ ignore: RETURN  C=1
 ;;; ============================================================
 
 .proc DrawDialogPathBuf0
-        ldax    #path_buf0
-        FALL_THROUGH_TO DrawDialogPath
+        FALL_THROUGH_TO DrawDialogPath, AX=#path_buf0
 .endproc ; DrawDialogPathBuf0
 
         .include "../lib/drawdialogpath.s"
diff --git a/src/desktop/ovl_selector_pick.s b/src/desktop/ovl_selector_pick.s
@@ -401,8 +401,7 @@ clean_flag:                     ; high bit set if "clean", cleared if "dirty"
         TAIL_CALL DrawTitleCentered, AX=#label_del
     END_IF
 
-        ldax    #label_run
-        FALL_THROUGH_TO DrawTitleCentered
+        FALL_THROUGH_TO DrawTitleCentered, AX=#label_run
 .endproc ; OpenWindow
 
 ;;; ============================================================
diff --git a/src/extras/asmtest.system.s b/src/extras/asmtest.system.s
@@ -43,7 +43,7 @@
         .include "../inc/macros.inc"
 
 ;;; ============================================================
-;;; Flow Control Macros - Branch & Loop
+;;; Control Flow Macros - Branch & Loop
 ;;; ============================================================
 
 ;;; --------------------------------------------------
@@ -930,7 +930,7 @@ table := *
     WHILE POS
 
 ;;; ============================================================
-;;; Flow Control Macros - Functions
+;;; Control Flow Macros - Functions
 ;;; ============================================================
 
 var:
diff --git a/src/inc/flow.inc b/src/inc/flow.inc
@@ -1,6 +1,6 @@
 ;;; ============================================================
 ;;;
-;;; Flow Control
+;;; Control Flow
 ;;;
 ;;; ============================================================
 
@@ -1135,10 +1135,13 @@
 ;;; * CALL proc, args...
 ;;; * TAIL_CALL proc, args...
 ;;; * RETURN args...
+;;; * FALL_THROUGH_TO proc, args...
 ;;;
 ;;; Args take the form of (pseudo-)register or flag assigments, and
-;;; loads/clears/sets are emitted in the order given. CALL produces
-;;; a JSR, TAIL_CALL produces a JMP, and RETURN produces RTS.
+;;; loads/clears/sets are emitted in the order given. CALL produces a
+;;; JSR, TAIL_CALL produces a JMP, and RETURN produces RTS.
+;;; FALL_THROUGH_TO produces nothing, but prevents refactoring
+;;; mistakes.
 ;;;
 ;;; Registers/pseudo-registers are: A, X, Y, AX, AY, XY, YA
 ;;; Expressions can be anything supported by the LD* ops/pseudo-ops.
@@ -1169,6 +1172,13 @@
     _FLOW_END_STATEMENT
 .endmacro
 
+.macro FALL_THROUGH_TO target,arg1,arg2,arg3,arg4,arg5,arg6,arg7,arg8,arg9
+    _FLOW_STATEMENT "FALL_THROUGH_TO"
+    _CALL_HELPER {arg1},{arg2},{arg3},{arg4},{arg5},{arg6},{arg7},{arg8},{arg9}
+        .assert * = (target), error, .sprintf("Fall through expectation failed: %s", .string(target))
+    _FLOW_END_STATEMENT
+.endmacro
+
 .macro _CALL_HELPER arg1,arg2,arg3,arg4,arg5,arg6,arg7,arg8,arg9
     .ifblank arg1
         ;; nothing
diff --git a/src/inc/macros.inc b/src/inc/macros.inc
@@ -385,10 +385,6 @@ loop:   pla
         .assert (* - name) = (size) * (record_length), error, .sprintf("Table size mismatch: %s (expected: %d, actual: %d)", .string(name), (size) * (record_length), * - name)
 .endmacro
 
-.macro FALL_THROUGH_TO label
-        .assert * = (label), error, .sprintf("Fall through expectation failed: %s", .string(label))
-.endmacro
-
 
 ;;; ============================================================
 ;;; Jump Table Definitions (very DeskTop-specific)
diff --git a/src/mgtk/mgtk.s b/src/mgtk/mgtk.s
@@ -3836,8 +3836,7 @@ table:  .byte   <(TXTCLR / 2), <(MIXCLR / 2), <(LOWSCR / 2), <(LORES / 2)
 ;;; SetPort
 
 .proc SetPortImpl
-        ldax    params_addr
-        FALL_THROUGH_TO assign_and_prepare_port
+        FALL_THROUGH_TO assign_and_prepare_port, AX=params_addr
 .endproc ; SetPortImpl
 
         ;; Call with port address in (X,A)
@@ -3860,8 +3859,7 @@ prepare_port:
 
 .proc GetPortImpl
         jsr     ApplyPortToActivePort
-        ldax    active_port
-        FALL_THROUGH_TO store_xa_at_params
+        FALL_THROUGH_TO store_xa_at_params, AX=active_port
 .endproc ; GetPortImpl
 
         ;; Store result (X,A) at params
@@ -5187,8 +5185,7 @@ stack_ptr_save:
         asl     preserve_zp_flag
         copy16  params_addr_save, params_addr
 
-        ldax    active_port
-        FALL_THROUGH_TO SetAndPreparePort
+        FALL_THROUGH_TO SetAndPreparePort, AX=active_port
 .endproc ; RestoreParamsAndStack
 
 .proc SetAndPreparePort
@@ -5863,8 +5860,7 @@ set_x:  stax    current_penloc_x
 .endproc ; SetPenloc
 
 .proc SetFillModeXOR
-        lda     #MGTK::penXOR
-        FALL_THROUGH_TO SetFillMode
+        FALL_THROUGH_TO SetFillMode, A=#MGTK::penXOR
 .endproc ; SetFillModeXOR
 
         ;; Set fill mode to A
@@ -6112,8 +6108,7 @@ filler: ldx     menu_item_index
 
 
 .proc FindMenuById
-        lda     #find_mode_by_id
-        FALL_THROUGH_TO FindMenu
+        FALL_THROUGH_TO FindMenu, A=#find_mode_by_id
 .endproc ; FindMenuById
 
 .proc FindMenu
diff --git a/src/selector/alert_dialog.s b/src/selector/alert_dialog.s
@@ -112,8 +112,7 @@ start:
         tay                     ; Y = index
         copy8   alert_options_table,y, alert_params::buttons
 
-        ldax    #alert_params
-        FALL_THROUGH_TO Alert
+        FALL_THROUGH_TO Alert, AX=#alert_params
 .endproc ; AlertById
 
 ;;; ============================================================
diff --git a/src/selector/app.s b/src/selector/app.s
@@ -1133,8 +1133,7 @@ backup_devlst:
 
 .proc GetPortAndDrawWindow
         CALL    GetWindowPort, A=#winfo::kDialogId
-        clc                     ; not an update
-        FALL_THROUGH_TO DrawWindow
+        FALL_THROUGH_TO DrawWindow, C=0 ; not an update
 .endproc ; GetPortAndDrawWindow
 
 ;;; Inputs: C set if processing update event, clear otherwise
diff --git a/src/selector/ovl_file_dialog.s b/src/selector/ovl_file_dialog.s
@@ -121,8 +121,7 @@ file_dialog_loop   := file_dialog::ep_loop
 .endproc ; SaveFileDialogState
 
 .proc RestoreFileDialogState
-        clc                     ; aux>main
-        FALL_THROUGH_TO _MoveFileDialogState
+        FALL_THROUGH_TO _MoveFileDialogState, C=0 ; aux>main
 .endproc ; RestoreFileDialogState
 
 ;;; C set by caller
diff --git a/src/toolkits/icontk.s b/src/toolkits/icontk.s
@@ -998,8 +998,7 @@ move_ok:
         rts
         END_OF_LAMBDA
 
-        lda     #IconTK::kDragResultMove
-        FALL_THROUGH_TO exit_with_a
+        FALL_THROUGH_TO exit_with_a, A=#IconTK::kDragResultMove
 
         ;; --------------------------------------------------
 
@@ -1401,8 +1400,7 @@ clip_window_id:
 .proc DrawIconImpl
         jsr     InitSetIconPort
 
-        lda     #$80            ; `clip_icons_flag`
-        FALL_THROUGH_TO DrawIconCommon
+        FALL_THROUGH_TO DrawIconCommon, A=#$80 ; `clip_icons_flag`
 .endproc ; DrawIconImpl
 
 ;;; ============================================================
