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

doc generated from the script with gendoc

zsh script, version=2.12

Synopsis


contmgr [options] [searchkey]

Options

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

Other options

-d,--dark	set colors for dark background
-f,--font=X	set normal and bold fonts and pointsize.
	'a,b 12' 'a,b' 'a' 'a 12' 'a, 12' ',b' '12' The last one ('12') changes the pointsize only.
-N,--nocolor	do not use color in terminal output
-n,--noarea=X	in phone numbers, remove area codes with the
	value X, possibly prefixed with 0 (zero)
-r,--return=X	use X as return addres in labels, commas are
	replaced with bullets
-c,--counter	prefix display name with a counter
-B,--blind	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 maintained in, for example, Thunderbird or the iCloud. The name of the vcard file is is read from the configuration file, see below, but it can be modified 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:

booklet

This produces a latex source on standard output, to be printed twosided on A4 paper, which can be folded to create an A5 booklet.

labels

Produces a latex source on standard output, to be printed on A4 sheets with sticky labels.

letter

Produces a latex source on standard output, containing one letter for each address. The content of the letter has to be insertes afterwards.

sorter

Lists the records, one line for each, with name, organisation, birth day, age and any tags.

tagged

Lists each record completely, one field per line, prefixed with the fields tags.

term

This is the default. Lists each record completely, with Home data on the left, work data on the right, mobile numer in the middle.

vcard

Prints the reformatted vcard file, sorting the fields and the records, cleaning up unneeded fields.

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: /usr/local/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=10
   Font='DejaVuSerif'
   Bold='DejaVuSerif-Bold'
   Input="$HOME/Contacts.vcf"
   Myccode=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 Nodial Grepopt Format Return Fontsize Font Bold Input
	Mycountry Key
returns:	the number of remaining arguments

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:	Use pnc to insert spaces in the phonenumber:
	x=+32630333955; fix x; echo $x => 0032 6 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'

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 phone nrs are home, work. and cell

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`.