package-resources-cli

Code generator for swift-package-resources

Table of contents

• Installation
• Usage
• Todos
• Alternatives
• License

Installation

1. Add required dependencies to your package

.package(
  url: "https://github.com/capturecontext/package-resources-cli.git", 
  .upToNextMajor(from: "4.0.0")
),
.package(
  url: "https://github.com/capturecontext/swift-package-resources.git", 
  .upToNextMajor(from: "5.0.0")
),

Note

Version update policy

Starting from 4.0.0 semver is only applied to CLI itself:

• major updates are reserved for breaking config or output changes and major dependency updates
• minor updates are reserved for additive changes in config or output
• patch updates are reserved for other updates

PackageResourcesClient is treated as implementation details and changes in it's APIs are not subject to semantic versioning unless it involves changes in CLI behavior

2. Add plugin and target dependency

.target(
  name: "AppUI",
  product: .library(.static),
  dependencies: [
    .product(
      name: "PackageResources",
      package: "swift-package-resources
    )
  ],
  resources: [...],
  plugins: [
    .plugin(
    	name: "package-resources-plugin",
      package: "package-resources-cli"
    ),
  ]
),

Tip

You can skip adding swift-package-resources dependency explicitly if you use exported alias instead:

.product(
     name: "_ExportedPackageResources",
     package: "package-resources-cli
)

it will still work as import PackageResources

Makefile

Make allows you to build and install package-resources-cli globally or locally, if you don't want to use swiftpm plugin

# Download repo
git clone https://github.com/capturecontext/package-resources-cli.git

# Navigate to repo directory
cd package-resources-cli

# Build and install globally using `make install`
# or see Makefile for more options
make install

# You can also delete package-resources-cli using `make uninstall` command

Usage

Supported resource types:

Resource	Extensions	Is reliable
_ColorResource	.xcassets	yes
_FontResource	.ttf .otf	yes
_ImageResource	.xcassets	yes
_SCNSceneResource	.scnassets/.scn	yes
_XCStringResource	xcstrings	yes
_NibResource	.xib	not used/tested
_StoryboardResource	.storyboard	not used/tested

Warning

Fonts require additional setup

For example you want to add Monsterrat and Arimo fonts with different styles

• Download fonts and add them to your resources folder

• Add a static factories for your custom fonts (Example)

• Register custom fonts on app launch (in AppDelegate, for example)

  • UIFont.bootstrap() if you are using code from the example above.

✅ Except of some hectic with fonts, installation is enough for using the plugin with swift-package-resources.

Configuration

Package plugin uses .packageresources file at the root of the package with as it's configuration file

version: "4.0"
output: "<path-to-output-file>"
indentor: "\t"
indent-size: 1
access-level: internal
group-by-catalog: true
numbers:
  separator: "_"
  allowed-delimeters: []
  next-token-mode: inherit
  ending-number-boundary-options:
  - disable-token-processing
  single-letter-boundary-options:
  - disable-separators
  - disable-token-processing
colors:
  group-by-folders: true
  split-by-key-path: true
images: default
fonts:
  ignore: false
nibs:
  ignore: true
scn-scenes:
  group-by-folders: true
  split-by-key-path: true
storyboards:
  ignore: true
xcstrings:
  split-by-key-path: true
acronyms:
  processing-policy: default
  values:
  - id
  - ID
  - Id
  ...

Tip

Use package-specific configs for your defaults and target-specific configs for separate targets, this way it's possible to expose shared resources from your design-system target and allow for local resources in feature targets.

In v4 all resource types are enabled by default. Disable a type with ignore: true in its section instead of using resource-types.

Top-level format keys are shared defaults. Resource sections inherit omitted values from the root config unless the section is set to the default alias, which uses the built-in defaults.

Argument	Description
version	Manifest format version. Current version is 4.0.
output	Path to output file. Default is dynamically calculated as input + /Resources.generated.swift
indentor	Indentation symbol. Default is \t
indent-size	Amount of indentors per indent level. default is 1 default for space/whitespace/" " indentors is 2
access-level	Access level for generated declarations (private, internal, package, public, or none). Default is internal
group-by-catalog	Whether catalog-backed resources are nested under a catalog-name enum. Applies to colors, images, SCN scenes, and xcstrings unless overridden. Default is true
<resource>.ignore	Disables a resource type when true. Resource sections are colors, images, fonts, nibs, scn-scenes, storyboards, and xcstrings. Default is false
<resource>.group-by-catalog	Overrides catalog grouping for one resource section. Supported by colors, images, scn-scenes, and xcstrings.
<resource>.group-by-folders	Groups folders inside asset catalogs into nested enums. Supported by colors, images, and scn-scenes. Default is true
<resource>.split-by-key-path	Splits dotted names/keys into nested enums. Supported by colors, images, scn-scenes, and xcstrings. Default is true
numbers.separator	Separator for numeric values. default is "_"
numbers.allowed-delimeters	Extends allowed characters for numbers, specifying ["."] might be helpful for enabling FloatingPoint numbers, however it's only allowed delimiter, so with this setting "1.2.3_value" will be tokenized as ["1.2.3", "_", "value"] default is []
numbers.next-token-mode	Camel case mode for a token after a number. default is inherit (equivalent to automatic)
numbers.ending-number-boundary-options	Options for numeric boundaries at ending number tokens (disable-separators, disable-token-processing, none, current, default).
numbers.single-letter-boundary-options	Options for numeric boundaries around single-letter tokens (disable-separators, disable-token-processing, none, current, default).
acronyms.processing-policy	See CamelCaseConfig.Acronyms.ProcessingPolicy. default is always-match-case.
acronyms.values	Overrides all default acronyms. default can be found here.

resource-types and group-xcstrings-by-catalog-name are still decoded for v1-v3 manifests. In v4, use resource ignore flags and xcstrings.group-by-catalog.

Command plugin

You can run commands manually using swift package resources

Generate command

swift package resources generate \
  --input "<path-to-lookup-root>" \
  --config "<path-to-configuration-file>" \
  --output "<path-to-output-file>" \
  --indentor "\t" \
  --indent-size 1 \
  --access-level internal \
  --group-by-catalog \
  --no-ignore-colors \
  --no-ignore-images \
  --ignore-nibs \
  --ignore-storyboards \
  --colors-group-by-folders \
  --images-group-by-folders \
  --scn-scenes-group-by-folders \
  --xcstrings-split-by-key-path \
  --numbers-separator "_" \
  --numbers-allowed-delimeters "__package_resources_unspecified" \
  --numbers-next-token-mode inherit \
  --numbers-ending-number-boundary-options default \
  --numbers-single-letter-boundary-options default \
  --acronyms-processing-policy default \
  --acronyms-values "acronym1" "acronym2"

Config init command

Dumps default configuration into a config file at the root of the package

swift package resources config init --format yaml # `json` is also supported
swift package resources config init --force # rewrite config file

Config edit command

Utility for editing config files, overrides specific values in config file

swift package resources config edit \
  --indentor "\s" \
  --indent-size 2

Also can remove specific keys from the config, just pass --remove- prefixed arguments as flags

swift package resources config edit --remove-acronyms-values

Tip

Path to config file can be specified for config commands

swift package resources config \
     --path "<path-to-config-file>" \
     edit --remove-output

Todos

• Improve docs

Tip

You can find docc reference generated by swift-argument-parser here

• Excludes support
• Filesystem expressions support
• Resources validation
• Images optimizations
• Legacy strings support

Alternatives

• swiftgen/swiftgen – Generic codegen
• mac-cain13/r.swift – Codegen for resources
• liamnichols/xcstrings-tool – Localized strings
• Xcode supports generating internal symbols from resources out of the box

License

This library is released under the MIT license. See LICENSE for details.