NOTE: This version of CaRP is obsolete. This documentation is being left here for those who have not yet upgraded to the current version.

Download | Installation | Configuration | Upgrading from version 2 | Functions | Examples | Donations

Old documentation: Version 2

The following functions are provided by CaRP for use by your web pages. All other functions are intended only for internal use or backward compatibility with earlier versions, and may changed or removed without notice.

Arguments listed in square braces are optional. If more than one optional argument is listed and you wish to set the values of any but the first, you must also set the values of any preceeding arguments.

All CaRP versions:
CarpConf | CarpConfAdd | CarpConfRemove | CarpConfReset | CarpCachePath | CarpCacheShow | CarpCacheFilter | CarpShow | CarpFilter | CarpAggregate | CarpCache | CarpClearCache | CarpClearCacheFile | CarpError | CarpDataPath | CarpAggregatePath | CarpCachePath | CarpAutoCachePath | CarpDecodeDate

CaRP Koi & CaRP Evolution:
CarpMapField | CarpUnmapField

CaRP Evolution:
CarpLoadPlugin | CarpRegisterCallback | CarpUnregisterCallback | SetItemOrder | GetFieldValue

All CaRP versions:

• CarpConf(option name(s), value);
  Sets a CaRP configuration option to the specified value. You may set more than one option to the same value at the same time by listing the option names, separated by pipe characters (|). See the configuration page for a list of available configuration options.
  option name(s): The name of the option or options to set.
  value: The value to which to set the option or options.
   
• CarpConfAdd(option name(s), value [, before or after]);
  Prepends or appends text to an existing CaRP configuration option. You may add to more than one option at the same time by listing the option names, separated by pipe characters (|).
  option name(s): The name of the option or options to set.
  value: The value to add to the option or options.
  before or after: By default, the text is added to the end of the existing value. To add at the beginning instead, do this: CarpConfAdd('option_name','value',0);
   
• CarpConfRemove(option name(s), value);
  Removes the specified text from an existing CaRP configuration option. You may remove from more than one option at the same time by listing the option names, separated by pipe characters (|).
  option name(s): The name of the option or options to set.
  value: The text to remove from the option or options. NOTE: The case of any letters in value must match their case in the existing configuration option.
   
• CarpConfReset();
  Resets all of the values in $carpconf (which control CaRP's behavior and the appearance of newsfeeds) to the default values specified in carp.php. When you are displaying multiple newsfeeds on one page with significantly different appearance, this is a convenient way to reset the configuration.
   
• CarpCachePath();
  Returns the path to CaRP's cache folder, based on the cachepath and cacherelative options.
   
• CarpCacheShow(url [, cachefile [, showit]]);
  This function combines CarpCache and CarpShow (which are explained below). It first caches the raw RSS feed and then displays it. The cache filename for the raw RSS feed is generated automatically. If you specify "cachefile", it will be used to cache the reformatted output. Since the raw RSS feed will be cached, it is less important to specify a cachefile than when calling CarpShow. We recommend using this function rather than CarpCache and CarpShow. See CarpShow for more details.
   
• CarpCacheFilter(url, cachefile);
  This function combines CarpCache and CarpFilter (which are explained below). See CarpCacheShow and CarpCacheFilter for more details.
   
• CarpShow(url [, cachefile [, showit]]);
  Fetches an RSS newsfeed from the internet, a local file, or a local cache file and displays it according to any settings you may have specified. If a cache file was specified, $carpconf['mtime'] will contain the UNIX timestamp for the last time the cache was updated after this function is called.
  url: The address of the RSS newsfeed.
  cachefile: The filename of the cache file in which to store a reformatted copy of the newsfeed, based on your configuration settings. If this argument is omitted, no cache file is used, and the newsfeed is re-fetched and re-formatted every time. We recommend only doing this while working on the formatting (unless using CarpCache, described below, to maintain a local copy of the newsfeed). Once you have decided how you want the feed to be displayed, you will get significantly better performance by specifying a cache file.
  showit: If you set this argument to 0, CarpShow will behave identically to CarpFilter. Note that you do not need to do this or use CarpFilter to get filtering functionality.
   
• CarpFilter(url, cachefile);
  Fetches an RSS newsfeed and saves a number of items from it in a formated based on your configuration settings in a cache file which may later be used by CarpAggregate. Unless you have specified values for the "filterin" or "filterout" options, it won't actually perform any filtering. Note that only item information is cached--because this function is used to aggregate news stories from multiple sources and display them together, channel information is discarded.
  url: The address of the RSS newsfeed.
  cachefile: The filename of the cache file in which to store a reformatted copy of the newsfeed, based on your configuration settings. Unlike CarpShow, CarpFilter requires a cache file to be specified. Note that while you are working on the formatting of a newsfeed, you will need to delete the cache file each time you wish to change it's appearance in order for it to update.
   
• CarpAggregate(cache file(s));
  Retrieves the most recent items from the cache file or files listed and displays them, newest first. Note that the ordering of items may not be correct unless the newsfeeds supply either a pubDate or dc:date for each item.
  cache file(s): The name or names of any number of cache files created by CarpFilter. When specifying more than one cache file, separate the filenames with a pipe character (|). Do not include spaces before or after the filenames.
   
• CarpCache(url, cachefile);
  Fetches an RSS newsfeed and stores it, unmodified, in a local cache file. The cache file is refreshed if it is older than the number of minutes specified in the cacheinterval configuration setting, or based on the value of cachetime. This function returns 1 if it was necessary to refresh the cache, and 0 if not. After this function completes, $carpconf['mtime'] will contain the UNIX timestamp for the last time the cache was updated.
  url: The address of the RSS newsfeed.
  cachefile: The filename of the local cache file.
   
• CarpClearCache(which);
  This function deletes all of the files in the cache folder indicated by "which". Valid values for "which" are 0 (CarpAggregatePath), 1 (CarpCachePath) and 2 (CarpAutoCachePath).
   
• CarpClearCacheFile(which, filename);
  This function deletes the indicated file from the cache folder indicated by "which". Valid values for "which" are as indicated above. To delete a file from the auto cache directory, indicate the URL of the newsfeed instead of the filename.
   
• CarpError(error message[, mark cache updated]);
  This function is used by CaRP and CaRP Evolution plugins to display error messages.
   
• CarpDataPath();
  This function returns the full path to the directory which contains the cache directories.
   
• CarpAggregatePath();
  This function returns the full path to the directory where the results of CarpFilter are stored.
   
• CarpCachePath();
  This function returns the full path to the directory where the results of CarpShow and CarpCache are stored.
   
• CarpAutoCachePath();
  This function returns the full path to the directory where raw newsfeeds are stored by CarpCacheShow and CarpCacheFilter.
   
• CarpDecodeDate(date as text);
  This function is used by CaRP and CaRP Evolution plugins to convert a text date to a UNIX timestamp. See the CaRP Evolution API documentation for more information.
   

• CarpMapField(CaRP field name, RSS field name [, is a channel field [, priority]]);
  Changes the mapping of RSS fields to CaRP's display fields in order to handle incorrectly formatted newsfeeds, and to provide compatibility with extensions to RSS not supported by the CaRP's default configuration.
  CaRP field name: One of the following: url, title, desc, date, imageurl, imagelink, imagealt, imagewidth, imageheight; and for items (but not the channel): author.
  RSS field name: The name of the field from the RSS file, including the names of the parents of the field, as follows:
  • For top-level children of the channel or of an item, just use the name of that field.
  • For anything below the top level, concatenate the names of each containing field, separating each with a "caret" character (^). For example, for an item's image's width, "IMAGE^WIDTH", or for an IMAGE:ITEM's DC:TITLE, "IMAGE:ITEM^DC:TITLE". You may also map attributes, for example, the RDF:RESOURCE attribute of an IMAGE:ITEM would be specified as "IMAGE:ITEM^RDF:RESOURCE".
  is a channel field: By default, CaRP assumes that you wish to map an item field. To set the mapping for a channel field, enter 1 here. The default (an item field) is 0.
  priority: Since more than one RSS field may be mapped to the same output field, CaRP must be able to decide which to display if the newsfeed specifies more than one. By default, CaRP places lower priority on fields mapped using this function than on it's default field mapping. To override this default, set the value of priority to a number 6 or higher. You may specify any number of mappings to the same CaRP display field, and use the priority setting to determine which to display when more than one is present.
   
• CarpUnmapField(CaRP field name, RSS field name [, is a channel field]);
  Removes field mappings created by CarpMapField, or default field mappings. See above for an explanation of the arguments.
   

• CarpLoadPlugin(plugin filename);
  Loads the plugin file named. The plugin file must be located in a directory named "plugins", which must be located in the same directory as carp.php. If the plugin is located somewhere else, it cannot be loaded using this function.
   
• CarpRegisterCallback(object, function, phase[, option]);
  This function is used by plugins. See the CaRP Evolution API documentation for more information.
   
• CarpUnregisterCallback(object, function[, phase[, option]]);
  This function is used by plugins. See the CaRP Evolution API documentation for more information.
   
• $carpconf['parser']->SetItemOrder(order);
  This function is used by plugins. See the CaRP Evolution API documentation for more information.
   
• $carpconf['parser']->GetFieldValue(fieldname[, is a channel field]);
  This function is used by plugins. See the CaRP Evolution API documentation for more information.