README.md

# ex_bardecode

Unofficial Elixir NIF for [Softek Barcode Reader Toolkit](http://www.bardecode.com/en1/app/linux/).

NOTE: `test/fixtures/barcode.jpg` should be removed from history if this repository is made public.

## Installation

If [available in Hex](https://hex.pm/docs/publish), the package can be installed
by adding `bardecode` to your list of dependencies in `mix.exs`:

```elixir
def deps do
  [
    {:ex_bardecode, "~> 0.9.0"}
  ]
end
```

Documentation can be generated with [ExDoc](https://github.com/elixir-lang/ex_doc)
and published on [HexDocs](https://hexdocs.pm). Once published, the docs can
be found at [https://hexdocs.pm/ex_bardecode](https://hexdocs.pm/ex_bardecode).

## Usage

Bardecode exposes three functions for reading barcodes from different sources.

- `read_barcode` reads from the specified image file (JPEG or TIFF)
- `read_barcode_from_bitmap` decodes JPEG data from an in-memory binary

```elixir
Bardecode.read_barcode(
  "barcode.jpg",
  %{
    license: "license key",
    type: [:pdf417, :code128],
    multiple: true
  }
)
```

The options map is the same for all three functions.

- `license` string for SoftTek (optional). If no license is specified, the last three characters of barcodes will be replaced with ???. A 30 day license can be obtained from sales@bardecode.com.
- `type` is a list of barcodes to look for. By default it looks for all types, but this is slower than specifying specific types. Valid types are [:codabar, :code39, :code128, :code25, :ean13, :ean8, :upca, :upce, :pdf417, :datamatrix].
- `multiple` will wait to find multiple barcodes if `true`. By default (`false`) it returns as soon as one barcode of any type is found.
- `max_threads` can be used to limit the number of threads used. The default (0) determines the number based on the number of CPU cores available.
- `timeout` is the maximum time in milliseconds, the default is 5000 (more of a suggestion).

## Tasks

| Task            | Description                                         |
| --------------- | --------------------------------------------------- |
| mix compile     | Builds bardecode, downloading the library if needed |
| mix clean       | Removes files created by mix compile                |
| mix test        | Run the test suite                                  |
| mix hex.publish | Publish a new version to Hex.pm                     |

Test under Linux using a Docker container:

```
docker build . -t ex_bardecode
docker run -it ex_bardecode /bin/bash
mix test --trace
```

## Code Layout

| File                    | Description                              |
| ----------------------- | ---------------------------------------- |
| src/bardecode.c         | C code for the NIF                       |
| src/barcode.h           | Header file copied from the library      |
| lib/bardecode.ex        | Elixir function stubs for calling C      |
| test/bardecode_test.exs | Elixir test suite                        |
| Makefile                | For building the NIF using `mix compile` |

## Resources

- Softek Barcode Toolkit documentation included in [the download](http://www.bardecode.com/en1/app/linux/)
- [Erlang Native Implemented Functions](http://erlang.org/doc/man/erl_nif.html) (NIF)
- [Using C from Elixir with NIFs](https://andrealeopardi.com/posts/using-c-from-elixir-with-nifs/)
- [libjpeg](http://ijg.org) download contains an example.c