View on GitHub

PrimCom

manage and access your personal knowledge base easily

Download this project as a .zip file Download this project as a tar.gz file

PrimCom

PrimCom is a personal knowledge base manager, primarily made for programmers. It is meant to be running in a terminal, thus you can access and consult it quickly while working.

Motivation

There are lots of code snippets that I use often but I couldn't reproduce them easily by heart. When I need such a piece of code, either I look it up on my blog (if I had written about it), or Google it. When I see the code, I remember it and I can modify it to my needs. However, looking up something on the Internet can take time (at least 30-60 seconds).

With PrimCom you can collect your own code snippets with your own examples. You can assign tags to them and find them easily later. PrimCom can perform two main actions: print the content of a file, or open a web page.

PrimCom has several useful features. It has tab completion; it can copy the content of a file to the clipboard; it can syntax highlight your code snippets; it even has a built-in radio player, etc. See the built-in help for a detailed list.

Quick start

Open a terminal with dark background and launch PrimCom:

$ ./h.py

If you prefer light background, use the light() command or modify directly the config.py file.

Type h for help, d for the list of available tags.

Screenshots

With dark background: dark background

With light background: light background

Requirements

The project was developed under Ubuntu GNU/Linux with Python 2.7. It is suggested that you install the following packages (via apt-get):

Details

The description above should be enough to get started. Now let's see the details...

Starting PrimCom

Here I suppose you extracted PrimCom to your HOME directory in this folder: ~/primcom. Enter this directory and launch h.py or start.sh:

$ cd
$ cd primcom
$ ./h.py

Another way is to call it from a shell script. To avoid problems, the launcher script should enter ~/primcom:

# ~/bin/h
cd ~/primcom
./h.py

I call the script h and it's in my ~/bin folder (where ~/bin is in my PATH). This way I can launch PrimCom from anywhere with the command h.

[The project's first name was "Help Project", hence the file name h.py. Later I renamed it to PrimCom.]

Quit

CTRL+C and CTRL+D work. With q you can step back one level (if you are on the main level, you will quit from the application). The command qq terminates the application whichever level you are on.

Basic usage

OK, now we have PrimCom running. With h you can access the built-in help. The most important command is d (from the word "dir") that lists all the tags. PrimCom treats two kinds of entries: (1) a note (code snippet), that is stored in a file, and (2) a link to a webpage. In the list of tags, the two kinds of entries are numbered with different colors. The "..." at the end of a tag means that this tag is assigned to at least two entries, thus you will have to select from an interactive list.

When you enter the number of a tag in the prompt, you will get the corresponding entry. It can be the content of a file, or you can be redirected to a webpage if it was a link. File contents are syntax highlighted according to the file's extension.

At the prompt you can enter keyword(s) too. Try for instance "url". You will get a list of entries that contain the given keyword(s). Select a number to get the content of the entry.

Database

At this point you may wonder where and how the entries are stored. They are in the data folder and they are categorized. For instance, python.json contains the description of the entries that are stored in the python folder. The descriptions are in JSON format and they look like this (sample):

"ed50c8b6773a92bf0632c6d4": {
    "doc": "remove a substring from the end of a string",
    "meta": {
        "date": "20130802_002744"
    },
    "action": [
        "cat",
        "python/strip_end.py"
    ],
    "tags": [
        "rstrip",
        "lstrip"
    ],
    "extra": []
}

The file urls.json contains the webpage links and it has no corresponding subfolder. Do not rename this file, its name is hardwired in the source.

Do not edit these JSON files manually if you want to add a new entry. There is a dedicated script for this task, see the next subsection.

Adding a new entry

If you want to add a new entry, launch the command add(). PrimCom has tab completion too, thus you can type ad<TAB>. It will launch the script add_item.py:

Let's see a concrete example. We want to create a new category for C++ and we want to add the classic "hello world" example:

pc> add()
doc: hello world in C++
action: (c)at or (o)pen_url [c/o]? c
Choose category:
[1] python
[2] text
[3] shell
[n] new...
[q] quit
~~> n
New DB: cpp
  filename: hello.cpp
tags: hello world
# added to cpp.json
# data/cpp/hello.cpp touched
Do you want to edit data/cpp/hello.cpp [y/n] (default: yes)?

Editing an entry

While using PrimCom, you may want to edit the description of an entry and/or the content of a file. For this you don't need to quit PrimCom. First select the entry, i.e. print it to the screen. Then you can use these commands:

Alternatives: this.edit(), this.jet().

Editing the whole JSON file

In the previous subsection we saw how to edit the JSON description of an entry. But what if you want to view/edit the whole JSON database?

Again, select an entry, i.e. print it to the screen. Then use one of these commands:

Example: you selected "1", which is in "python.json". Thus, "json.edit()" will open "python.json" for editing.

Entry info

When you have lots of tags, you may forget what entries they mean. In this case you can print the JSON description of an entry with the command <NUM>.json, e.g. 3.json.

Copy to clipboard

If you collect your code snippets with PrimCom, you might want to copy them to the clipboard. When you selected an entry, you can use these options:

You can also have such code snippets that you always want to copy to the clipboard. You print its content and you copy it immediately. It would be nice to say "whenever I select this entry, copy its content to the clipboard automatically". Well, you can do that. Here is an example:

"597060835b6c50deb39b819f": {
    "doc": "wordpress: python sourcecode tag",
    "meta": {
        "date": "20130604"
    },
    "action": [
        "cat",
        "text/wordpress_sourcecode_python.txt"
    ],
    "tags": [
        "wp"
    ],
    "extra": [
        "cb()"
    ]
}

Notice the "cb()" command in the "extra" list.

Follow URLs

Some textual entries may include URLs. It would be great if you could visit them easily. Well, you can. Just use the command links() and select the URL you want to open.

Light background, dark background

You can adjust the colors of PrimCom to light background and dark background with the commands light() and dark(), respectively. The default is dark, but you can change it easily in config.py.

Special commands

The list of special commands can be listed with commands():

pc> commands()
Available commands:
-------------------
pymotw:     - open on PyMOTW, e.g. pymotw:atexit
go:         - Google search list
go1:        - open first google hit
imdb:       - open on IMDb
youtube:    - open on YouTube
wp:         - open on wikipedia
lib:        - look up in Python 2 Standard Library
lib3:       - look up in Python 3 Standard Library
shorten:    - shorten URL

General form: <command>:<keyword(s)>, e.g. imdb:star wars V.

Some other useful commands:

Radio

You can start the radio with the command radio(). Just select a channel. You can stop the current channel with mute(). Quitting PrimCom shuts down the radio.

Pid checker

It can happen that you launch a program that takes too much time to finish. You don't want to sit next to your machine but you would like to get some audio notification when the program is done. PrimCom's pid checker can monitor a process and play a sound when the process terminates.

Example: launch the command "yes" in a terminal window. In PrimCom execute the command pid(). Press "2" to adjust the audio volume. With "ps" list processes and find out the PID of "yes". Say it's 5219 (it will be different in your case, thus use your own value). With "m" you can always print the mini menu. Start monitoring "yes" with the command "add:5219". With "d" you can list the monitored processes. Now stop "yes" in the other terminal. A few seconds later you should hear the audio alert. Under Ubuntu you should also see a notification in the top right corner of the screen.

Project structure

Now let's see the structure of the project:

Related work

Contact

PrimCom was written by Laszlo Szathmary, alias Jabba Laci, 2013. You can contact me at jabba.laci@gmail.com. Feedbacks are appreciated.