~ubuntu-branches/ubuntu/natty/raptor/natty-security

<?xml version="1.0" encoding="iso-8859-1"?>

<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" 

               "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [

<!ENTITY version SYSTEM "version.xml">

]>

<refentry id="raptor-section-feature">

<refmeta>

<refentrytitle role="top_of_page" id="raptor-section-feature.top_of_page">Features</refentrytitle>

<manvolnum>3</manvolnum>

<refmiscinfo>RAPTOR Library</refmiscinfo>

</refmeta>

<refnamediv>

<refname>Features</refname>

<refpurpose>Parser and Serializer features</refpurpose>

</refnamediv>

<refsynopsisdiv id="raptor-section-feature.synopsis" role="synopsis">

<title role="synopsis.title">Synopsis</title>

<synopsis>

enum                <link linkend="raptor-feature">raptor_feature</link>;

unsigned <link linkend="int">int</link>        <link linkend="raptor-get-feature-count">raptor_get_feature_count</link>            (void);

<link linkend="int">int</link>                 <link linkend="raptor-features-enumerate">raptor_features_enumerate</link>           (const <link linkend="raptor-feature">raptor_feature</link> feature,

                                                         const <link linkend="char">char</link> **name,

                                                         <link linkend="raptor-uri">raptor_uri</link> **uri,

                                                         const <link linkend="char">char</link> **label);

<link linkend="raptor-feature">raptor_feature</link>      <link linkend="raptor-feature-from-uri">raptor_feature_from_uri</link>             (<link linkend="raptor-uri">raptor_uri</link> *uri);

<link linkend="int">int</link>                 <link linkend="raptor-feature-value-type">raptor_feature_value_type</link>           (const <link linkend="raptor-feature">raptor_feature</link> feature);

</synopsis>

</refsynopsisdiv>

<refsect1 id="raptor-section-feature.description" role="desc">

<title role="desc.title">Description</title>

<para>

Optional parameters for <link linkend="raptor-parser"><type>raptor_parser</type></link> and <link linkend="raptor-serializer"><type>raptor_serializer</type></link>

objects that can be get and set.  Utility functions also exist

to enumerate them, their description and the parameter type

taken.

</para>

</refsect1>

<refsect1 id="raptor-section-feature.details" role="details">

<title role="details.title">Details</title>

<refsect2 id="raptor-feature" role="enum">

<title>enum raptor_feature</title>

<indexterm zone="raptor-feature"><primary sortas="raptor_feature">raptor_feature</primary></indexterm><programlisting>typedef enum {

  RAPTOR_FEATURE_SCANNING,

  RAPTOR_FEATURE_ASSUME_IS_RDF,

  RAPTOR_FEATURE_ALLOW_NON_NS_ATTRIBUTES,

  RAPTOR_FEATURE_ALLOW_OTHER_PARSETYPES,

  RAPTOR_FEATURE_ALLOW_BAGID,

  RAPTOR_FEATURE_ALLOW_RDF_TYPE_RDF_LIST,

  RAPTOR_FEATURE_NORMALIZE_LANGUAGE,

  RAPTOR_FEATURE_NON_NFC_FATAL,

  RAPTOR_FEATURE_WARN_OTHER_PARSETYPES,

  RAPTOR_FEATURE_CHECK_RDF_ID,

  RAPTOR_FEATURE_RELATIVE_URIS,

  RAPTOR_FEATURE_START_URI,

  RAPTOR_FEATURE_WRITER_AUTO_INDENT,

  RAPTOR_FEATURE_WRITER_AUTO_EMPTY,

  RAPTOR_FEATURE_WRITER_INDENT_WIDTH,

  RAPTOR_FEATURE_WRITER_XML_VERSION,

  RAPTOR_FEATURE_WRITER_XML_DECLARATION,

  RAPTOR_FEATURE_NO_NET,

  RAPTOR_FEATURE_RESOURCE_BORDER,

  RAPTOR_FEATURE_LITERAL_BORDER,

  RAPTOR_FEATURE_BNODE_BORDER,

  RAPTOR_FEATURE_RESOURCE_FILL,

  RAPTOR_FEATURE_LITERAL_FILL,

  RAPTOR_FEATURE_BNODE_FILL,

  RAPTOR_FEATURE_HTML_TAG_SOUP,

  RAPTOR_FEATURE_MICROFORMATS,

  RAPTOR_FEATURE_HTML_LINK,

  RAPTOR_FEATURE_WWW_TIMEOUT,

  RAPTOR_FEATURE_WRITE_BASE_URI,

  RAPTOR_FEATURE_WWW_HTTP_CACHE_CONTROL,

  RAPTOR_FEATURE_WWW_HTTP_USER_AGENT,

  RAPTOR_FEATURE_JSON_CALLBACK,

  RAPTOR_FEATURE_JSON_EXTRA_DATA,

  RAPTOR_FEATURE_RSS_TRIPLES,

  RAPTOR_FEATURE_ATOM_ENTRY_URI,

  RAPTOR_FEATURE_PREFIX_ELEMENTS,

  RAPTOR_FEATURE_LAST = RAPTOR_FEATURE_PREFIX_ELEMENTS

} raptor_feature;

</programlisting>

<para>

Raptor parser, serializer or XML writer features.</para>

<para>

</para><variablelist role="enum">

<varlistentry id="RAPTOR-FEATURE-SCANNING--CAPS" role="constant">

<term><literal>RAPTOR_FEATURE_SCANNING</literal></term>

<listitem><simpara> If true (default false), the RDF/XML

  parser will look for embedded rdf:RDF elements inside the XML

  content, and not require that the XML start with an rdf:RDF root

  element.

</simpara></listitem>

</varlistentry>

<varlistentry id="RAPTOR-FEATURE-ASSUME-IS-RDF--CAPS" role="constant">

<term><literal>RAPTOR_FEATURE_ASSUME_IS_RDF</literal></term>

<listitem><simpara> If true (default false) then the

  RDF/XML parser will assume the content is RDF/XML, not require

  that rdf:RDF root element, and immediately interpret the content

  as RDF/XML.

</simpara></listitem>

</varlistentry>

<varlistentry id="RAPTOR-FEATURE-ALLOW-NON-NS-ATTRIBUTES--CAPS" role="constant">

<term><literal>RAPTOR_FEATURE_ALLOW_NON_NS_ATTRIBUTES</literal></term>

<listitem><simpara> If true (default true)

  then the RDF/XML parser will allow non-XML namespaced attributes

  to be accepted as well as rdf: namespaced ones.  For example,

  'about' and 'ID' will be interpreted as if they were rdf:about

  and rdf:ID respectively.

</simpara></listitem>

</varlistentry>

<varlistentry id="RAPTOR-FEATURE-ALLOW-OTHER-PARSETYPES--CAPS" role="constant">

<term><literal>RAPTOR_FEATURE_ALLOW_OTHER_PARSETYPES</literal></term>

<listitem><simpara> If true (default true)

  then the RDF/XML parser will allow unknown parsetypes to be

  present and will pass them on to the user.  Unimplemented at

  present.

</simpara></listitem>

</varlistentry>

<varlistentry id="RAPTOR-FEATURE-ALLOW-BAGID--CAPS" role="constant">

<term><literal>RAPTOR_FEATURE_ALLOW_BAGID</literal></term>

<listitem><simpara> If true (default true) then the

  RDF/XML parser will support the rdf:bagID attribute that was

  removed from the RDF/XML language when it was revised.  This

  support may be removed in future.

</simpara></listitem>

</varlistentry>

<varlistentry id="RAPTOR-FEATURE-ALLOW-RDF-TYPE-RDF-LIST--CAPS" role="constant">

<term><literal>RAPTOR_FEATURE_ALLOW_RDF_TYPE_RDF_LIST</literal></term>

<listitem><simpara> If true (default false)

  then the RDF/XML parser will generate the idList rdf:type

  rdf:List triple in the handling of rdf:parseType="Collection".

  This triple was removed during the revising of RDF/XML after

  collections were initially added.

</simpara></listitem>

</varlistentry>

<varlistentry id="RAPTOR-FEATURE-NORMALIZE-LANGUAGE--CAPS" role="constant">

<term><literal>RAPTOR_FEATURE_NORMALIZE_LANGUAGE</literal></term>

<listitem><simpara> If true (default true) then

  XML language values such as from xml:lang will be normalized to

  lowercase.

</simpara></listitem>

</varlistentry>

<varlistentry id="RAPTOR-FEATURE-NON-NFC-FATAL--CAPS" role="constant">

<term><literal>RAPTOR_FEATURE_NON_NFC_FATAL</literal></term>

<listitem><simpara> If true (default false) then

 illegal Unicode Normal Form C in literals will give a fatal

 error, otherwise just a warning.

</simpara></listitem>

</varlistentry>

<varlistentry id="RAPTOR-FEATURE-WARN-OTHER-PARSETYPES--CAPS" role="constant">

<term><literal>RAPTOR_FEATURE_WARN_OTHER_PARSETYPES</literal></term>

<listitem><simpara> If true (default true) then 

  the RDF/XML parser will warn about unknown rdf:parseType values.

</simpara></listitem>

</varlistentry>

<varlistentry id="RAPTOR-FEATURE-CHECK-RDF-ID--CAPS" role="constant">

<term><literal>RAPTOR_FEATURE_CHECK_RDF_ID</literal></term>

<listitem><simpara> If true (default true) then the

  RDF/XML will check rdf:ID attribute values for duplicates and

  cause an error if any are found.

</simpara></listitem>

</varlistentry>

<varlistentry id="RAPTOR-FEATURE-RELATIVE-URIS--CAPS" role="constant">

<term><literal>RAPTOR_FEATURE_RELATIVE_URIS</literal></term>

<listitem><simpara> If true (default true) then

  relative URIs will be used wherever possible when serializing.

</simpara></listitem>

</varlistentry>

<varlistentry id="RAPTOR-FEATURE-START-URI--CAPS" role="constant">

<term><literal>RAPTOR_FEATURE_START_URI</literal></term>

<listitem><simpara> Set the start URI for serlalizing to use.

</simpara></listitem>

</varlistentry>

<varlistentry id="RAPTOR-FEATURE-WRITER-AUTO-INDENT--CAPS" role="constant">

<term><literal>RAPTOR_FEATURE_WRITER_AUTO_INDENT</literal></term>

<listitem><simpara> Automatically indent elements when

  seriailizing.

</simpara></listitem>

</varlistentry>

<varlistentry id="RAPTOR-FEATURE-WRITER-AUTO-EMPTY--CAPS" role="constant">

<term><literal>RAPTOR_FEATURE_WRITER_AUTO_EMPTY</literal></term>

<listitem><simpara> Automatically detect and

  abbreviate empty elements when serializing.

</simpara></listitem>

</varlistentry>

<varlistentry id="RAPTOR-FEATURE-WRITER-INDENT-WIDTH--CAPS" role="constant">

<term><literal>RAPTOR_FEATURE_WRITER_INDENT_WIDTH</literal></term>

<listitem><simpara> Integer number of spaces to use

  for each indent level when serializing with auto indent.

</simpara></listitem>

</varlistentry>

<varlistentry id="RAPTOR-FEATURE-WRITER-XML-VERSION--CAPS" role="constant">

<term><literal>RAPTOR_FEATURE_WRITER_XML_VERSION</literal></term>

<listitem><simpara> Integer XML version XML 1.0 (10) or XML 1.1 (11)

</simpara></listitem>

</varlistentry>

<varlistentry id="RAPTOR-FEATURE-WRITER-XML-DECLARATION--CAPS" role="constant">

<term><literal>RAPTOR_FEATURE_WRITER_XML_DECLARATION</literal></term>

<listitem><simpara> Write XML 1.0 or 1.1 declaration.

</simpara></listitem>

</varlistentry>

<varlistentry id="RAPTOR-FEATURE-NO-NET--CAPS" role="constant">

<term><literal>RAPTOR_FEATURE_NO_NET</literal></term>

<listitem><simpara> Deny network requests.

</simpara></listitem>

</varlistentry>

<varlistentry id="RAPTOR-FEATURE-RESOURCE-BORDER--CAPS" role="constant">

<term><literal>RAPTOR_FEATURE_RESOURCE_BORDER</literal></term>

<listitem><simpara> Border color of resource

  nodes for GraphViz DOT serializer.

</simpara></listitem>

</varlistentry>

<varlistentry id="RAPTOR-FEATURE-LITERAL-BORDER--CAPS" role="constant">

<term><literal>RAPTOR_FEATURE_LITERAL_BORDER</literal></term>

<listitem><simpara> Border color of literal nodes

  for GraphViz DOT serializer.

</simpara></listitem>

</varlistentry>

<varlistentry id="RAPTOR-FEATURE-BNODE-BORDER--CAPS" role="constant">

<term><literal>RAPTOR_FEATURE_BNODE_BORDER</literal></term>

<listitem><simpara> Border color of blank nodes for

  GraphViz DOT serializer.

</simpara></listitem>

</varlistentry>

<varlistentry id="RAPTOR-FEATURE-RESOURCE-FILL--CAPS" role="constant">

<term><literal>RAPTOR_FEATURE_RESOURCE_FILL</literal></term>

<listitem><simpara> Fill color of resource nodes

  for GraphViz DOT serializer.

</simpara></listitem>

</varlistentry>

<varlistentry id="RAPTOR-FEATURE-LITERAL-FILL--CAPS" role="constant">

<term><literal>RAPTOR_FEATURE_LITERAL_FILL</literal></term>

<listitem><simpara> Fill color of literal nodes for

  GraphViz DOT serializer.

</simpara></listitem>

</varlistentry>

<varlistentry id="RAPTOR-FEATURE-BNODE-FILL--CAPS" role="constant">

<term><literal>RAPTOR_FEATURE_BNODE_FILL</literal></term>

<listitem><simpara> Fill color of blank nodes for

  GraphViz DOT serializer.

</simpara></listitem>

</varlistentry>

<varlistentry id="RAPTOR-FEATURE-HTML-TAG-SOUP--CAPS" role="constant">

<term><literal>RAPTOR_FEATURE_HTML_TAG_SOUP</literal></term>

<listitem><simpara> Use a lax HTML parser if an XML parser

  fails when read HTML for GRDDL parser.

</simpara></listitem>

</varlistentry>

<varlistentry id="RAPTOR-FEATURE-MICROFORMATS--CAPS" role="constant">

<term><literal>RAPTOR_FEATURE_MICROFORMATS</literal></term>

<listitem><simpara> Look for microformats for GRDDL parser.

</simpara></listitem>

</varlistentry>

<varlistentry id="RAPTOR-FEATURE-HTML-LINK--CAPS" role="constant">

<term><literal>RAPTOR_FEATURE_HTML_LINK</literal></term>

<listitem><simpara> Look for head &lt;link&gt; to type rdf/xml

  for GRDDL parser.

</simpara></listitem>

</varlistentry>

<varlistentry id="RAPTOR-FEATURE-WWW-TIMEOUT--CAPS" role="constant">

<term><literal>RAPTOR_FEATURE_WWW_TIMEOUT</literal></term>

<listitem><simpara> Set timeout for internal WWW URI requests

  for GRDDL parser.

</simpara></listitem>

</varlistentry>

<varlistentry id="RAPTOR-FEATURE-WRITE-BASE-URI--CAPS" role="constant">

<term><literal>RAPTOR_FEATURE_WRITE_BASE_URI</literal></term>

<listitem><simpara> Write <parameter>base</parameter> directive for Turtle/N3.

</simpara></listitem>

</varlistentry>

<varlistentry id="RAPTOR-FEATURE-WWW-HTTP-CACHE-CONTROL--CAPS" role="constant">

<term><literal>RAPTOR_FEATURE_WWW_HTTP_CACHE_CONTROL</literal></term>

<listitem><simpara> HTTP Cache-Control: header

</simpara></listitem>

</varlistentry>

<varlistentry id="RAPTOR-FEATURE-WWW-HTTP-USER-AGENT--CAPS" role="constant">

<term><literal>RAPTOR_FEATURE_WWW_HTTP_USER_AGENT</literal></term>

<listitem><simpara> HTTP User-Agent: header

</simpara></listitem>

</varlistentry>

<varlistentry id="RAPTOR-FEATURE-JSON-CALLBACK--CAPS" role="constant">

<term><literal>RAPTOR_FEATURE_JSON_CALLBACK</literal></term>

<listitem><simpara> JSON serializer callback function.

</simpara></listitem>

</varlistentry>

<varlistentry id="RAPTOR-FEATURE-JSON-EXTRA-DATA--CAPS" role="constant">

<term><literal>RAPTOR_FEATURE_JSON_EXTRA_DATA</literal></term>

<listitem><simpara> JSON serializer extra top-level data

</simpara></listitem>

</varlistentry>

<varlistentry id="RAPTOR-FEATURE-RSS-TRIPLES--CAPS" role="constant">

<term><literal>RAPTOR_FEATURE_RSS_TRIPLES</literal></term>

<listitem><simpara> Atom/RSS serializer writes extra RDF triples it finds (none, rdf-xml, atom-triples)

</simpara></listitem>

</varlistentry>

<varlistentry id="RAPTOR-FEATURE-ATOM-ENTRY-URI--CAPS" role="constant">

<term><literal>RAPTOR_FEATURE_ATOM_ENTRY_URI</literal></term>

<listitem><simpara> Atom entry URI.  If given, generate an Atom Entry Document with the item having the given URI, otherwise generate an Atom Feed Document with any items found.

</simpara></listitem>

</varlistentry>

<varlistentry id="RAPTOR-FEATURE-PREFIX-ELEMENTS--CAPS" role="constant">

<term><literal>RAPTOR_FEATURE_PREFIX_ELEMENTS</literal></term>

<listitem><simpara> Integer. If set, generate Atom/RSS1.0 documents with prefixed elements, otherwise unprefixed.

</simpara></listitem>

</varlistentry>

<varlistentry id="RAPTOR-FEATURE-LAST--CAPS" role="constant">

<term><literal>RAPTOR_FEATURE_LAST</literal></term>

<listitem><simpara> Internal

</simpara></listitem>

</varlistentry>

</variablelist></refsect2>

<refsect2 id="raptor-get-feature-count" role="function">

<title>raptor_get_feature_count ()</title>

<indexterm zone="raptor-get-feature-count"><primary sortas="raptor_get_feature_count">raptor_get_feature_count</primary></indexterm><programlisting>unsigned <link linkend="int">int</link>        raptor_get_feature_count            (void);</programlisting>

<para>

Get the count of features defined.

</para>

<para>

This is prefered to the compile time-only symbol <link linkend="RAPTOR-FEATURE-LAST--CAPS"><type>RAPTOR_FEATURE_LAST</type></link>

and returns a count of the number of features which is

<link linkend="RAPTOR-FEATURE-LAST--CAPS"><type>RAPTOR_FEATURE_LAST</type></link>+1.</para>

<para>

</para><variablelist role="params">

<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> count of features in the <link linkend="raptor-feature"><type>raptor_feature</type></link> enumeration

</simpara></listitem></varlistentry>

</variablelist></refsect2>

<refsect2 id="raptor-features-enumerate" role="function">

<title>raptor_features_enumerate ()</title>

<indexterm zone="raptor-features-enumerate"><primary sortas="raptor_features_enumerate">raptor_features_enumerate</primary></indexterm><programlisting><link linkend="int">int</link>                 raptor_features_enumerate           (const <link linkend="raptor-feature">raptor_feature</link> feature,

                                                         const <link linkend="char">char</link> **name,

                                                         <link linkend="raptor-uri">raptor_uri</link> **uri,

                                                         const <link linkend="char">char</link> **label);</programlisting>

<para>

Get list of syntax features.

</para>

<para>

If uri is not NULL, a pointer to a new raptor_uri is returned

that must be freed by the caller with <link linkend="raptor-free-uri"><function>raptor_free_uri()</function></link>.

</para>

<para>

<link linkend="raptor-init"><function>raptor_init()</function></link> MUST have been called before calling this function.

Use <link linkend="raptor-features-enumerate-v2"><function>raptor_features_enumerate_v2()</function></link> if using raptor_world APIs.</para>

<para>

</para><variablelist role="params">

<varlistentry><term><parameter>feature</parameter>&#160;:</term>

<listitem><simpara> feature enumeration (0+)

</simpara></listitem></varlistentry>

<varlistentry><term><parameter>name</parameter>&#160;:</term>

<listitem><simpara> pointer to store feature short name (or NULL)

</simpara></listitem></varlistentry>

<varlistentry><term><parameter>uri</parameter>&#160;:</term>

<listitem><simpara> pointer to store feature URI (or NULL)

</simpara></listitem></varlistentry>

<varlistentry><term><parameter>label</parameter>&#160;:</term>

<listitem><simpara> pointer to feature label (or NULL)

</simpara></listitem></varlistentry>

<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> 0 on success, &lt;0 on failure, &gt;0 if feature is unknown

</simpara></listitem></varlistentry>

</variablelist></refsect2>

<refsect2 id="raptor-feature-from-uri" role="function">

<title>raptor_feature_from_uri ()</title>

<indexterm zone="raptor-feature-from-uri"><primary sortas="raptor_feature_from_uri">raptor_feature_from_uri</primary></indexterm><programlisting><link linkend="raptor-feature">raptor_feature</link>      raptor_feature_from_uri             (<link linkend="raptor-uri">raptor_uri</link> *uri);</programlisting>

<para>

Turn a feature URI into an feature enum.

</para>

<para>

The allowed feature URIs are available via <link linkend="raptor-features-enumerate"><function>raptor_features_enumerate()</function></link>.

</para>

<para>

<link linkend="raptor-init"><function>raptor_init()</function></link> MUST have been called before calling this function.

Use <link linkend="raptor-feature-from-uri-v2"><function>raptor_feature_from_uri_v2()</function></link> if using raptor_world APIs.</para>

<para>

</para><variablelist role="params">

<varlistentry><term><parameter>uri</parameter>&#160;:</term>

<listitem><simpara> feature URI

</simpara></listitem></varlistentry>

<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> &lt; 0 if the feature is unknown

</simpara></listitem></varlistentry>

</variablelist></refsect2>

<refsect2 id="raptor-feature-value-type" role="function">

<title>raptor_feature_value_type ()</title>

<indexterm zone="raptor-feature-value-type"><primary sortas="raptor_feature_value_type">raptor_feature_value_type</primary></indexterm><programlisting><link linkend="int">int</link>                 raptor_feature_value_type           (const <link linkend="raptor-feature">raptor_feature</link> feature);</programlisting>

<para>

Get the type of a features.

</para>

<para>

The type of the <parameter>feature</parameter> is 0=integer , 1=string.  Other values are

undefined.  Most features are integer values and use

raptor_set_feature and <link linkend="raptor-get-feature"><function>raptor_get_feature()</function></link>

( raptor_serializer_set_feature <link linkend="raptor-serializer-get-feature"><function>raptor_serializer_get_feature()</function></link> )

</para>

<para>

String value features use <link linkend="raptor-parser-set-feature-string"><function>raptor_parser_set_feature_string()</function></link> and

<link linkend="raptor-parser-get-feature-string"><function>raptor_parser_get_feature_string()</function></link>

( <link linkend="raptor-serializer-set-feature-string"><function>raptor_serializer_set_feature_string()</function></link>

and <link linkend="raptor-serializer-get-feature-string"><function>raptor_serializer_get_feature_string()</function></link> )</para>

<para>

</para><variablelist role="params">

<varlistentry><term><parameter>feature</parameter>&#160;:</term>

<listitem><simpara> raptor serializer or parser feature

</simpara></listitem></varlistentry>

<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the type of the feature or &lt;0 if <parameter>feature</parameter> is unknown

</simpara></listitem></varlistentry>

</variablelist></refsect2>

</refsect1>

</refentry>