contmgr list contacts for your terminal iPad, Fritz!Box, hand bag
doc generated from the script with gendoc
bash script, version=2.05

Synopsis

contmgr [options] [searchkey]

General options:

-h,--help
Print this help and exit
-H,--Help
Show full documentation and exit
-V,--version
Print version and exit
-i,--input=X
Take input from file X with default extension vcf;
if X has no path info, the file is supposed to reside in the same directory as the default input file.
-k,--key=X
select records containing key X in the CATEGORIES field
-w,--word
search key must be a complete word

Format options:

-b,--booklet
print booklet
-l,--labels
print tex source for address labels
-L,--letter
print tex source for letters
-s,--sorter
print only first line of --term format
-T,--tagged
print tag / value list
-t,--term
print to terminal (this is the default format)
-v,--vcard
print vcards
-x,--xml
print xml for FritzBox

Format specific options (b, l, t and T specify relevant formats):

-d,--dark
(t) do not use color in terminal output
-f,--font=X
(bl) set font andor bold font andor pointsize.
The last one (|'12'|) changes the pointsize only.
-N,--nocolor
(t) set colors for dark background
-n,--noarea=X
(bl) in phone numbers, remove area codes with the
value X, possibly prefixed with 0 (zero)
-r,--return=X
(l) use X as return addres in labels, commas are
replaced with bullets
-c,--counter
(b) prefix display name in booklet with a counter for
reference
-B,--blind
(ltT) suffix label lines with a dot for visually
read aloud on an iphone.

Description

contmgr lists your contacts to standard output. If you provide a search key, only contacts containing that key are listed. With the --word option, the search key must occur as a whole word.

The input is a vcard file exported from, for example, Thunderbird or the iCloud. The name of the vcard file is supposed to be in the environment variable CONTACTS, unless it is given with the --input option.

There are some limitations on the data that are read from that vcard file. The following table shows the vcard fields that are stored and the formats (v=vcard, T=tagged, x=xml, t=terminal, b=booklet, l=label L=letter) in which they are reproduced:

Last
vTxtblL N 1
First
vTxtblL N 2
Middle
vTxtb-  N 3
Prefix
vT-tblL N 4
Suffix
vT-tblL N 5
Nick
vTxtb-  NICKNAME
Disp
vT----  FN (unused, reconstructed from above entries)
Org
vTxtb-  ORG
Url
vT-t--  URL
Bday
vT-t--  BDAY
Hmail
vTxt--  EMAIL;TYPE=HOME
Wmail
vTxt--  EMAIL;TYPE=WORK
Hpobox
vT-tblL ADR;TYPE=HOME 1
Hext
vT-tblL ADR;TYPE=HOME 2
Hstreet
vT-tblL ADR;TYPE=HOME 3
Hcity
vT-tblL ADR;TYPE=HOME 4
Hstate
vT-tblL ADR;TYPE=HOME 5
Hzip
vT-tblL ADR;TYPE=HOME 6
Hcntry
vT-tblL ADR;TYPE=HOME 7
Wpobox
vT-tblL ADR;TYPE=WORK 1
Wext
vT-tblL ADR;TYPE=WORK 2
Wstreet
vT-tblL ADR;TYPE=WORK 3
Wcity
vT-tblL ADR;TYPE=WORK 4
Wstate
vT-tblL ADR;TYPE=WORK 5
Wzip
vT-tblL ADR;TYPE=WORK 6
W.cntry
vT-tblL ADR;TYPE=WORK 7
Keys
vT-t--  CATEGORIES
Hphone
vTxt--  TEL;TYPE=HOME
Wphone
vTxt--  TEL;TYPE=WORK
Mphone
vTxt--  TEL;TYPE=CELL
Note
vT-tb-  NOTE

Formats

contmgr can print in various formats, specified in the --format option. Currently, the following formats are available:

==

Configuration

The defaults for some variables, like font, fontsize, vcard file, and country may be inconvenient. You can set your own defaults in a config file, either in system file: $PREFIX/contmgr.conf or in a user file: $HOME/.contmgr.conf. These files are read in this order and they can contain input such as this:

   Fontsize=12
   Font='DejaVuSerif'
   Bold='DejaVuSerif-Bold'
   Input="$HOME/Contacts.vcf"
   Mycountry='Nederland'
   Mycode=31

The content shown here would have no effect, as its values are the defaults already.

Todo

Country code

The vCard format lacks an entry for the country code, needed for formatting the zip code and for zip code positioning in address labels. There is of course an entry for the country, but that can be expressed in any language, preferably the local language.

My solution for now is to expect two vcard entries in the vcard file: X-CCODE-HOME and X-CCode-WORK, which set the country codes for home and work addresses. By default, the users own country code Mycode, as set in the configuration file, is used. So normally, these entries are needed only for foreign addresses.

Phone number formatting

I suppose phonenumbers to have the format +can, where c is 1-3 country code digits, a is 1-3 area code digits and n is 1 or more phone number digits. If the c's match the value of Mycode (say xx), this is converted to 0xx␣an; if not, to 00xx␣an. After this, I match the a's with an array AreaCodes and I use the match (say yyy) to convert to 00xx␣yyy␣n. Finally, the n's are spaced, depending on the number of n's. Problem: the AreaCodes array is valid for the Netherlands only.

Author

Wybo Dekker

Copyright

Released under the GNU General Public License

Functions used:


handle_options

synopsis:
handle_options "$@"
description:
handle the options.
globals used:
Myname Version AreaCodes
globals  set:
Args Noarea Grepopt Format Return Fontsize Font Bold Input
Mycountry Key
returns:
the number of remaining arguments

validateemail

description:
validate a comma+space-separated email list

light

description:
set colors for light background

dark

description:
set colors for dark background

nocolor

description:
set no colors

join

synopsis:
join separator string [string...]
description:
use first argument as separator to print other non-empty
join '=' a b '' d → a=b=d

pr_age

description:
print age; On March 13, 2019:
after Bday=2011-03-22 pr_age prints (7) or, for blind people: age: 7

pr_city

synopsis:
pr_city zip city state areacode [Blind]
description:
Try to format city, state and zip
pr_city 94595 'Walnut Creek' CA 1 → Walnut Creek CA 94595 If there is a 5th argument and it is true, zip codes are printed without  spaces: this is useful for blind people, because spaces cause pronunciation problems for speaking programs.

fix

synopsis:
fix phonenumber
description:
replace any Mycode with 0 and insert spaces in phone number;
fix Hphone && echo $Hphone # → 06 3033 3955
returns:
1 if the phone number is empty, else 0

texescape

synopsis:
texescape varname
description:
escape #, _, %, & in the variable named in the argument
x='50%'; texescape x; echo $x → 50\%

displayname

description:
print Last, First (Organization), but clean up if some are empty.

 First=Wybo Last=Dekker Org=DekDoc displayname → Dekker, Wybo (DekDoc)

 First=Wybo Last=Dekker Org=''     displayname → Dekker, Wybo

 First=''   Last=Dekker Org=DekDoc displayname → Dekker (DekDoc)

 First=''   Last=''     Org=DekDoc displayname → DekDoc

setvar

synopsis:
setvar varname value vardescription 
description:
set named variable to value, but only if it's empty:
Example: setvar Hphone +31345652152 'home phone'

pr_sorter

description:
print only first line of terminal format

pr_tagged

description:
print in tag:value format

pr_oneliner

description:
print in oneliner terminal format

pr_term

description:
print in terminal format

pr_startlabels

description:
print preamble for address labels

pr_startletter

description:
print preamble for letter

trim

descrtiption:
trim and squeeze named variable

pr_label

description:
print in home and work addresses label format

pr_letter

description:
print in home and work addresses letter format

pr_startbooklet

description:
print preamble for booklet format

pr_booklet

description:
print in booklet format

pr_startxml

description:
print preamble for FritzBox xml format

pr_xml

description:
print in FritzBox xml format

pr_vcard

description:
print vcard

filltype

synopsis
filltype xhome xwork [xcell]
description:
Set Type to the first argument for which the corresponding
variable is empty; the name of the argument tells the type assigned. note: Made this, because thunderbird exports home address without type=HOME if it's the first address, and the work address without type=WORK if it's the second address. iCloud exports with both type indications. thus, in the absence of type indicators the first two addresses are home and work the first two emails are home and work the first three phonenrs are home, work. and celll

mobtest

synopsis:
mobtest Xphone type boolean
description:
Test if the content of the named variable in arg 1 is probably a
mobile number. If so, and arg 3 is false, of if not and arg 3 is true, issue a warning. Finally, edit the content of arg 1 by replacing an initial +$Mycode with 0 for nicer display (unless the output format is vcard.