Skip to content

Converting Files with Alchemist

Have you tried the tutorial?

If you haven't already, start with the tutorial to get a quick overview of how to use Alchemist. The tutorial will guide you through the process of setting up Alchemist, preparing the project, analyzing your sources, and generating reports.

To convert your files using Alchemist, follow these steps. You can start with a single file, a folder, or even the root folder containing all your sources. However, you should strive to eventually convert the whole set of sources in one run. The output will be generated in the target dialect specified by the -t option.

Organize your project space

We recommend sitcking to the standard usage pattern. Read before proceeding.

Converting a Single File or Folder

  1. Make sure you've configured alchemist
  2. Open the command prompt or terminal.

  3. Run the following command to convert a single file or folder:

    alchemist convert -p project_name -t target_dialect -o /path/to/output/folder path/to/a/file_or_folder
    • Replace project_name with a unique name for your conversion project.

    • -t target_dialect specifies the target dialect to use for conversion. You can choose from the following supported dialects:

      • dbr (Databricks)
      • prophecy (Prophecy)

    Note

    There is no need to append .exe to the alchemist command on Windows. It should work as shown.

  4. If the conversion is successful for a single file, you can proceed to convert a folder or the root folder containing all your sources.

Working with AST

In order to apply advanced configuration, especially to create code patterns and templates, you will need to explore the AST structure. You can find more information in the AST section.

Troubleshooting

If you encounter issues, follow these tips:

Installation issues

If you can't install Alchemist, please contact us.

Invalid value for '-o' / '--output-path': Directory is not readable

In macOS Catalina and later versions, restricted folders include Documents, Desktop, Downloads, among others. To solve this issue, you need to grant Terminal access to these folders through privacy settings.

Granting Terminal Access

Follow these steps to allow access to the folder:

  1. Open System Preferences on your Mac.
  2. Go to Security & Privacy.
  3. Select the Privacy tab.
  4. Scroll down to Files and Folders or Full Disk Access (depending on your macOS version).
  5. Look for the Terminal application (or the terminal you are using, such as iTerm) in the list.

  6. Check the box next to it to grant access. If the application is not listed, you can add it by clicking the plus sign (+) and locating it in Finder.

  7. Source skipped due to errors: Alchemist may report various errors during execution. Most of them will provide necessary information to resolve the issue, e.g. incorrect configuration or invalid input file. However, some source files may be skipped due to unexepected errors. If some files were skipped - most probably they were not supported by Alchemist, it will not impact the results for the remaining ones. Please, report this and we'll work on adding support for them.

App freezes

In rare cases, some source files may freeze the process. You may try to identify these and remove from sources and run operation again. If you can't identify the problematic files, please contact us.

Execution crashes or takes too much time

If you have hundreds or even thousands of files, you may run out of memory or the output may be too large. In this case, you can:

  • Run in smaller chunks, i.e. running alchemist multiple times, each time providing a different set of input files or folders. Remember to use a different project name after the -p option on each run.
  • Use a different output format, such as -f parquet.

Command not found

If typing alchemist doesn't work (program not found), make sure you've finished our tutorial. Use the full path to the executable. For example, on Windows:

```
C:\Program Files (x86)\Alchemist\Alchemist\alchemist.exe analyze src -p project_name -f xlsx path/to/a/file_or_folder
```

Remember to consult the built-in help (alchemist -h or alchemist <command> -h) for the most up-to-date information on using Alchemist CLI. For more information on how to use Alchemist, refer to the usage page.