Data Structures |
| struct | _CLibSource |
| struct | _CLibSymbol |
| struct | _CacheEntry |
Defines |
| #define | WIFSIGNALED(x) 0 |
| #define | WTERMSIG(x) 0 |
| #define | WIFEXITED(x) 1 |
| #define | WEXITSTATUS(x) 0 |
| #define | SYM_FILENAME_FILTER ".sym" |
| #define | CLIB_LIST_CMD "list" |
| #define | CLIB_DATA_CMD "get" |
| #define | CLIB_MAX_SYMBOL_CACHE 128 |
| #define | CLIB_MIN_SYMBOL_CACHE 96 |
Typedefs |
| typedef struct _CacheEntry | CacheEntry |
Enumerations |
| enum | CLibSourceType { CLIB_NONE = 0,
CLIB_DIR,
CLIB_CMD,
CLIB_SCM
} |
Functions |
| static void | free_symbol (gpointer data, gpointer user_data) |
| | Iterator callback for freeing a symbol.
|
| static void | free_symbol_cache_entry (gpointer data) |
| | Iterator callback for freeing a symbol cache entry.
|
| static void | free_source (gpointer data, gpointer user_data) |
| | Iterator callback for freeing a source.
|
| static gint | compare_source_name (gconstpointer a, gconstpointer b) |
| | Compare two component sources by name.
|
| static gint | compare_symbol_name (gconstpointer a, gconstpointer b) |
| | Compare two component symbols by name.
|
| static void | cache_find_oldest (gpointer key, gpointer value, gpointer user_data) |
| | Iterator callback for finding oldest symbol cache entry.
|
| static gchar * | run_source_command (const gchar *command) |
| | Execute a library command.
|
| static CLibSymbol * | source_has_symbol (const CLibSource *source, const gchar *name) |
| | Find any symbols within a source with a given name.
|
| static gchar * | uniquify_source_name (const gchar *name) |
| | Make sure a source name is unique.
|
| static void | refresh_directory (CLibSource *source) |
| | Rescan a directory for symbols.
|
| static void | refresh_command (CLibSource *source) |
| | Re-poll a library command for symbols.
|
| static void | refresh_scm (CLibSource *source) |
| | Re-poll a scheme procedure for symbols.
|
| static gchar * | get_data_directory (const CLibSymbol *symbol) |
| | Get symbol data from a directory source.
|
| static gchar * | get_data_command (const CLibSymbol *symbol) |
| | Get symbol data from a library command.
|
| static gchar * | get_data_scm (const CLibSymbol *symbol) |
| | Get symbol data from a Scheme-based component source.
|
| void | s_clib_init () |
| | Initialise the component library.
|
| void | s_clib_free () |
| | Free all memory used by the component library.
|
| GList * | s_clib_get_sources (const gboolean sorted) |
| | Get a list of available component sources.
|
| void | s_clib_refresh () |
| | Rescan all available component libraries.
|
| const CLibSource * | s_clib_get_source_by_name (const gchar *name) |
| | Get a named component source.
|
| const CLibSource * | s_clib_add_directory (const gchar *directory, const gchar *name) |
| | Add a directory of symbol files to the library.
|
| const CLibSource * | s_clib_add_command (const gchar *list_cmd, const gchar *get_cmd, const gchar *name) |
| | Add symbol-generating commands to the library.
|
| const CLibSource * | s_clib_add_scm (SCM listfunc, SCM getfunc, const gchar *name) |
| | Add symbol-generating Scheme procedures to the library.
|
| const gchar * | s_clib_source_get_name (const CLibSource *source) |
| | Get the name of a source.
|
| GList * | s_clib_source_get_symbols (const CLibSource *source) |
| | Get a list of symbols available from a given source.
|
| const gchar * | s_clib_symbol_get_name (const CLibSymbol *symbol) |
| | Get the name of a symbol.
|
| gchar * | s_clib_symbol_get_filename (const CLibSymbol *symbol) |
| | Get a filename for editing a symbol.
|
| const CLibSource * | s_clib_symbol_get_source (const CLibSymbol *symbol) |
| | Get the source to which a symbol belongs.
|
| gchar * | s_clib_symbol_get_data (const CLibSymbol *symbol) |
| | Get symbol data.
|
| GList * | s_clib_search (const gchar *pattern, const CLibSearchMode mode) |
| | Find all symbols matching a pattern.
|
| void | s_clib_flush_search_cache () |
| | Flush the symbol name lookup cache.
|
| void | s_clib_flush_symbol_cache () |
| | Flush the symbol data cache.
|
| void | s_clib_symbol_invalidate_data (const CLibSymbol *symbol) |
| | Invalidate all cached data about a symbol.
|
| const CLibSymbol * | s_clib_get_symbol_by_name (const gchar *name) |
| | Get symbol structure for a given symbol name.
|
| gchar * | s_clib_symbol_get_data_by_name (const gchar *name) |
| | Get symbol data for a given symbol name.
|
| GList * | s_toplevel_get_symbols (const TOPLEVEL *toplevel) |
| | Get a list of symbols used.
|
Variables |
| static GList * | clib_sources = NULL |
| static GHashTable * | clib_search_cache = NULL |
| static GHashTable * | clib_symbol_cache = NULL |
clib stands for component library.
The component library is made up of a number of component sources, each of which in turn makes available a number of component symbols. Each source may be either a directory on disk containing symbol files, a command in the system PATH which can generate gEDA symbol data (e.g. from a database), or a Scheme function which can do likewise. A component source is represented by a CLibSource instance.
The component library system manages component sources and symbols, and abstracts the interface to the underlying storage.
To initialise the component library, s_clib_init() is called. To clean up when it is no longer needed, s_clib_free() should be called.
A directory which contains one or more symbol files in gEDA format may be used as a component source. Each symbol file should have a filename ending in ".sym" (case insensitive). A component source based on a directory can be added using s_clib_add_directory(). Symbol files with filenames starting with a period "." are ignored.
An executable program in the system search path may be used as a component source, and it must conform with the specification given on page Library Commands. A component source based on a command may be added using s_clib_add_command().
Scheme functions may be used as a component source; for more information, please see page Library Scheme Procedures. A component source based on Scheme functions may be added using s_clib_add_scm().
Each symbol is identified by its name, which is stored in the saved schematic file. The name must be a valid for storage in a gEDA schematic file as the "basename" of a "component" object. For symbols from directory sources, the filename of the symbol is taken as the symbol name. For a command source, the name may be any permissible string. Guidelines to follow:
- Do not begin a symbol name with "EMBEDDED"
- Do not use whitespace, or any of the characters "<tt>/:!*?</tt>".
- Try to use unique names.
The component database may be queried using s_clib_search(). A null-terminated buffer containing symbol data (suitable for loading using o_read_buffer()) may be obtained using s_clib_symbol_get_data(). If an exact symbol name is known, the symbol data may be requested directly using s_clib_symbol_get_data_by_name().
Library Commands
A program or set of programs can be used as a component source. The procedure used to add such a source from a gEDA rc file is:
(component-library-command listcmd getcmd name)
This is implemented by g_rc_component_library_command(), which is a wrapper for s_clib_add_command().
The list command will be executed with no further arguments, and should output a list of available symbol names on stdout. The get command will have a symbol name appended to it as the final argument, and should output gEDA symbol data on stdout.
If the command cannot successfully complete, it should exit with non-zero exit status. Anything it has output on stdout will be ignored, and any stderr output displayed to the user.
Library Scheme Procedures
A set of Scheme procedures can be used as a component source. The procedure used to add such a source from a gEDA rc file is:
(component-library-funcs listfunc getfunc name)
This is implemented by g_rc_component_library_funcs(), which is a wrapper for s_clib_add_scm().
listfunc and getfunc must both be Guile procedures. listfunc takes no arguments, and returns a list of symbol names. getfunc takes a symbol name as an argument, and returns gEDA symbol data in a string, or #f if not known.
Definition in file s_clib.c.
1.7.3 
