Skip to content

Configuring Export Name Format

Jump to bottom
Andrew Glick edited this page Jan 16, 2024 · 3 revisions

Configuring Export Name Format

Starting in v1.0.0, OpenSCAD for VS Code has the ability to customize file name when exporting by changing the openscad.export.exportNameFormat configuration.

Configurations

Configuration Description
openscad.export.exportNameFormat Specifies the file name in quick exports and save dialogs.
openscad.export.skipSaveDialog When enabled, the standard action of Export Model will automatically export a file based on the configuration openscad.export.exportNameFormat without a save dialog.
Note: that when this option is enabled, the save dialog can still be opened by alt + clicking the Export Model button. Also, the save dialog can always be accessed by running Export Model with Save Dialog through the command palette.
openscad.export.saveDialogExportNameFormat Behaves likeopenscad.export.exportNameFormat but only for save dialogs. Empty by default and falls back toopenscad.export.exportNameFormat. This is useful if you want to use a different exportNameFormat for quick exporting than in save dialogs.

Note: Prior to v1.3.0, these settings had different names. (See #58 for more details).

Reference Variables

Auto Naming uses a list of predefined variables, mostly based on those used in VS Code's tasks.json file. Note: a full list of those variables can be found here: https://code.visualstudio.com/docs/editor/variables-reference.

A full list of supported variables used for auto exporting can be found below. Note that the "current open file" refers to whichever file is being exported. This file may not be open if an export is initiated through a context menu.

  • ${workspaceFolder} - The path of the folder open in VS Code
  • ${workspaceFolderBasename} - The name of the folder opened in VS Code without any slashes(/)
  • ${file} - Full path of the current opened file
  • ${relativeFile} - The path of the currently open file relative to workspaceFolder
  • ${relativeFileDirname} - The current opened file's dirname relative to workspaceFolder
  • ${fileBasename} - The current opened file's basename
  • ${fileBasenameNoExtension} - The current opened file's basename with no file extension
  • ${fileDirname} - The current opened file's dirname
  • ${fileExtname} - The current opened file's extension. This will (probably) always be .scad
  • ${exportExtension} - The file extension used in the export, e.g. stl, png, etc. Note: Does not include the .
  • ${date} - The current date in ISO 8601 format, e.g., 2023-12-31. See below for customized formatting
  • ${#} - Auto versioning placeholder. Starts at '1' and increments each time you export a file, keeping old versions and preventing accidental overrides.

Default Format

The default export format is: ${fileBasenameNoExtension}.${exportExtension}

However, you may also like: ${fileBasenameNoExtension}_${#}.${exportExtension} or Exports/${fileBasenameNoExtension}_${#}.${exportExtension}

Auto-Versioning

The auto-versioning placeholder, ${#} can be used to keep track of versions and prevent accidental overrides of exported files. When exporting using the auto-versioning placeholder, the extension will first scan all the files in the directory where the file will be exported to. Then, it will replace ${#} with the next largest available number as to not conflict with the file name or extension.

Auto-Versioning Example

Suppose that you export the file: myModel.scad, using the export format:

"openscad.export.exportNameFormat": "${fileBasenameNoExtension}_${#}.${exportExtension}"

The first time myModel.scad is exported to a stl file, it would be named: myModel_1.stl. The next time the model is exported, it would be named myModel_2.stl, and so on.

Date formatting

New in v1.3.0

The ${date} variable can be used to include the current date in the file export. By default, this is in ISO 8601 format, e.g., 2023-12-31, but can be customized by specifying ${date:FORMAT}, where the format uses Luxon tokens.

Examples

Format Result
${date} 2023-12-31
${date:yyyy-LL-dd} 2023-12-31
${date:LLL-dd HH-mm Dec-31 13-47

Note: Any / or : in the date string will automatically be replaced with _

A full example configuration might look like:

"openscad.export.exportNameFormat": "${fileBasenameNoExtension}_${date:LLL dd, yyyy}.${exportExtension}"

Where the file myModel.scad would be exported as myModel_Dec 31, 2023.stl.

File-Level Configuration

New in v.1.3.0

openscad.export.exportNameFormat can be specified on a per-file basis. To enable this, simply add a comment in your .scad file:

// exportNameFormat=${fileBasenameNoExtension} with_a_custom_format.${exportExtension}
cube(10);

This will export myModel.scad as myModel with_a_custom_format.stl, regardless of how openscad.config.exportNameFormat is configured.

Note: openscad.config.saceDialogExportNameFormat will take priority over the file-level exportNameFormat in save dialogs.

Planned Features

Here's a list of planned features for exporting files. There's no set time for when these will be implemented as features.

  • Configuration for a unique export format on a per-file extension basis (e.g., different export name formats for .stl, .png, etc.)
  • Add support for ${var:VAR_NAME} variable to include local variables in file name

Clone this wiki locally