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:

With 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):

python-pygments (syntax highlighting)

xsel (copying to the clipboard)

mplayer2 (radio)

python-psutil (process manipulation; or: pip install psutil)

python-requests (or: pip install requests)

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 long hexa number is a unique ID and it is generated automatically

doc: a short textual description of the entry

meta/date: creation date and time (old: yyyymmdd ; new: yyyymmdd_hhmmss )

; new: ) action: it can be "cat" (print the content of the given file), or "open_url" (open a webpage)

tags: list of tags

extra: extra operations. There is only one operation implemented here (" cb() "), which copies the content of a file to the clipboard right after it was printed to the standard output.

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 :

doc: give a short description

action: do you want to print the content of a file or open a URL?

If you chose "c" (cat), then select a category or create a new category. Then provide a filename (just a filename without any path).

If you chose "o" (open_url), enter the URL.

tags: provide one or more keywords, separated by comma

At the end you can open the file and fill its content.

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:

edit() : edit the content of the file

: edit the content of the file jet() : edit the JSON description ("jet()" stands for "json edit this"). If you chose this one, then DO NOT MODIFY the long hexa ID!

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:

json.view()

json.edit()

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:

cb() : copy the content of the file to the clipboard

: copy the content of the file to the clipboard gedit() : open the file with gedit, then copy just a part of it from gedit and paste it wherever you want

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:

myip() : your public IP address

: your public IP address reddit() : open your favourite subreddit easily

: open your favourite subreddit easily conferences() : for browsing Python conferences

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:

h.py : main file

: main file edit.sh : edit h.py ; start.sh : launch h.py

: edit ; : launch add_item.py : add a new item. It can be launched from PrimCom too with the command add() .

: add a new item. It can be launched from PrimCom too with the command . config.py : configuration file. Editor, colors, etc. can be customized here.

: configuration file. Editor, colors, etc. can be customized here. assets dir.: static files (audio, logo, etc.)

dir.: static files (audio, logo, etc.) data dir.: databases are here

dir.: databases are here lib dir.: own and 3rd party libraries

dir.: own and 3rd party libraries modules dir.: extra features of the application (radio, pid checker)

dir.: extra features of the application (radio, pid checker) tmp dir.: database backups. Do not delete this directory.

Related work

cheat: It was designed to help remind *nix system administrators of options for commands that they use frequently, but not frequently enough to remember.

Contact

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