HyperSheetsPreprocessor - Documentation

HSPP DOCUMENTATION

Important note
Minification
Executable arguments
Configuration file
1. Header [general]
2. Header [css]
  1. List settings
  2. Boolean settings
PHP include file
Minification "on the fly"

IMPORTANT NOTE:

If some functionality doesn't work properly for you, disable it within the configuration file
and report a bug.

Be careful of using attribute selectors on id and class attributes, when using id and class minification.

HSPP should work correctly with UTF-8 encoding and encodings, which are a subset of it.
Also 8-bit encodings such as ISO 8859-x and windows-125x should not cause problems.

HSPP currently does not support source mapping.

Minification

Whitespace

All optional whitespace characters will be removed.

Numbers

Leading and trailing zeros will be removed.

Examples:

000.500 ➔ .5

001.000 ➔ 1

Scientifical notation will be used where possible (only if the number will get shorter).

Examples:

100000 ➔ 1e5

1230000 ➔ 123e4

10 ➔ 10 (not 1e1!)

100 ➔ 100 (not 1e2!)

Colors

Hex colors will be shortened where possible

Examples:

#aabbcc ➔ #abc

#aabbccdd ➔ #abcd

rgb() and rgba() functions will be rewritten as hex color.

Examples:

In case alpha channel is not set or is set to 100%, each of

rgb(51, 102, 153)

rgb(20%, 40%, 60%)

rgb(51, 102, 153, 1)

rgb(20%, 40%, 60%, 1)

rgb(51, 102, 153, 100%)

rgb(20%, 40%, 60%, 100%)

rgb(51 102 153)

rgb(20% 40% 60%)

rgb(51 102 153 / 1)

rgb(20% 40% 60% / 1)

rgb(51 102 153 / 100%)

rgb(20% 40% 60% / 100%)

will result in #369.

In case use_rgba_hex_notation is disabled and alpha is < 100%, each of

rgb(51, 102, 153, 0.5)

rgb(20%, 40%, 60%, 0.5)

rgb(51, 102, 153, 50%)

rgb(20%, 40%, 60%, 50%)

will result in rgb(51,102,153,.5)

and each of

rgb(51 102 153 / 0.5)

rgb(20% 40% 60% / 0.5)

rgb(51 102 153 / 50%)

rgb(20% 40% 60% / 50%)

in rgb(51 102 153/.5).

In case use_rgba_hex_notation is enabled and alpha is < 100%, each of

rgb(51, 102, 153, 0.5)

rgb(20%, 40%, 60%, 0.5)

rgb(51, 102, 153, 50%)

rgb(20%, 40%, 60%, 50%)

rgb(51 102 153 / 0.5)

rgb(20% 40% 60% / 0.5)

rgb(51 102 153 / 50%)

rgb(20% 40% 60% / 50%)

will result in #3366997f.

The minification behavior for the rgb() and rgba() functions is the same.

Selectors, custom properties, animation names

Id and class selectors, custom properties and animation names will be minified, if the corresponding settings are enabled (minify_ids, minify_class_names, minify_custom_properties, minify_animation_names).

Attribute selector values will get unquoted where possible.

Keyframes selectors will be minified.

Examples:

#some-id {...} ➔ #a{...}

.some-class {...} ➔ .a{...}

--some-color: #abc ➔ --a:#abc

color: var(--some-color) ➔ color:var(--a)

@keyframes fade-in {...} ➔ @keyframes a{...}

animation-name: fade-in ➔ animation-name:a

input[type="text"] {...} ➔ input[type=text]{...}

from {...} ➔ 0%{...}

100% {...} ➔ to{...}

The names created by the name generator consist of lowercase/uppercase letters and digits where the first character is always a letter.

Empty rules

If remove_empty_rules is enabled, empty rules will be removed.

Empty rule example:

.some-class > img { }

Executable arguments

--help
Show help.
--config-info
Show current configuration.
--create-config-file
Create configuration file with default settings.
--config-file

Set the configuration file path.

Example Linux:
./hspp --config-file "/path/to/config/file/hspp.ini"
Example Windows:
hspp --config-file "C:\path\to\config\file\hspp.ini"
--stdo
Output to the standard output instead of a file.
-i
Set absolute input file path. If input_working_directory is set, this has to be a relative path.
-o
Set output directory path. If output_working_directory is set, this has to be a relative path.

To prevent accidental overwriting of your original files, the output path must not be included in the input path. Though if such a case occur, HSPP will not carry out any processing and will issue an error.

However, it is highly recommended to make a backup copy of your input data!

Configuration file

Initially there is no configuration file provided with the executable. If there is no configuration file within the directory where the executable is located, HSPP will use default configuration.

To show current configuration, use argument --config-info.

To create a configuration file with default settings, pass --create-config-file argument to the executable. The configuration file will be created into directory in which the executable file of HSPP is located.

Also use this option to reset the configuration file to defaults, if it already exists.
If the configuration file already exists, HSPP will ask you to confirm the overwriting of the existing file.

The configuration file is subdivided into sections, which contain configurable options. Each section begins with a header. Options following each header belong to this header. For example all options which follow the header [general] belong to this header, until the next header or the end of file is reached.

Comments

# starts a comment, which ends at the end of line.

Comments are skipped when reading the configuration file (i.e. not evaluated as configuration data). Comments can be used to describe the configuration. But they are also useful, if you want to temporarily disable or switch to another data for an option but keep the data for later use.

The comment character can be used on any position in the configuration file. Consequently any file/directory paths may not contain this character, because the path string will not be read completely. This behavior might change in future versions of HSPP by using quoted strings.

Header `[general]`

List settings

Accepted values: File extensions separated by space (including leading dot)

css_file_extensions
Configure file extensions for files to minify.

String settings

input_working_directory
Input working directory. If this is set, the input file path has to be a relative path.
output_working_directory
Output working directory. If this is set, the output path has to be a relative path.
input_path
Absolute input file path. If input_working_directory is set, this has to be a relative path.
output_path
Absolute output directory path. If output_working_directory is set, this has to be a relative path.

This paths will be used, if no paths are passed through the command line. Corresponding command line options -i and -o, when used, will override path settings of the configuration file.

php_id_array_name
Array name for ids used in the PHP include file
php_class_array_name
Array name for class names used in the PHP include file
php_cprop_array_name
Array name for custom property names used in the PHP include file
php_animation_array_name
Array name for animation names used in the PHP include file

The last four settings are only significant if create_php_include_file is enabled.

Boolean settings

Accepted values: on / off

create_php_include_file
Create a PHP include file containing the replacement information for ids, class names, custom property names and @keyframes animation names.
use_utf8_bom
If this is enabled, UTF-8 BOM will be written. @charset rules will be removed. If the @charset rule defines another encoding, HSPP will prompt you to either remove the @charset rule or not to write UTF-8 BOM.

Header `[css]`

List settings

Accepted values: Terms separated by space

comment_terms
Comments containing this terms will not be removed also if remove_comments is enabled. To remove all comments, this list has to be empty.

Boolean settings

Accepted values: on / off

include_external_stylesheets
Replace @import rules with the contents of a file pointed to by the rule. If the @import rule has a list of media queries, the content in the output will be wrapped by a @media rule which expressions contain this media queries.
remove_comments
Remove comments. Comments containing terms defined in comment_terms, will not be removed.
minify_numbers
Try to minify numbers.
minify_colors
Try to minify colors.
rewrite_angles
Try to minify angles.
use_rgba_hex_notation
Use RGBA hexadecimal notation.
Example: #aabbccdd / #abcd
minify_ids
Minify ids.
minify_class_names
Minify class names.
minify_custom_properties
Minify custom property names.
minify_animation_names
Minify animation names.
rewrite_functions
- Rewrites hsl() / hsla() functions to rgb() / rgba() functions or hexadecimal color notation. The generated result depends on option use_rgba_hex_notation.
- Tries to rewrite linear-gradient() function so that it will get shorter without changing the resulting gradient.
  Only linear-gradient() functions using percentage color stops are handled.
remove_empty_rules
Remove rules which do not have any content.
merge_media_rules
Merge @media rules with same expressions.

PHP include file

If the setting create_php_include_file and at least one of minify_ids, minify_class_names, minify_custom_properties, minify_animation_names are enabled, a PHP include file will be created within the output directory.

Example of PHP include file content:

${php_class_array_name} = array( '[initial-name]' => '[replacement-name]', 'some-class-1' => 'a', 'some-class-2' => 'b', 'some-class-3' => 'c', ... );

Including PHP include file:

include 'hspp.php';

Using name arrays inside including file:

while (...) { echo '<div class="'.${php_class_array_name}['initial-name'].'">...</div>'; }

Minification "on the fly"

If you have root access to your server, you can let HSPP minify your stylesheets "on the fly".

With PHP this can be achieved using execution operator (backticks) and exec() or shell_exec() functions.

Example of using execution operator on unixoid system:

echo `./hspp -i/path/to/some/file.css --stdo`;

Last updated: March 4th, 2023

Data Protection Declaration

Minification

Whitespace

Numbers

Colors

Selectors, custom properties, animation names

Empty rules

Executable arguments

Configuration file

Comments

Header [general]

List settings

String settings

Boolean settings

Header [css]

List settings

Boolean settings

PHP include file

Minification "on the fly"

Header `[general]`

Header `[css]`