Pirka highlights source code syntax in EPUB books


  • Highlights synatax in EPUB files

  • Extracts <code> elements from EPUB files and asks you which programing language they are, and then uses them to highlight

  • Downloads shared code and language information from Git repository


Highlighting source code syntax in EPUB books

$ pirka path/to/book.epub

It’s a short cut to:

$ pirka highlight path/to/book.epub

To highlight books, run pirka update(see below for details) just after installation because pirka highlight requires library files.

Detecting source code from EPUB books

$ pirka detect path/to/book.epub
Detecting code from "Book Title"
Library file was saved to:

library.yaml here includes:

  • location of <code> element(expressed by EPUB CFI but you don’t need to undarstand it.)

  • language field with blank value

  • file path in EPUB file(zip archive)

  • source code


  epubcfi(/6/64!/4/2/30/2):              # location
    language:                            # language name. blank at first
    item: OEBPS/text/p-003-003.xhtml     # file path in zip archive
    code: |                              # source code
      f1 = open("|cat", "w")
      f2 = open("|sed 's/a/b/'", "w")
      f1.print "Hello\n"
      f2.print "abc\n"

In Pirka context, the file is called library.

pirka highlight command determines programming languages of source code according to this file. Read source code, determine languages, write it at language field, remove code field, and then you can highlight the EPUB file by pirka highlight.

You also determine languages interactively. Set -i(--interactive) option:

$ pirka detect -i path/to/book.epub

Updating libraries

$ pirka update

Pirka provides official library files for some EPUB books as Git repository( pirka update command fetches the files from the repository and you benefit from it.

Additionally, you can host library files by your own and make Pirka recognizes it by configuration file. See later section for that.

Listing supported books

$ pirka lib

pirka lib command lists books Pirka can highlight with:

  • Release Identifier(special identifier for EPUB books)

  • location of library file

  • title

  • some other metadata


Pirka can be configured by environment variables, config file and command-line options.

Environment variables


Affects directory to save library files.
Library files are saved to $XDG_DATA_HOME/pirka/local
The directory is used to search library, too.
Default: $HOME/.local/share


Affects directory to search library files.
You can specify multiple directory by seperating with a colon like XDG_DATA_DIRS=/dir1:/dir2.
/dir1/pirka/local and /dir2/pirka/local are used to search library, for example.
Default: /usr/local/share:/usr/share


Affects directory to search and save config file.
$XDG_CONFIG_DIRS/pirka.yaml is recognized as config file.
Default: $HOME/.config


Affects directory to search config file.
You can specify multiple directory by seperating with a colon like XDG_CONFIG_DIRS=/dir1:/dir2.
/dir1/pirka.yaml and /dir2/pirka.yaml are searched as config file.
Default: /etc/xdg

Config file

Config file is a YAML file. Properties below are recognized:


Directory to save and search library files.
Default: $XDG_CONFIG_HOME/pirka/local


Directories to search library files.
Expressed by sequence(array).
Default: []


Git repository URIs used by pirka lib command.
Expressed by sequence(array).
Default: []

Command-line options

You can configure Pirka by pirka command’s global options:

-c, --config=FILE

Path to config file.
Default: $HOME/.config/pirka.yaml

-s, --data-home=DIRECTORY

Same to config file’s data_home property.

-d, --directory=DIRECTORY

Same to config file’s additional_directories property.
Able to multilpe times.

You can also see help by

$ pirka --help
Pirka highlights source code syntax in EPUB files

Usage: pirka [global options] [<command>] [options]

Global options:
    -c, --config=FILE                Config file. Defaults to /Users/ikeda/.config/pirka.yaml
    -s, --data-home=DIRECTORY        Directory to *SAVE* library data
    -d, --directory=DIRECTORY        Directory to *SEARCH* library data.
                                     Specify multiple times to add multiple directories.

    highlight        Highlights source code in EPUB file
    detect           Detects source code from EPUB file and generate library file
    update           Update library files by remote files
    lib              Show library infomation
If command is ommitted, highlight is used with no option


  • Ruby 2.2 or later

  • C compiler to compile Nokogiri gem


$ gem install pirka

Make faster

By default, Pirka uses archive-zip gem, a pure Ruby implementation, for zip archive but you can make command execution faster by using Zip/Ruby gem, a C implementation. Just install Zip/Ruby:

$ gem install zipruby

Pirka, actually internally-used EPUB Parser, tries to load Zip/Ruby and use it if available.

Copyright (c) 2017 KITAITI Makoto

See COPYING for details.