My favorites | Sign in
Project Logo
Project Home
  
Downloads
  
Wiki
  
Issues
  
Source
    
Search
for
Updated Nov 02, 2007 by dulanov
Labels: Phase-Requirements, Featured
ConsoleToolSpecification  
The specification of work in console in the man style.

NAME

contactserv - a service to manage personal address book data in the URI-based Semantic Web style.

SYNOPSIS

contactserv [<semap instance URL>] <command> [<arguments>]

DESCRIPTION

contactserv is an address book utility to operate with a specified by FOAF scheme personal data. All various aspects of supported contacts data are described in the master.rdf file.

COMMAND

find - to find contacts' URI(s) corresponding some constraint field values.

get - to display all or specified explicitly contact fields on the specified URI(s).

add - to create a new contact or add contact field values on the specified URI(s).

update - to update or delete contact field values on the specified URI(s).

remove - to remove whole contacts with all fields on the specified URI(s).

[--]help or -h - to access the built-in tool documentation.

[--]version or -v - to see an information about the tool version.

get, add, update and remove are URI-centric commands, they consume URIs consistently. Sometimes you can use the find command to populate them. To exit from these commands enter an empty URI.

COMMAND ARGUMENTS

FOR FIND COMMAND

Only some fields of contact data can be used to find contacts or try keyword-base approach instead. You can use regular expressions in all these cases. Don't set any arguments to find all contacts.

Used field-based arguments:

full name abbreviation field(s) possible values
--gender -g gender 'male' or 'female'
--nick none nick name any regular expression for literal values
--name -n full name any regular expression for literal values
--firstname -f first name any regular expression for literal values
--surname -s surname any regular expression for literal values
--birthday -b date of birth yyyy-mm-dd date format
--mailbox -m mailbox any regular expression to find ordinal emails
--url -u homepage, weblog, workpage or openid any regular expression to find web page's URLs
--friend none friend any regular expression to find contact's URIs

Other special arguments:

full name abbreviation description possible values value by default
--keyword -k search by a keyword any regular expression to find everything not used

FOR GET COMMAND

Options that define what contact fields must be displayed. Don't set any arguments to display all existing contact fields.

Field-based arguments:

full name abbreviation field value format
--gender -g gender 'male' or 'female'
--nick none nick name a literal value with a language code @postfix
--name -n name an ordinary name with a language code @postfix
--firstname -f first name a literal value with a language code @postfix
--surname -s surname a literal value with a language code @postfix
--birthday -b date of birth see the 'find' command arguments descriptions
--image -i image an image URL
--mailbox -m mailbox account an email address URI
--mailboxsha1sum none mailbox SHA1 summary a literal value
--phone none phone a telephone URI
--homepage none homepage a web page URL
--weblog none weblog a web page URL
--workpage none workpage a web page URL
--icq none ICQ account identifier a literal value
--aim none AIM account identifier a literal value
--msn none MSN account identifier a literal value
--yahoo none Yahoo account identifier a literal value
--jabber none Jabber account identifier a literal value
--account -a online account username@service [ profile ]
--openid -o openid an OpenID profile URL
--residence -r residence WGS84 latitude:longitude
--friend none friend an other contact URI

Other special arguments:

full name abbreviation description possible values value by default
--language -l language parameter the list of normalized to lowercase language code of language tags separated by ',' or 'all' all
--force none never display any prompts none none

If a plain literal value doesn't have any predefined language, it is always displayed regardless of the chosen language.

The most often used language codes (see the list of available codes also):

language code language name
zh Chinese
en English
fr French
de German
it Italian
ja Japanese
ru Russian
es Spanish

FOR ADD COMMAND

The command arguments are identical to arguments from the get command, but there are some additional important rules:

  1. Duplicating contact field values will be ignored;
  2. The command doesn't sensitive to the language argument;
  3. It is possible to enter multiple contact field values separated by comma;
  4. You cannot add automatically regenerated fields manually: a mailbox SHA1 summary;
  5. If some contact fields have not been added explicitly they can be calculated automatically: a name.

New contact field values should satisfy with the following simple rules:

  1. You can add a language code @postfix to a literal value;
  2. Literal value that contains comma or '@' symbol should be framed with ', " or ` symbols for choice.

FOR UPDATE COMMAND

The command arguments are identical to arguments from the get command, but you can update and delete contact fields values instead of only viewing them by means of the following commands:

  • To leave the current field value press the 'TAB' button;
  • To modify the contact field type a new value for it;
  • To delete the contact field value enter an empty value.

And some important rules exist:

  1. Duplicating contact field values will be deleted;
  2. You cannot update or delete automatically regenerated fields (see the add command for details).

New contact fields values should satisfy with the rules described in the add command section.

FOR REMOVE COMMAND

No predefined arguments.

FOR HELP COMMAND

To view the description of any command simply write it's name after the 'help' command: 

contactserv [--]help <command>

EXAMPLES

specdata.rdf (will be used by default by using the predefined environment parameter) and master.rdf (will be used via the http://master.localhost/ semap instance) data are used in the following examples.

1. Find all contact resources URIs: 

> contactserv find

http://localhost/contacts/timbl
http://localhost/contacts/nwalsh
http://localhost/contacts/ivan_herman
http://localhost/contacts/fgiasson
http://localhost/contacts/chrisb
http://localhost/contacts/cygri
http://localhost/contacts/dave_beckett
http://localhost/contacts/danbri
http://localhost/contacts/mnaver
http://localhost/contacts/dulanov

2. Find contact resources that have nickname started with 'c': 

> contactserv find --nick 'c.*'

http://localhost/contacts/chrisb
http://localhost/contacts/cygri

3. Who has birthday in winter and has a homepage, weblog, workpage or openid: 

> contactserv find -b '.*-(12|01|02)-.*' -u '.*' | contactserv get -nbr --homepage

Welcome to contactserv version 1.0.
Insert a contact URI to process it or press 'ENTER' (an empty URI) to finish.

uri> http://localhost/contacts/ivan_herman
name: Ivan Herman@en
name: Herman Iván@hu
birthday: 1955-02-24
homepage: http://www.ivan-herman.net
residence: 52.302063:4.87397

uri> http://localhost/contacts/danbri
name: Dan Brickley@en
birthday: 1972-01-09
homepage: http://danbri.org/

uri>

4. Display all contact resources names (all languages by default): 

> contactserv find | contactserv get --name --force

uri> http://localhost/contacts/timbl
name: Timothy Berners-Lee@en

uri> http://localhost/contacts/nwalsh
name: Norman Walsh@en

uri> http://localhost/contacts/ivan_herman
name: Ivan Herman@en
name: Herman Iván@hu

uri> http://localhost/contacts/fgiasson
name: Frédérick Giasson@fr

uri> http://localhost/contacts/chrisb
name: Chris Bizer@en

uri> http://localhost/contacts/cygri
name: Richard Cyganiak@en

uri> http://localhost/contacts/dave_beckett
name: Dave Beckett@en

uri> http://localhost/contacts/danbri
name: Dan Brickley@en

uri> http://localhost/contacts/mnaver

uri> http://localhost/contacts/dulanov
name: Dmitry Ulanov@en
name: Уланов Дмитрий@ru

uri>

5. Display contact names, emails and available online services in English and Russian languages: 

> contactserv http://master.localhost/ get --name --mailbox --account --language en,ru --force
or
> contactserv http://master.localhost/ get -nma -l en,ru --force

uri> http://example.com/foaf#me
name: 一流の姓
name: Firstname Surname@en
name: Имя Фамилия@ru
mailbox: mailto:me@example.com
account: me@http://example.com/service/ [http://example.com/service/me/]

uri>

6. Display all contact fields values: 

> contactserv http://master.localhost/ find | contactserv http://master.localhost/ get --force

uri> http://example.com/foaf#me
gender: male
gender: female
nick: nick@en
nick: ник@ru
name: 一流の姓
name: Firstname Surname@en
firstname: Firstname@en
surname: Surname@en
name: Имя Фамилия@ru
firstname: Имя@ru
surname: Фамилия@ru
birthday: 1999-12-31
image: http://example.com/image.jpg
mailbox: mailto:me@example.com
mailboxsha1sum: 7197f75b9213873c4679bfcb982a00943fc0ffb3
phone: tel:+1-(123)-123-4567
homepage: http://example.com/
weblog: http://example.com/blog/
workpage: http://example.com/
icq: 1234567
aim: [aimChatID]
msn: me@example.co
yahoo: [yahooChatID]
jabber: [jabberChatID]
account: me@http://example.com/service/ [http://example.com/service/me/]
openid: http://example.com/
residence: 12.345678:-12.345678
friend: http://example.com/foaf#anyone

uri>

7. Add a first name and surname in French and Spain and Timothy Berners-Lee as a friend to a contact: 

> contactserv find --surname 'Bern.*'

http://localhost/contacts/timbl

> contactserv add --firstname --surname --friend

Welcome to contactserv version 1.0.
Insert a contact URI to process it or press 'ENTER' (an empty URI) to finish.

uri> http://example.com/foaf#me
firstname: prénom@fr, 'nombre'@es
surname: "nom de famille"@fr, `apellido`@es
friend: http://localhost/contacts/timbl

uri>

8. Change the nick name in English, the weblog page URL and delete the phone number: 

> contactserv http://master.localhost/ update -fs --nick --phone --weblog -l en

Welcome to contactserv version 1.0.
Insert a contact URI to process it or press 'ENTER' (an empty URI) to finish.

Usage:
  1. Press 'TAB' to leave the current field value;
  2. Enter an empty value to delete the current field value.

uri> http://example.com/foaf#me
nick: nick@en -> new nick@en
firstname: Firstname@en -> Firstname@en
surname: Surname@en -> Surname@en
phone: tel:+1-(123)-123-4567 ->
weblog: http://example.com/blog/ -> http://example.com/newblog/

uri>

Are you sure you want to update those values? (yes/no) no

9. Remove all contacts: 

> contactserv http://master.localhost/ find | contactserv http://master.localhost/ remove

Welcome to contactserv version 1.0.
Insert a contact URI to process it or press 'ENTER' (an empty URI) to finish.

uri> http://example.com/foaf#me

uri>

Are you sure you want to delete those contacts? (yes/no) no

ENVIRONMENT

parameter description
SEMANTIC_BUS_URL A URL of the semap instance which is should used by default

EXIT STATUS

000 The contactserv utility terminated without any errors (successfully).

001-127 The contactserv utility detected an error.

The summary table of all predefined errors:

code error
001 an unknown command
002 an unknown command argument
003 an incorrect command argument value
004 an incorrect URI format
005 an incorrect textual field value format
006 the semap instance is not available
007 user has insufficiently rights to read or modify the resource

AUTHOR

The semap project development team

BUGS/TODO

Please report all bugs and suggestions via http://code.google.com/p/contactserv/issues/list.

LICENSE

	Copyright 2007 The semap project development team.

	Licensed under the Apache License, Version 2.0 (the "License");
	you may not use this file except in compliance with the License.
	You may obtain a copy of the License at

		http://www.apache.org/licenses/LICENSE-2.0

	Unless required by applicable law or agreed to in writing, software
	distributed under the License is distributed on an "AS IS" BASIS,
	WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
	See the License for the specific language governing permissions and
	limitations under the License.

VERSION

1.0-M1

SEE ALSO

-


Sign in to add a comment
Hosted by Google Code