---
title: Macros
slug: macros
docTags: 
createdAt: 2023-03-08T05:04:01.000Z
---

Macros are defined as name-value pairs, where a value replaces the name during the BarcodeReaderCLI session. This process is called macro expansion. Macros are used:

- Specify names of input and output file/folder names 
- Select data presented in the output.

## Macro format and expansion rules

In most cases, a macro is referenced by its name enclosed in curly brackets: <font color="#eb144c">`{macro.name}`</font> Macro names are case-insensitive. General macro references format is: <font color="#eb144c">`{namespace::macro.name?/format}`</font>

Where:

- <font color="#eb144c">`namespace::`</font>*&#xA0;*- **optional&#x20;**&#x6E;amespace to distinguish macros with the same name defined in multiple categories.
- <font color="#eb144c">`macro.name`</font> - **the required&#x20;**&#x6E;ame of a macro
- <font color="#eb144c">`?`</font> - **optional** mark to expand **undefined** macro to an empty string. Without this mark, an undefined macro causes a runtime error.
- <font color="#eb144c">`|format`</font> - **optional&#x20;**&#x6D;acro expansion control. Available formats:
  - <font color="#eb144c">`#xN`</font> - duplicate macro value N times
  - <font color="#eb144c">`#n` </font>- expands to the name of the macro
  - <font color="#eb144c">`#v`</font> - expands to the value of the macro

### Examples:

<font color="#eb144c">`{tab|#x3}` </font>expands to 3 tab characters

<font color="#eb144c">`{dob?|#n is #v}`</font> expands to a string <font color="#eb144c">`dob is` `user_date_of_birth`</font> , if the current barcode contains driver's license data; otherwise, it expands to an empty string

<font color="#eb144c">`{path.temp}{path.sep}MyOutput.xml`</font>expands to a <font color="#0c121d">`MyOutput.xml`</font> file path located in a temporary folder, e.g.`/tmp/MyOutput.xml`

<font color="#eb144c">`{bc::page}` </font>expands to the page number in a file, where a barcode is located

## Macro categories

### Session macros

The Session macros remain constant in the course of the BarcodeReaderCLI session. The namespace for these macros is <font color="#eb144c">`prg::`</font>.

| **Name**                                    | **Value Description**                                             |
| ------------------------------------------- | ----------------------------------------------------------------- |
| <font color="#eb144c">`path.tmp`</font>     | System temporary folder path (without terminating path separator} |
| <font color="#eb144c">`path.sep`</font>     | Path separator character: \ on Windows, / on Linux                |
| <font color="#eb144c">`host`</font>         | Host computer name                                                |
| <font color="#eb144c">`app.filename`</font> | BarcodeReaderCLI file name                                        |
| <font color="#eb144c">`app.version`</font>  | BarcodeReaderCLI version                                          |
| <font color="#eb144c">`start.date`</font>   | Session start date. Format: YYYY-MM-DD                            |
| <font color="#eb144c">`start.time`</font>   | Session start time. Format: hh\:mm\:ss                            |
| <font color="#eb144c">`nl`</font>           | New line character                                                |
| <font color="#eb144c">`cr`</font>           | Carriage return character                                         |
| <font color="#eb144c">`eol`</font>          | Carriage return + New line characters                             |
| <font color="#eb144c">`tab`</font>          | Tab character                                                     |
| <font color="#eb144c">`bom`</font>          | UTF-8 byte-order mark (BOM)                                       |

### Environment variables

Selected environmental variables are converted to a macro.  The namespace for these macros is <font color="#eb144c">`env::`</font>.

### User macros

The User macros are defined using<font color="#eb144c"> `-d="``macro.name=macro.value"`</font> option on a command line or in the configuration file. The namespace for these macros is <font color="#eb144c">`user::`</font>.
The value of user macros referenced in filename options can reference other user macros (Recursive expansion.)

### Source macros

The Source macros are associated with the currently processed source. The namespace for these macros is <font color="#eb144c">`source::`</font>.


| **Name**                                | **Value Description**                   |
| --------------------------------------- | --------------------------------------- |
| <font color="#eb144c">`path`</font>     | Source path specified on a command line |
| <font color="#eb144c">`type`</font>     | Source type: `file`, `folder`, `url`    |
| <font color="#eb144c">`files`</font>    | Number of files found in the source     |
| <font color="#eb144c">`bc.count`</font> | Total number of found barcodes          |

### File macros

The File macros are associated with the currently processed image file. The namespace for these macros is <font color="#eb144c">`file::`</font>.


| **Name**                                | **Value Description**                      |
| --------------------------------------- | ------------------------------------------ |
| <font color="#eb144c">`path`</font>     | Image file path                            |
| <font color="#eb144c">`filename`</font> | Filename section of path                   |
| <font color="#eb144c">`basename`</font> | Filename without extension                 |
| <font color="#eb144c">`ext`</font>      | The extension portion of the filename      |
| <font color="#eb144c">`folder`</font>   | Path to a folder containing the image file |
| <font color="#eb144c">`pages`</font>    | Number of pages in a file                  |
| <font color="#eb144c">`format`</font>   | Image file format                          |
| <font color="#eb144c">`size`</font>     | Size of image file                         |
| <font color="#eb144c">`bc.count`</font> | Total number of found barcodes             |

### Page macros

The Page macros are associated with the currently processed image page. The namespace for these macros is <font color="#eb144c">`page::`</font>.


| **Name**                                | **Value Description**                       |
| --------------------------------------- | ------------------------------------------- |
| <font color="#eb144c">`page`</font>     | Page number (1-based)                       |
| <font color="#eb144c">`bpp`</font>      | Bits-per-pixel                              |
| <font color="#eb144c">`width`</font>    | Page width in pixels                        |
| <font color="#eb144c">`height`</font>   | Page height in pixels                       |
| <font color="#eb144c">`hdpi`</font>     | Horizontal DPI                              |
| <font color="#eb144c">`vdpi`</font>     | Vertical DPI                                |
| <font color="#eb144c">`compr`</font>    | Page compression                            |
| <font color="#eb144c">`path`</font>     | Path to the image file containing this page |
| <font color="#eb144c">`bc.count`</font> | Total number of found barcodes              |

### Barcode macros

The Barcode macros are associated with the currently processed barcode. The namespace for these macros is <font color="#eb144c">`bc::`</font>.

| **Name**                                        | **Value Description**                                                |
| ----------------------------------------------- | -------------------------------------------------------------------- |
| <font color="#eb144c">`ind`</font>              | Barcode index on a page                                              |
| <font color="#eb144c">`text`</font>             | Barcode text value as UTF-8 string                                   |
| <font color="#eb144c">`data`</font>             | Barcode value as a byte array encoded as base-64 string              |
| <font color="#eb144c">`length`</font>           | Barcode value length                                                 |
| <font color="#eb144c">`type`</font>             | Barcode type                                                         |
| <font color="#eb144c">`rotation`</font>         | Barcode rotation                                                     |
| <font color="#eb144c">`encoding`</font>         | The encoding used to convert barcode data to UTF-8 text              |
| <font color="#eb144c">`tbr`</font>              | TBR code used to read this barcode (not present if code was not set) |
| <font color="#eb144c">`path`</font>             | Image file path                                                      |
| <font color="#eb144c">`abspath`</font>          | Image file absolute path                                             |
| <font color="#eb144c">`page`</font>             | Page number (1-based)                                                |
| <font color="#eb144c">`mod`</font>              | Barcode module size in pixels                                        |
| <font color="#eb144c">`skew`</font>             | Barcode skew                                                         |
| <font color="#eb144c">`rectangle.left`</font>   | The left coordinate of the encompassing rectangle                    |
| <font color="#eb144c">`rectangle.top`</font>    | The top coordinate of the encompassing rectangle                     |
| <font color="#eb144c">`rectangle.right`</font>  | The right coordinate of the encompassing rectangle                   |
| <font color="#eb144c">`rectangle.bottom`</font> | The bottom coordinate of the encompassing rectangle                  |
| <font color="#eb144c">`corners.tl.x`</font>     | X coordinate of the top left corner                                  |
| <font color="#eb144c">`corners.tl.y`</font>     | Y coordinate of the top left corner                                  |
| <font color="#eb144c">`corners.tr.x`</font>     | X coordinate of the top right corner                                 |
| <font color="#eb144c">`corners.tr.y`</font>     | Y coordinate of the top right corner                                 |
| <font color="#eb144c">`corners.bl.x`</font>     | X coordinate of the bottom left corner                               |
| <font color="#eb144c">`corners.bl.y`</font>     | Y coordinate of the bottom left corner                               |
| <font color="#eb144c">`corners.br.x`</font>     | X coordinate of the bottom right corner                              |
| <font color="#eb144c">`corners.br.y`</font>     | Y coordinate of the bottom right corner                              |

### Driver's License macros

The Driver's License macros are associated with the currently processed barcode; it contains driver's license or ID card data. The namespace for these macros is <font color="#eb144c">`dl::`</font>.



| **Name**                               | **Value Description**             |
| -------------------------------------- | --------------------------------- |
| <font color="#eb144c">`last`</font>    | Cardholder family name            |
| <font color="#eb144c">`first`</font>   | Cardholder first name             |
| <font color="#eb144c">`middle`</font>  | Cardholder middle name            |
| <font color="#eb144c">`dob`</font>     | Cardholder's date of birth        |
| <font color="#eb144c">`eyes`</font>    | Cardholder eyes color             |
| <font color="#eb144c">`hair`</font>    | Cardholder hair color             |
| <font color="#eb144c">`sex`</font>     | Cardholder sex                    |
| <font color="#eb144c">`height`</font>  | Cardholder height in ft. and inch |
| <font color="#eb144c">`weight`</font>  | Cardholder weight in pounds       |
| <font color="#eb144c">`street`</font>  | Cardholder street address         |
| <font color="#eb144c">`city`</font>    | Cardholder city                   |
| <font color="#eb144c">`state`</font>   | Cardholder state or province      |
| <font color="#eb144c">`postal`</font>  | Cardholder ZIP or postal code     |
| <font color="#eb144c">`id`</font>      | Card ID number                    |
| <font color="#eb144c">`issued`</font>  | Card issue date                   |
| <font color="#eb144c">`expires`</font> | Card expiration date              |