usage.md

How to use ABAP cleaner

Cleaning code from ADT with the ABAP cleaner plug-in

Automated cleanup

To clean ABAP code automatically with a single keystroke,

1. Select any amount of ABAP code in the current code editor in ADT for Eclipse or VS Code - or alternatively, do NOT select any code to apply cleanup to the current method or declaration section.

2. Press Ctrl + 4 or select menu 'Source Code / Clean Up With Automated ABAP Cleaner' (Eclipse) or command 'ABAP cleaner: Format Selection' (VS Code). The cleanup will be done automatically, using the profile and cleanup range that was last selected when you used the interactive ABAP cleaner UI (see below).

   

If you clean a selection of code, ABAP cleaner will expand your selection to whole ABAP statements. With the plug-in, you are not required to select complete code blocks (e.g., you may select an IF without its corresponding ENDIF).

In VS Code, you may alternatively use command 'Format Selection' or 'Format Document' (Shift + Alt + F). In the VS Code Settings, ABAP cleaner can be selected as the default formatter with 'Editor: Default Formatter'. The setting 'Editor: Format on Save' also applies to ABAP cleaner.

Interactive cleanup

To clean ABAP code interactively,

1. Select any amount of ABAP code in the current code editor in ADT for Eclipse or VS Code - or alternatively, do NOT select any code to apply cleanup to the current method or declaration section.

2. Press Ctrl + Shift + 4 or select menu 'Source Code / Clean Up With Interactive ABAP Cleaner...' (Eclipse) or command 'ABAP Cleaner: Format Interactively' (VS Code). This will open the ABAP cleaner UI to compare the original and the cleaned code.

   

3. Check the changes highlighted in the display, using the arrow keys Left / Right to navigate to the previous / next finding (or Ctrl + Left / Right for the previous / next screen with findings).

   

   (Un)check the 'Highlight ...' options to focus on certain types of changes. If you come across a changed statement which you prefer to keep in its original state, simply deactivate the applied rule(s) in the 'Rules Used in Current Selection' list for this statement. You may also configure or select a different profile for the cleanup.

4. Press Ctrl + Enter or click 'Apply and Close' to apply the result and return to the ADT editor; to discard the changes, press Esc or click 'Cancel'.

Read-only preview without locking or changing code

If you only want a preview of the cleaned code, without locking or changing the code (e.g. because the object is locked by another person, or you do not have development authorization in the current system),

1. Select any amount of ABAP code in the current code editor in ADT for Eclipse or VS Code.

2. Press Ctrl + Shift + 5 or select menu 'Source Code / Show Read-Only Preview With ABAP Cleaner...' (Eclipse) or command 'ABAP Cleaner: Show Read-Only Preview' (VS Code):

   

This opens the interactive ABAP cleaner UI as described above, but the code will not be locked or changed. Nevertheless, changes to ABAP cleaner settings (selected profile, activated rules and options etc.) will be kept.

The read-only preview also allows you to paste other ABAP code (e.g. from SAP GUI) into the ABAP cleaner UI by pressing Ctrl + V or selecting menu 'Code / From Clipboard', or to read code from a file with 'Code / From File...'.

Cleaning code with the stand-alone ABAP cleaner app

To clean ABAP code,

1. Enter edit mode in your development environment (SAP GUI) to block others from changing the code in the meantime.

2. Copy a section of code from the IDE to the clipboard. This may be anything from a single statement to an entire code document with several classes. However, any blocks (IF ... ENDIF, LOOP ... ENDLOOP, METHOD ... ENDMETHOD etc.) must be complete for the stand-alone ABAP cleaner app to work.

3. Paste the code into the ABAP cleaner main window by pressing Ctrl + V or using the menu 'Code / From Clipboard'. ABAP cleaner immediately processes the code with the selected Profile; you may select a different profile to reprocess the code with a different selection or configuration of rules.

4. Check the changes highlighted in the display, using the arrow keys Left / Right to navigate to the previous / next finding (or Ctrl + Left / Right for the previous / next screen with findings). (Un)check the 'Highlight ...' options to focus on certain types of changes. If you come across a changed statement which you prefer to keep in its original state, simply deactivate the applied rule(s) in the 'Rules Used in Current Selection' list for this statement.

   

5. Copy all cleaned code from ABAP cleaner to the clipboard by pressing Ctrl + A (to select the entire code) and then Ctrl + C, or by using the menu 'Code / Whole Result to Clipboard'.

6. Paste the code back to your IDE, replacing the previous section of code. It is recommended to keep the code selected in the IDE in step 2, so you are sure to replace the exact section which you copied earlier.

If you activate the ABAP cleaner menu 'Code / Watch and Modify Clipboard', you can skip steps 3-5: As soon as you copy code into the clipboard, ABAP cleaner will replace the clipboard content with cleaned code (confirming the action with a sound), so you can immediately replace the selected code by pasting the modified clipboard content into your IDE.

Calling ABAP cleaner from the command line

To integrate ABAP cleaner in other processes, you may call the "abap-cleanerc.exe" of the stand-alone version from the command line with the following arguments for cleaning either a single file or multiple files in a directory:

Show help or version information:
    .\abap-cleanerc.exe /?
    .\abap-cleanerc.exe /man
    .\abap-cleanerc.exe --version


Cleanup of single source:
    .\abap-cleanerc.exe {--sourcefile <path> | --source <code>} [--linerange <numrange> [--scope <scopename>] ]
                        [{ --profile <path> | --profiledata <json> | --profilename <name> | --last-profile }] [--release <num>] [--workspace <dir>]
                        [--targetfile <path> [--overwrite]] [--partialresult] [--crlf]
                        [--stats] [--usedrules]

- Example for cleanup of single source:
    .\abap-cleanerc.exe --sourcefile "CL_ANY_CLASS.txt" --linerange "20-35" --scope method --profilename "team A: profile" --release "757" --targetfile "result\CL_ANY_CLASS.txt" --overwrite --stats --usedrules


Interactive cleanup (single source only; profile and user scope only selected on the UI):
    .\abap-cleanerc.exe {--sourcefile <path> | --source <code>} [--linerange <numrange> [--scope {statement | user}] ]
                        [--release <num>] [--workspace <dir>]
                        --ui [--title <text>] [--readonly] [--darktheme]
                        [--targetfile <path> [--overwrite]] [--partialresult] [--crlf]

- Example for interactive cleanup of single file:
    .\abap-cleanerc.exe --sourcefile "CL_ANY_CLASS.txt" --release "757" --ui --title "CL_ANY_CLASS" --workspace "test_ws" --readonly


Cleanup of multiple files:
    .\abap-cleanerc.exe --sourcedir <path> [--filepattern <pattern>] [--recursive]
                        [{ --profile <path> | --profiledata <json> | --profilename <name> | --last-profile }] [--release <num>] [--workspace <dir>]
                        [--targetdir <path> [--overwrite]] [--crlf]
                        [--stats] [--usedrules]

- Example for cleanup of multiple files:
    .\abap-cleanerc.exe --sourcedir "C:\temp\source" --filepattern "*.txt" --recursive --profile "C:\temp\profile.cfj" --release "757" --targetdir "C:\temp\target" --overwrite


Options for cleanup:
    --sourcefile        File name of an ABAP source file which is input to the cleanup.
    --source            ABAP source code which is input to the cleanup.
                        Please use either --sourcefile or --source or --sourcedir.
    --linerange         Single line range for partial cleanup, e.g. "20-35"
                        Without this option, the cleanup will be applied to the whole code document.
    --scope             Expands the line range to the supplied scope: statement (default), method, 
                        class, document or user (setting from the UI).
                        Without this option, the line range will only be expanded to statement scope.

    --sourcedir         Folder that contains ABAP source files (default file pattern is "*.abap")
    --filepattern       File pattern to look for (only relevant when --sourcedir has been supplied)
    --recursive         Searches provided source directory recursively for ABAP files

    --profile           File name of the cleanup profile to be used (extension .cfj). From the UI,
                        you may use button 'Export...' from the profiles editor to create the file.
    --profiledata       JSON-like content of the cleanup profile to be used.
    --profilename       Name of the cleanup profile to be used, as displayed on the UI.
                        This includes synchronized team profiles such as "team A: profile".
    --last-profile      Use the cleanup profile that was last selected on the UI on this machine.
                        Please provide only one profile option (or none for program defaults).

    --release           ABAP release to restrict syntax of cleanup changes, e.g. "758".
                        Without this option, the latest ABAP syntax will be allowed.
    --workspace         The workspace directory or ID, used to retrieve workspace-specific settings
                        for the last cleanup profile to be used (--last-profile), for expanding the
                        line range (--scope user) and additional release restrictions (from the UI).

    --ui                Open the UI for interactive cleanup and profile configuration
                        (only possible for single source input).
    --title             The source code title to be displayed on the UI.
    --readonly          Show a read-only preview of the changes without allowing to apply them.
    --darktheme         Show the code with dark theme colors.

    --targetfile        Target file name to which the cleanup result will be saved.
                        Without this option, the cleanup result will be written to the standard output.
    --targetdir         Target directory name to which the cleanup files will be saved
                        If not supplied, --sourcedir will be the target diretory
    --overwrite         Overwrite target file if it already exists.
                        Without this option, an error will be raised if the target file already exists.
    --partialresult     Restrict output to the cleanup result of the --linerange (if supplied).
                        Without this option, the cleanup result of whole code document will be returned.
    --crlf              Use CRLF = "\r\n" as line separator (default: LF = "\n").
    --simulate          Run cleanup without writing the result code to a file or to standard output.
                        Use this option to check the potential effect of cleanup with --stats or --usedrules.

    --stats             Write statistical summary to standard output.
    --usedrules         Write list of used rules to standard output.


Starting and using a daemon:
    .\abap-cleanerc.exe --daemonize [--idle-timeout <seconds>]
    socket.write: --ping [--request-id <id>]
    socket.write: --status [--request-id <id>]
    socket.write: --sourcefile ... [--request-id <id>]
    socket.write: --keep-alive [--request-id <id>]
    socket.write: --stop [--request-id <id>]

- Example for starting and using a daemon:
    .\abap-cleanerc.exe --daemonize --idle-timeout 600
    socket.write: --ping --request-id 1
    socket.write: --status --request-id 2
    socket.write: --sourcefile "CL_ANY_CLASS.txt" --targetfile "result\CL_ANY_CLASS.txt" --overwrite --request-id 3
    socket.write: --keep-alive --request-id 4
    socket.write: --stop --request-id 5


Options for starting and using a daemon:
    --daemonize         Makes the program run as a daemon process in the background. Returns
                        the localhost port number to which the daemon is listening for commands.
    --idle-timeout      Specifies the idle timeout in seconds after which the daemon will
                        automatically stop if no command is received. Use 0 for no idle timeout.

    --ping              Pings the daemon; returns 'pong' via the socket's output stream.*
    --status            Returns the start time, idle time, and idle timeout of the daemon.*
    --sourcefile        All cleanup commands work as described above. Responses are written
                        to the client socket's output stream.*
    --keep-alive        Resets the idle timer of the daemon; returns 'OK: ...'.*
    --stop              Stops the daemon; returns 'OK: ...'.*

    --request-id        A unique identifier that will be added at the end of the daemon's
                        response to allow the client to map the response to the command.*

    * All responses end with an extra line that contains '<<<END>>>' and the request <id>
      (if supplied), e.g. '<<<END>>> 42'.

GitHub Actions workflow usage

Here is an example of how the command line options could be used in a GitHub Actions workflow /.github/workflows/clean-up.yml that is triggered whenever someone pushes a change to the main branch of the GitHub repository, and then

1. automatically downloads the latest version of ABAP cleaner,
2. runs ABAP cleaner on all *.abap files inside the /src folder and all its subfolders, using the ABAP cleaner profile cleaner-profile.cfj and restricting cleanup to the ABAP syntax of release 7.50,
3. commits the changes:

name: Clean Up ABAP Files

on:
  push:
   branches: ["main"]
  # pull_request:
  #   branches: ["main"]

  workflow_dispatch:

jobs:
  Code-Cleanup:
    runs-on: ubuntu-latest

    steps:
      - run: git config --global core.autocrlf true

      - name: Checkout
        uses: actions/checkout@v3

      - name: Download ABAP cleaner (latest version)
        run: |
          mkdir .cleanup
          cd .cleanup
          wget -q -c https://github.com/SAP/abap-cleaner/releases/latest/download/com.sap.adt.abapcleaner.app-linux.gtk.x86_64.tar.gz -O - | tar -xz
          cd ..

      - name: Clean-up files in /src
        run: ./.cleanup/abapcleaner/abap-cleaner --sourcedir src --recursive --overwrite --profile cleaner-profile.cfj --release 750 --stats --usedrules

      - name: Commit changes
        uses: EndBug/add-and-commit@v9
        with:
          default_author: github_actions
          message: "style: code cleanup with ABAP cleaner"
          add: "src"

Continue reading: Main window