Home

Awesome

Gitter

<p> <h2 align="center"> OpenBookStore </h2> <h3 align="center"> Book management software </h3> </p> <p align="center"> <a href="https://github.com/OpenBookStore/openbookstore"><b>Homepage</b></a> | <a href="https://gitlab.com/MyOpenBookStore/openbookstore/issues"><b>Issues</b></a> | <a href="https://gitter.im/openbookstore-developers/community?utm_source=share-link&utm_medium=link&utm_campaign=share-link"><b>Gitter chat</b></a> | <a href="https://github.com/sponsors/vindarel"><b>Support us!</b></a> | <a href="https://ko-fi.com/vindarel"><b>Buy me a coffee!</b></a> | <a href="/README_fr.md">Français</a> </p>

In development. Starts being testable.

Command line interface and web UI to search for books, add them to your stock, sell, see the history, etc.

<!-- markdown-toc start - Don't edit this section. Run M-x markdown-toc-refresh-toc -->

Table of Contents

<!-- markdown-toc end -->

Installation

Download a binary (WIP)

Download the standalone executable from here (warn: beta).

It's a 24MB self-contained executable (for Debian Buster GNU/Linux, x86/64 platform). You don't need to install a Lisp implementation to run it. Unzip the archive and run openbookstore from the bin/ directory.

There is a system dependency to install. On Debian: apt install sqlite3

Run from sources

Alternatively, install sbcl with your package manager:

apt install sbcl rlwrap

install Quicklisp, the Lisp library manager (full instructions):

curl -O https://beta.quicklisp.org/quicklisp.lisp && sbcl --load quicklisp.lisp --eval '(quicklisp-quickstart:install)' --eval '(ql:add-to-init-file)' --quit &> /dev/null
rm quicklisp.lisp

clone the repository:

git clone https://gitlab.com/myopenbookstore/openbookstore.git

Then, to run the software, you have 2 options: build a binary or run it from sources.

Running it

Web UI

To run the web application:

./bin/bookshops -w [--port 4242] [--verbose]

To create a user with admin rights, run:

/bookshops --manage createsuperuser

and follow the prompt.

make run

aka rlwrap sbcl --load run.lisp. You can set the port with the environment variable OBS_PORT (defaults to 4242).

Quit with C-d.

(openbookstore/web:start-app :port 4242)

Command line

We can run OpenBookStore without a graphical interface.

We can use it to search for books data on internet sources:

$ ./bookshops search terms

see --help for the available options.

Readline interface

We can use OpenBookStore with a simple readline-based terminal interface.

Get a readline interactive prompt with the -i flag:

$ ./bookshops -i
bookshops >

See the available commands with help, the documentation of a given command with help <cmd> (see help help, use TAB-completion).

At any moment, quit the current prompt with C-d (control-d) or use:

To search for books on the internet sources, use search:

Lisp REPL

We can start OpenBookStore from a Common Lisp REPL, from our preferred editor, and modify it on-the-fly. The editor can be Emacs with Slime, Atom with SLIMA, Vim with Slimv, VSCode with Alive etc.

Load the system definition, bookshops.asd, with C-c C-k in Slime,

Load the dependencies: (ql:quickload "bookshops"),

Create the DB: (openbookstore.models::initialize-database)

Create a superuser: (openbookstore.models::create-superuser name email password)

Connect to the DB: (bookshops:init)

then explore commands in bookshops.commands.

You might need to enable terminal colors with M-x slime-repl-ansi-on (see here).

Run at startup with Systemd

In a new /etc/systemd/system/openbookstore.service:

[Unit]
Description=OpenBookStore

[Service]
Restart=on-failure
WorkingDirectory=/home/you/path/to/repository
# We run the binary: (absolute path)
ExecStart=/home/you/path/to/repository/openbookstore --web --port 4242
User=openbookstore  # or an existing user
Type=simple
Restart=on-failure

[Install]
WantedBy=multi-user.target  # start at reboot.

start it:

systemctl start openbookstore.service

to see the logs:

journalctl -u openbookstore.service [--since today] [--no-pager] [-o json-pretty] [-f]

use -f to follow the logs as they are written.

Usage

Below is an overview of the available features in the web app and in the terminal interface.

Bibliographic search, adding books to your stock

In the web app, go to the "Search" menu on the left.

You can search anything by keywords or by ISBN (you can scan a book in every search input of OpenBookStore). The search will return the required bibliographic data (title, author(s), publisher, ISBN…) as well as the book's price and the cover image. However, these last two data depend on the datasource you use.

The currently available datasources are:

In addition, for each book found, you will see a little button that tells you if you already have this title in stock, and how many.

Click on the "+1" button to add this book to your stock.

In the terminal interface, use search:

It fetches bibliographic information on online sources and prints a list of results. Add one to your stock:

Or create a book manually:

To cancel the form, use C-d (control-d), or enter nothing in a mandatory field (showed like in web forms with a red asterisk).

See also

What's in a book?

A book has these fields:

Seeing your stock

To search the books you have in stock, use the "Stock" menu in the web app, or use the search input in the top navigation bar.

In the terminal interface, use stock:

This prints a list of results with at most *page-size* elements. Use the two commands for pagination:

To see more information about one book you have in stock:

As with several commands, you can autocomplete the id argument using the TAB key. The choices are the ids displayed on the last stock command, so this can be handy when you have filtered the results.

Selling books, history

In the web app, go to the "Sell" menu.

You can scan any book in the search input that is already selected, and you can search books already in your stock with the keyboard (3 letters are necessary to trigger a search).

Once you're ready, click a payment method button to validate the transaction.

What remains to be done:

History (of sells)

You can find all your sell transactions in the History.

What remains to be done:

Places

Note: we don't encourage the use of multiple places, it only renders your stock management more difficult

When you start the program, you are in the "default place". See that the command prompt displays (default place) bookshops > : it shows the current place you are in.

This current place plays the role of the origin place for the mentioned commands below.

To create a place, use

To change the current place:

To move a book to another place:

See the list of places:

Lending books to contacts

In the web UI, the dashboard shows which loans are outdated (their due date was due before today).

In the terminal app, lend a book to someone like so:

See your contacts, their books and the date they borrowed them:

The same information, but a list of books sorted by date (oldest first):

In both commands, a book that was borrowed more than 60 days is printed in red.

and when your friend returns a book back:

In Lisp, get them with:

(openbookstore.models::loans)
;; and
(openbookstore.models::outdated-loans)

Stats

Get some numbers about your stock:

Settings

The parameters can be changed with set.

The follownig settings currently exist:

High-level goals

Be more useful and easier to install and use than our Abelujo web app.

i18n

This software is available in other languages than english.

See the makefile and i18n-load in utils.lisp.

NOTE: i18n is currently disabled in the released binary.

Dev

We use (our) replic library to build the readline commands from existing Lisp functions: https://github.com/vindarel/replic (which builds on cl-readline).

We use the Mito ORM. See the Cookbook tutorial.

<!-- ## Management commands --> <!-- You can use: --> <!-- - `manage <custom_command>` --> <!-- to run custom commands. --> <!-- And you can see some basic instructions on how to create your own commands --> <!-- on file "src/manager.lisp" -->

TODO

So much.

Testing

To test DB operations, use our macro with-empty-db.

(use-package :openbookstore.models)
(use-package :bookshops-test.utils)

(with-empty-db
   (let* ((bk (make-book :title "inside-test")))
     (save-book bk)))

;;  CREATE TABLE "book" (
;;     "id" INTEGER PRIMARY KEY AUTOINCREMENT,
;;     "datasource" VARCHAR(128),
;;     "title" VARCHAR(128) NOT NULL,
;;     "price" INTEGER,
;;     "date_publication" VARCHAR(128),
;;     "editor" VARCHAR(128),
;;     "authors" VARCHAR(128),
;;     "quantity" INTEGER,
;;     "created_at" TIMESTAMP,
;;     "updated_at" TIMESTAMP
;; ) () [0 rows] | EXECUTE-SQL
#<BOOK inside-test>

Troubleshooting

Translations

make tr takes care of extracting the strings (generating .pot files) and generating or updating (with msgmerge) .po and .mo files for each locale. The .mo files are loaded in the lisp image at compile-time (or run-time, when developing the application).

How to add a new locale?

  1. Add the new locale to the LOCALES variable in the makefile.
  2. Call make tr. This will generate the .po file (and directory) for the new locale.

How to add a translation for an existing string?

  1. Update the .po file for the locale.
    1. Find the msgid that corresponds to the string you want to translate.
    2. Fill the msgstr.
  2. Call make tr to update the .mo file for the locale.

More technical details

Lisp ?!

See also

<!-- - https://github.com/jl2/bookdb/, which searches on isbndb.com (not good enough for us and lacking prices) -->

Licence

AGPLv3