central(n) 1.0b3 central "Central"

Name

central - Central

Table Of Contents

Synopsis

Description

Central is a passive registration system for Tcl extensions and programs, based on the idea and workings of the Tcl pkgconfig command.

To participate, a pkgconfig command should exist in the namespace of an extension or program ("package"). Central itself is not needed by a providing package, only by a querying program.

Central can be used by a program to scan the namespace hierarchy (discover), and query any package information found. A Central package is the fully-qualified namespace inside which a pkgconfig command was found.

The pkgconfig command provided by a package should behave like the Tcl pkgconfig command.

Central makes no effort to interpret the information returned by a pkgconfig command; this information is entirely up to the package.

Central is all about "about": allowing a program to easily provide information about itself to the outside world.

The usage example files, the program centraltool.tcl, and the Central extension itself contain pkgconfig commands and other code bits that can be copied or serve as examples and should make it easy to add Central functionality to extensions or programs.

Central works with Jim as well as with Tcl.

CENTRALIZED PACKAGES

A centralized package connects a Tcl package name and a namespace.

A package is considered "centralized" if it has both "name" and "importfrom" keys. The "name" should be the name of the Tcl package used in [package require], and "importfrom" should be the namespace where procedures exported by the package can be found. The "importfrom" namespace will be used in [namespace import] invocations. If "importfrom" is empty then the package is still considered to be centralized.

PACKAGE INITIALIZATION

A package can declare an initialization command by having both "name" and "initializer" keys. A package that declares both keys can be used with the [central initializer] and [central initialize] commands.

If the value of the "initializer" key begins with a colon then the package initialization command will be the value of the "initializer" key. If the package has an "importfrom" key then the initialization command will be the concatenation of the value of the "importfrom" key, two colons, and the value of the "initializer" key. Otherwise, the package is not considered to have an initialization command.

COMMANDS

central discover ?exclude?

Discovers packages. Ignores packages specified in exclude. Should be called before calling other Central commands. Returns a list of all discovered packages.

central packages

Returns a list of previously discovered packages.

central packagekeys package ?key?

Returns a list of all keys for package package matching key. If key isn't supplied then the default pattern "*" will be used for key.

central package ?package? ?key?

Returns all package info or info matching package and key. If package isn't supplied then the default pattern "*" will be used for package. If key isn't supplied then the default pattern "*" will be used for key.

central find ?key? ?value?

Finds packages. Returns the package if key and value do not contain glob chars and only one match was found, otherwise returns a list of {package key value} lists for all matches. If key isn't supplied then the default pattern "*" will be used for key. If value isn't supplied then the default pattern "*" will be used for value.

central centralized tclpackage

Returns a 2-element list of {package namespace} if the Tcl package is centralized, the 2-element list {{} {}} otherwise.

central exports tclpackage

Returns a list of procedures exported by centralized Tcl package tclpackage or an empty list if tclpackage isn't a centralized package.

central import ?-force? tclpackage ?pattern ...?

Imports procedures from centralized Tcl package tclpackage. If tclpackage is a centralized package, "importfrom" isn't empty, and the invocation of [namespace import] was successful, then the return value will be a list of attempted import patterns, otherwise an empty list is returned. The -force option can be used to import commands over existing commands.

central initializer tclpackage

Returns the initialization command for tclpackage or an empty string if tclpackage doesn't exist or doesn't have an initialization command.

central initialize tclpackage ?arg ...?

Calls the initialization command for tclpackage in the callers environment, passing any ?arg ...?. An error is returned if the tclpackage doesn't exist or doesn't have an initialization command, otherwise the returned value of the initialization command is returned.

central require ?-exact? ?-noinit? ?-noimport? ?-init command? ?-import {command ...}? ?-allinfo? tclpackage ?requirement ...?

In the callers namespace, performs [package require ?-exact? tclpackage ?requirement ...?], [central discover], [central initialize tclpackage], and [central import tclpackage]. The options -noinit and -noimport disable all initialization and importing, respectively. The -init command option specifies a command to call instead of any package initialization command. The supplied initialization command will be called with one argument: the initialization command of the package. The initialization info will be set to the return value of the supplied initialization command. The -import {command ...} option can be used to specify a list of commands to import. If the -allinfo option is specified then a dictionary of require, init, and import info is returned, otherwise, the returned value is the returned value of the Tcl [package require] command. A package must have the keys "name", "initializer", and "importfrom" for this to work.

EXAMPLES

	# Discover packages and display package info.
	package require central
	namespace import ::central::central
	central discover
	foreach package [central packages] {
		foreach key [central packagekeys $package] {
			puts [string cat $key " -> " \
				[central package $package $key]]
		}
	}
	# Find and use a package.
	package require central
	namespace import ::central::central
	package require myPackage
	central discover
	set package [central find name myPackage]
	if {[regexp {^.+\db\d+$} [central package $package version]} {
		puts "Still in beta!"
	}
	# Find all packages with ISC licenses,
	  for all packages that have a key "license,type".
	central find license,type ISC
	# Using a centralized package.
	package require central
	namespace import ::central::central
	package require MyPackage
	central discover
	puts "MyPackage exports: [central exports MyPackage]"
	# namespace import a few commands
	#
	central import MyPackage aCmd anotherCmd z*
	# namespace import *
	#
	central import MyPackage

See Also

Tcl_RegisterConfig(3), central::extras

Keywords

central, pkgconfig

Category

Programming tools