cdd
For any subject write to tbin@libero.it

Intro: what is cdd?
Download
Well, I don't ask money for the programs I create. But if you want to sustain my work, feel free to donate any amount you can, using the PayPal button down below. In any case, whatever is your decision, go on surfing.

Intro: what is cdd?

cdd is a UNIX tool, written in bash, that scans a textual file (your cd database) for extracting information and data and prints a report in a pretty format. The program has various options to control its behavior and may be customized to some extent.
The package contains the following files:
A brief description. The database is formed by text lines, each containing seven fields:
All fields are separated by a special character (defined in custom.data): by default it's the vertical bar |. Here's an example:
Led Zeppelin|BBC Sessions|V.V.|1997|From studio and live performances|Atlantic|GB|2|
The format is quite unreadable, but it's pure text, and may be altered by any editor.

The simplest usage is cdd <pattern> (look out: all files must reside in the same directory) as in the following example:
$ cdd led
The output will be

Led Zeppelin         BBC Sessions                V.V. 1997  From studio and

(since cdd in case-insensitive, you can type 'led' and view "Led"; cdd has searched through the database and has reported all the lines containing the pattern "led" (it could have been in the title or in the notes, for example). Another useful usage is:
$ cdd -a
this command (-a option, no patterns) simply prints out the whole database in the default view ('a' stands for all). Here's what happens here:

Bruce, Jack          Songs For A Tailor          1969 1997       
Dandy Wharols        The Dandy Wharols           1996 1996   
Led Zeppelin         BBC Sessions                V.V. 1997  From studio and
Pat Metheny Group    Letter From Home            1989 1989     
......
......

The default format is a fixed-size output; there are other views: a plain format in which the separator (|) is changed into a TAB, a framed output, a view suitable for HTTP publishing and a wide field view. Now that you've understood the principles, here's the output of the -h options (h for help):

$ cdd -h
Welcome to the cdd world!
cdd is a compact disc database manager for your musical cd collection.

Usage: cdd [OPTIONS] [pat1] [+|- pat2] [+|- pat3] ...

cdd reads all the content of a textual database (by default $HOME/.cdd/cd.db)
containing your cd collection data, selecting all lines matching pattern [pat1]
(which may contain spaces), formatting output in various friendly ways. The
matching is extended to the whole record by default, but a single field may be
chosen for matching (see option -x). Search is case-insensitive for all options
(except --change, which selects case-sensitive patterns).

Options (<mandatory arguments>, [facultative arguments]):

 -@            select alternative position (pattern-matching or not) records
 -%            select alternative format (pattern-matching or not) records
 -a            select all database entries for output, ignoring patterns
 --add [db]    add records to current or [db] database
 -A            aligned view: main info in fixed-size columns (may trim fields)
 -b            select box-set (pattern-matching or not) records
 -B            in aligned mode (-A), print also country before notes
 -c            report total number of records in the current database
 --copy <db>   copy pattern-matching records from current to <db> database
 --change <f> <old> <new> change occurrences of <old> with <new> in field <f>
 -C            be verbose, i.e. print a report about search results
 -D            in aligned mode (-A), print discs number instead of notes
 --databases   list databases in the system directory
 --delete      delete pattern-matching records from current database
 --dvd         set dvd mode, substituting proper references of 'cd' to 'dvd'
 -e            search for the exact term in the field (use with option -x)
 -f <file>     set <file> as current database file
 -F            framed view: full output (may end in a long listing)
 -G            group view: artist's header, then titles, years (-P add labels)
 -h --help     print this help and exit
 --heal [db]   wizard for correcting -I/-J records on current or [db] database
 -H            http publishing view: wide artist/title, year, label, issue date
 -i            select irregular (pattern-matching or not) records
 -I            select (pattern-matching or not) records without issue date
 -J            select (pattern-matching or not) records with 'unknown' marks
 -K            imply both --single and --keep, which means search 'as-is'
 --keep        disable the alternative search mechanism and keep last search
 -l[c] [num]   list last [num] or 10 log records; -lc for compact output
 --lp          set lp mode, substituting proper references of 'cd' to 'lp'
 -L            list the entire current log file; -Lc for logfile entries number
 -m --modify   modify all fields in pattern-matching records
 --mix         build a cumulative output by searching for each word of pattern
 --move <db>   move pattern-matching records from current to <db> database
 --multi <db>  add database <db> to current pattern-matching search; iterable;
 -n            prefix each line with order-number (-N) or frequency (-o)
 --no-colors   disable output colors (see -T) for all views
 --not         invert risults for options -@/-b/-i/-I/-J/-R
 --notes       print my personal database input notes and exit
 -N            normal view: full unaligned output (may give uneasy listing)
 -o <i>        print only unified and alphabetically sorted fields <i>
 -p <s>        reverse primary or secondary sorting level: see -r/-s/-S
 -P            add label/issue year fields in different guises for each mode
 -q            quiet mode; print only the complete report (enable -C)
 -r            reverse both primary and secondary sorting levels; see -p/-s/-S
 --remove      delete destination file for --move/--copy before action
 --replace <f> replace field <f> with user input on pattern-matching records
 -R <y1>[-y2]  select records (pattern-matching or not) in y1-y2 range of years
 -s <i>        sort output according to selected field <i> as primary key
 --set [inv] <flag> set (or invert) <flag>, where <flag>=box|alt|pos|irr|frm
 --single      disable the secondary search mechanism
 -S <i>        sort output according to selected field <i> as secondary key
 -t            export current database in -A view to a textual file
 -T            disable colors for all views and disable notes in -F/-W views
 -u --usage    print a fast usage help and exit
 -U            print multiple occurrences of title as unique in -G view
 -v --version  print version and exit
 --views       print a brief list of all views and their options
 -w[c]         list pattern-matching records log data; -wc for compact output
 -W            wide view: year, issue, artist, title and indented full notes
 -x <i>        search only in the selected field <i> (see also option -e)
 -X            enable appending [alt-pos]/[box-set]/[alt-frm] (off by default)
 -z <f[,l]>    set <f> and <l> as first and last notes column in -F/-W views
 -Z <char>     set <char> as separator for current database (default is '|')

Options are input in any order, provided arguments follow those needing them.
There is an internal order, in evaluating options that don't do any search 
(-@, -b, -l, -L, -t, -w, -h, -v for instance) so, if set together in the user
input command, only a specific option is applied, not always the last in the
input line.

In particular:

option -c does not expect arguments, but if you type -cc, the net number of
records is printed, so that you could incorporate this to a script.

option -l must be followed by a number, which will be set as the number of
output log lines; -lc is typed (possibly followed by a number) the output will
be compact (one line per each entry - the character 'c' must be tight to l);
if the number is absent or illegal (e.g. a letter), the default 10 is used;

option -L does not expect arguments, but if you type -Lc, the net number of
log lines is printed, so that you could incorporate this to a script.

option -p must be followed by a selector char <s> for reverse sorting level:
   1|s  for reversing the primary sorting level
   2|S  for reversing the secondary sorting level

options -s, -S, -x and -o must be followed by a selector char <i> for a field:
   a    for the artist's name,
   c    for the artist's country
   r|t  for the record title,
   y    for the original record's year,
   i    for the CD issue year, if found (type cdd --notes for info),
   l|p  [lower 'el'] for the label or publisher's name
   n    for notes about the recordings (if you've got any);
   d    for the number of discs
   0    [zero] for special sorting with option -o (see below)

option -Z must be followed by a word, whose first letter is set as the
new separator; special characters may be escaped. For using the tab character,
type -Z\\t or -Z'\t'.

option -z must be followed by one or two numbers, separated by comma; these
numbers specify the extension of notes for wide-notes and framed views, with
the first number indicating the starting column and the second the ending
column; if one number only is used, it sets the ending column; framed view,
in any case, does not use the first column number, which is fixed and
encapsulated in the frame.

----------

The first time cdd is invoked, its own working directory .cdd/ is created in
the user $HOME directory; this directory will contain the default database,
all temporary files created by cdd and the file cdd_profile, which contains
user preferences; customize it at pleasure after first run (type 'cdd --help',
for instance...).

The secondary search reads [pat2] (which may contain spaces too) and tries to
refines search, selecting only records containing [pat2] if + is used, or
excluding those containing [pat2] if - is used. Blanks must be typed before and
after the +|-, and search may be iterated at will, adding and mixing + and -.
If you've got to search for words including + and -, you can disable the
secondary search mechanism using option --single (that means: use a single
search). If the first character of the pattern is + or - it will be interpreted
as the character itself, not a peculiar secondary search without primary
pattern. Should a character cause a misfunctioning of cdd, try escaping it.

The alternative search is activated when no match occurs: if the pattern can be
split into two or more words, cdd repeats the search (with the very same
options) over each word; to disable this mechanism use option --keep (that
means: keep last search). Alternative search is automatically disabled in case
of no results for the mix search.

Option -K disables both secondary and alternative searches, making cdd look for
the single and unique given pattern.

The mix search (option --mix) uses all pattern items as search patterns, stores
each search result and builds a cumulative output, that may be driven for
output using cdd common options (sorting, reverse, output, etc...). To separate
patterns containing blanks (e.g. soft machine) enclose patterns into single
quotes (e.g. 'soft machine') or use the underscore in place of blanks (e.g.
soft_machine).

During input with option --add or --replace, if text for artists' name, title
or publisher has a '%' prepended, it will be turned to all upper letters,
otherwise it is capitalized.

----------

If you find problems with the execution of cdd (in particular the infamus
'stdin: Illegal byte sequence' error message), remember that you should use
only ASCII characters in your database, or at least resetting your LANG user
system variable to "", because of a known bug of the program 'cut'.

----------

Now stop reading and start using cdd!
It's GPL! Enjoy!

Now you can understand how powerful it is. For example, here's the same output with the -n and -N option (n for numbered and N for Neutral):

$ cdd -n -N legacy

1737    Soft Machine Legacy     Live In Zaandam 2005    2005    @Dean, Etheridge, Hopper, Marshall      Moonjune        GB      1
1736    Soft Machine Legacy     Live At The New Morning 2006    2006    @Live, recorded Dec. 12, 2005 at the New Morning in Paris; Hopper, Marshall, Dean, Etheridge    Inakustik       GB      2
1738    Soft Machine Legacy     Steam   2007    2007    @Etheridge, Hopper, Marshall, Travis    Moonjune        GB      1
1735    Soft Machine Legacy     Live Adventures 2010    2010    @Live, recorded on Oct. 22, 2009 at Posthof, Linz, Austria, and on Oct. 23, 2009 and the Village, Habach, Germany; Etheridge, Travis, Babbington, Marshall      Moonjune       GB       1

or an output with the -F and -C options (F for framed and C for count)

------------------------------------------------------------------------------
Artist    : Soft Machine Legacy (GB)
Album     : Live In Zaandam
Issued in : 2005     CD date:  2005     Label:  Moonjune
Notes     : Dean, Etheridge, Hopper, Marshall
------------------------------------------------------------------------------
Artist    : Soft Machine Legacy (GB)
Album     : Live At The New Morning (2 CD)
Issued in : 2006     CD date:  2006     Label:  Inakustik
Notes     : Live, recorded Dec. 12, 2005 at the New Morning in Paris; Hopper,
            Marshall, Dean, Etheridge
------------------------------------------------------------------------------
Artist    : Soft Machine Legacy (GB)
Album     : Steam
Issued in : 2007     CD date:  2007     Label:  Moonjune
Notes     : Etheridge, Hopper, Marshall, Travis
------------------------------------------------------------------------------
Artist    : Soft Machine Legacy (GB)
Album     : Live Adventures
Issued in : 2010     CD date:  2010     Label:  Moonjune
Notes     : Live, recorded on Oct. 22, 2009 at Posthof, Linz, Austria, and on
            Oct. 23, 2009 and the Village, Habach, Germany; Etheridge,
            Travis, Babbington, Marshall
------------------------------------------------------------------------------
4 records found in cd.db database, with pattern 'legacy'.


Yes: colours!  Enabled with -F and -W views! You can customize that colors, of course.
Explore other options on your own (for instance, -o controls which field should be printed, and -x limits the search to the specified field).


As a final note, here I explain the symbols I use (appended to the issue/recording years) to define their meaning (--notes option):

$ cdd --notes
THE SPECIAL MARKERS AND THE SYMBOLS OF THE DATABASE

To enhance cdd usage, I adopted a small number of conventions to be used during
data input (option --add). The main conventions I use are explained here:

For any field (artist excluded):

   ^^^^   The 'unknown' mark; it means 'unknown data'; It also serves as a
          memo placeholder for subsequent insertions (see option --heal).
          This is the mark that option -J looks for when invoked.

For the year's field:

   v.v.   It means 'various years' - the record is typically a collection or
          an anthology; it means that the songs of the album have been recorded
          in a range of various years.
          This is the mark that option -R looks for when invoked with v.v.
          as parameter.

For the issue field:

   ----   The 'unknown issue year' mark; it means that no issue year has been
          found onto the cd (sometimes it happens, especially for bootlegs);
          this symbol is put automatically by --add when you leave the 'CD
          date' field empty, hitting Return on the input line.
          This is the mark that option -I looks for when invoked.

    x     Usually, a CD may be issued in the same epoch of its recording, or be
          a rather recent reprint, maybe from an older CD or from a much older
          LP. In case of a reprint, if the track listing matches the original
          (with possibly some bonus tracks), nothing remarkable happens: the
          two dates (whatever they are) stand for themselves, because the
          reprint includes the whole original opera. If some change arises
          (some tracks left off because they don't fit into the CD, or the
          record has some re-recording or it is a bootleg version with a
          different tracklist or whatever), any extra character should be put
          after the issue year, e.g. 2007N (--add performs this operation
          automatically, inserting a lower 'x, e.g. 2007x answering 'no' to the
          regular disc question). When cdd finds this extra character(s) during
          a search, an asterisk (*) is printed after the issue year,
          highlighting the 'irregularity' of the disc.
          This is the mark that option -i looks for when invoked.

For the notes field:
         
    ~     The tilde at the start of the notes field (possibly followed by @ and
          by some free-form text) indicates that the record is contained into a
          boxed-set, maybe with other independent titles; for a multi-cd
          anthology don't use this symbol, but e.g. for the Beatles mono
          collection (all mono complete cds in one box) use this symbol for
          each title; this symbol is put automatically by --add answering 'yes'
          to the box set question.
          This is the mark that option -b looks for when invoked.

    @     The '@' at the start of the notes field (possibly following the tilde
          and followed by some free-form text) indicates that the record is
          stored elsewhere (in an @lternative position), and not within the
          collection itself; this symbol is put automatically by --add
          answering 'yes' to the alternative position question.
          This is the mark that option -@ looks for when invoked.
         
    %     The '%' at the start of the notes field (possibly following the '@'
          and/or the tilde and followed by some free-form text) indicates that
          the record has a format different from the standard juwel-box; in my
          collection, this means I have to store them in a different position
          because they don't fit the shelf, and thus they automatically mean
          the alternative position is implied, but you can manage it as you
          like; this symbol is put automatically by --add answering 'yes' to
          the alternative format question.
          This is the mark that option -% looks for when invoked.

    The correct order for the case in which all three features are present is
    the following: ~@%
         
You're free to use your own coding, of course. This is only my point of view.
It's GPL! Enjoy!

Download last stable version: 6.14.0.

What's new in version 6.14.0 (September 28, 2013)
Note: Version 6.0.0 was a strong urge that I felt to publish that version, since I had used cdd extensively since version 2.2.2  and changed it a lot! But, as usual, too hurry means also too faulty.  I had some more ideas on the way, not implemented yet, and some improvement still to be accomplished. Now I guess I'm ready, but I'm planning, for version 7.x to improve and better all functions for manage the database (add, modify, delete and so on...). Wait and see...
No intermediate versions since 6.0.0 have been uploaded.
What's new in version 6.0.0 (February 14, 2013)
Note: I use cdd quite daily, and every day I've got one or two ideas to be added; this led to version 3, then to version 4, then to version 5; after the last changes, I put up my mind and typed the 'make' command, baptizing this version as 6.0.0; I expect suggestions and bugs research!
No intermediate versions since 2.2.2. have been uploaded.
What's new in version 2.2.2 (November 7, 2010)
Note: cdd has been used extensively by me, during these years. I added or changed small things over the years, and suddenly I realized that version 1.50 was far away. So I changed release number to 2; and, doing further small changes/addons, I had to increase the major and minor numbers too, up to 2.2.2. No intermediate versions have been uploaded.
What's new in version 1.5.0 (April 30, 2007)
Note: I made all sorts of experiments on this script, so the versioning was messed-up. My fault. There's no actual distribution between 1.0.0 and 1.5.0.
What's new in version 1.0.0 (November 25, 2006)
Download

Downloadable files (recommended for any system with bash 3.x):
It's GPL! Enjoy!