contmgr list contacts for your terminal iPad, Fritz!Box, hand bag

doc generated from the script with gendoc

bash script, version=2.06

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 one or more of regular font, bold font, and pointsize.
	Default: `X='DejaVuSerif,DejaVuSerif-Bold␣12'` Argument examples: `'a,b␣12'␣'a,b'␣'a'␣'a␣12'␣'a,␣12'␣',b'␣'12'` 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
	handicapped, text-to-voice progs will pause there Labels will be boxed to force reading horizontally. Creates a nickname in vcards containing most info. The nickname can easily be invoked to be 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	N 1
First	N 2
Middle	N 3
Prefix	N 4
Suffix	N 5
Nick	NICKNAME
Disp	FN (unused, reconstructed from above entries)
Org	ORG
Url	URL
Bday	BDAY
Hmail	EMAIL;TYPE=HOME
Wmail	EMAIL;TYPE=WORK
Hpobox	ADR;TYPE=HOME 1
Hext	ADR;TYPE=HOME 2
Hstreet	ADR;TYPE=HOME 3
Hcity	ADR;TYPE=HOME 4
Hstate	ADR;TYPE=HOME 5
Hzip	ADR;TYPE=HOME 6
Hccode	ADR;TYPE=HOME 7
Wpobox	ADR;TYPE=WORK 1
Wext	ADR;TYPE=WORK 2
Wstreet	ADR;TYPE=WORK 3
Wcity	ADR;TYPE=WORK 4
Wstate	ADR;TYPE=WORK 5
Wzip	ADR;TYPE=WORK 6
Wccode	ADR;TYPE=WORK 7
Keys	CATEGORIES
Hphone	TEL;TYPE=HOME
Wphone	TEL;TYPE=WORK
Mphone	TEL;TYPE=CELL
Note	NOTE

Note that the last (7th) field of the ADR entry is supposed to be a country code, like NL for The Netherlands. Vcard exports of most applications tend to put the name of the country here, in the language set in that application. contmgr tries to replace such names with the corresponding country code, using the information in the CCodes associative array. When a country name has to be written, in an address label for example, this country code is used to find, in CCodes, the country name in the language of the user, Mylanguage, as defined in the user configuration file.

Currently, country names are defined in CCodes in 6 languages: EN, FR, ES, IT, and NL.

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 code, may be inconvenient. You can set your own defaults in a configuration 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"
   Myccode=NL
   Mylanguage=NL
   Cols=3
   Rows=8
   Paperwidth=210
   Paperheight=297
   LetterStyle=iso

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 Myccode, 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 Myccode (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 countrycode [Blind]

description:

Try to format city, state and zip

pr_city 94595 'Walnut Creek' CA US → 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 `Myccode` 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='' 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

find_country

synopsis:	find_country countrycode
description:	From the countrycode (FR, NL, GB, BE, et cetera) find the
	country name.

                The Vcard ADD entry has 7 fields; the last field is the
                country name. This name can occur in any language, while
                what we need in address labels is the name of the country
                in the language of the country where we live (Mylanguage),
                so that the postman recognizes it.
                Therefore, contmgr expects the country code in this
                field, and if it finds a country name instead, in any of
                the languages it understands, it replaces it with the
                country code.
                Finally, |find_country| prints country code, call code and
                country name, separated with |-| characters. If the country
                code happens to be the country of the user (|Myccode|),
                then the country name is cleared, since it would not have
                to be written on address labels in that case.
Example:

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 `+$Myccode` with 0 for nicer display (unless the output format is `vcard`.