.. index:: single: gpx_protocol
.. _gpx_protocol/0:

.. rst-class:: right

**protocol**

``gpx_protocol``
================

GPX 1.1 parser, generator, and validator protocol.

| **Availability:** 
|    ``logtalk_load(gpx(loader))``

| **Author:** Paulo Moura
| **Version:** 1:0:0
| **Date:** 2026-08-02

| **Compilation flags:**
|    ``static``


| **Dependencies:**
|   (none)


| **Remarks:**
|    (none)

| **Inherited public predicates:**
|    (none)

.. contents::
   :local:
   :backlinks: top

Public predicates
-----------------

.. index:: parse/2
.. _gpx_protocol/0::parse/2:

``parse/2``
^^^^^^^^^^^

Parses a GPX 1.1 document from the given source (``file(Path)``, ``stream(Stream)``, ``codes(List)``, ``chars(List)``, or ``atom(Atom)``) into a native GPX term.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``parse(Source,GPX)``
| **Mode and number of proofs:**
|    ``parse(++compound,--compound)`` - ``one_or_error``

| **Exceptions:**
|    ``Source`` is not a ground term:
|        ``instantiation_error``
|    ``Source`` is a ground term but not a valid source:
|        ``domain_error(gpx_source,Source)``
|    The source does not contain a valid GPX 1.1 document:
|        ``domain_error(gpx,Source)``


------------

.. index:: generate/2
.. _gpx_protocol/0::generate/2:

``generate/2``
^^^^^^^^^^^^^^

Generates a GPX 1.1 document to the given sink (``file(Path)``, ``stream(Stream)``, ``codes(List)``, ``chars(List)``, or ``atom(Atom)``) from a native GPX term.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``generate(Sink,GPX)``
| **Mode and number of proofs:**
|    ``generate(+compound,++compound)`` - ``one_or_error``

| **Exceptions:**
|    ``Sink`` is a variable:
|        ``instantiation_error``
|    ``Sink`` is neither a variable nor a valid sink:
|        ``domain_error(gpx_sink,Sink)``
|    ``GPX`` is not ground:
|        ``instantiation_error``
|    ``GPX`` is ground but not a valid native GPX term:
|        ``domain_error(gpx,GPX)``


------------

.. index:: validate/1
.. _gpx_protocol/0::validate/1:

``validate/1``
^^^^^^^^^^^^^^

True iff the argument is a valid native GPX 1.1 term.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``validate(GPX)``
| **Mode and number of proofs:**
|    ``validate(@term)`` - ``zero_or_one_or_error``

| **Exceptions:**
|    ``GPX`` is a variable:
|        ``instantiation_error``


------------

.. index:: validate/2
.. _gpx_protocol/0::validate/2:

``validate/2``
^^^^^^^^^^^^^^

Validates a native GPX 1.1 term, returning all detected errors as reason terms whose final argument is the failing path. List indexes in paths are zero-based.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``validate(GPX,Errors)``
| **Mode and number of proofs:**
|    ``validate(@term,-list(compound))`` - ``one_or_error``

| **Exceptions:**
|    ``GPX`` is a variable:
|        ``instantiation_error``

| **Remarks:**

    - invalid_gpx_term(Path): The term is not a supported native GPX term.
    - invalid_creator(Path): The required creator is not an atom.
    - invalid_properties(Path): A properties argument is not a list.
    - invalid_list(Path): A repeated GPX value is not represented by a list.
    - invalid_value(Value, Path): A value does not satisfy the required GPX type or range.
    - invalid_date_time(Value, Path): A value is not an atom in the XML Schema 1.0 ``dateTime`` lexical space.
    - invalid_year(Value, Path): A value is not an atom in the XML Schema 1.0 ``gYear`` lexical space.
    - invalid_bounds(Path): The minimum latitude is greater than the maximum latitude.
    - invalid_extensions(Path): The extension nodes are not valid non-GPX namespaced XML elements.
    - duplicate_property(Name, Path): A property occurs more than once in the enclosing GPX term.
    - unknown_property(Property, Path): The property is not supported by the enclosing GPX term.


------------

.. index:: xml_to_gpx/2
.. _gpx_protocol/0::xml_to_gpx/2:

``xml_to_gpx/2``
^^^^^^^^^^^^^^^^

Converts an XML parser document term into a native GPX 1.1 term.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``xml_to_gpx(XML,GPX)``
| **Mode and number of proofs:**
|    ``xml_to_gpx(+compound,-compound)`` - ``one_or_error``

| **Exceptions:**
|    ``XML`` is not a ground term:
|        ``instantiation_error``
|    ``XML`` is a ground term but not a valid GPX 1.1 XML document term:
|        ``domain_error(gpx,XML)``


------------

.. index:: gpx_to_xml/2
.. _gpx_protocol/0::gpx_to_xml/2:

``gpx_to_xml/2``
^^^^^^^^^^^^^^^^

Converts a native GPX 1.1 term into an XML parser document term.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``gpx_to_xml(GPX,XML)``
| **Mode and number of proofs:**
|    ``gpx_to_xml(+compound,-compound)`` - ``one_or_error``

| **Exceptions:**
|    ``GPX`` is not a ground term:
|        ``instantiation_error``
|    ``GPX`` is a ground term but not a valid native GPX term:
|        ``domain_error(gpx,GPX)``


------------

Protected predicates
--------------------

(none)

Private predicates
------------------

(none)

Operators
---------

(none)