vtk_fortran_xml_scanner

XML scanner: index the elements of an XML file without loading it.

The scanner reads the file once, in chunks, and records for each element its name, attributes, position in the hierarchy and the positions (in bytes, from 1) of its content in the file; the content itself is never stored, so the memory used does not depend on the data held in the file. The content is read afterwards, on demand, from the recorded positions. The scan can stop at the start tag of a given element (e.g. AppendedData of VTK files, whose content is raw binary).

The module depends only on PENF: it is meant to be moved into FoXy.

Supported XML: elements, attributes (single or double quoted, with the predefined entities), comments, processing instructions and declarations (skipped). CDATA sections are not supported.

Source: src/lib/vtk_fortran_xml_scanner.f90

Contents

• xml_attribute
• xml_element
• xml_scanner
• stream_buffer
• get_attribute
• free
• scan
• add_element
• load
• read_tag
• add_attribute
• add_child
• has_attribute
• find_child
• char_at
• find
• decode_entities
• is_space
• skip_spaces

Variables

Name	Type	Attributes	Description
chunk_size	integer(kind=I8P)	parameter	Size of the chunks read from the file.

Derived Types

xml_attribute

Attribute of an XML element: name and (entities decoded) value.

Components

Name	Type	Attributes	Description
name	character(len=:)	allocatable	Attribute name.
value	character(len=:)	allocatable	Attribute value.

xml_element

Element of an XML file: name, attributes, hierarchy and positions of its content in the file.

The content of an element spans content_start:content_end; its text, the part before the first child element (where VTK puts the data of a DataArray), spans content_start:text_end. Both are empty for a self closing element.

Components

Name	Type	Attributes	Description
name	character(len=:)	allocatable	Element name.
attribute	type(xml_attribute)	allocatable	Attributes.
attributes_number	integer(kind=I4P)		Number of attributes.
parent	integer(kind=I4P)		Index of the parent element (0 for the root).
level	integer(kind=I4P)		Depth in the hierarchy (1 for the root).
child	integer(kind=I4P)	allocatable	Indexes of the children elements.
children_number	integer(kind=I4P)		Number of children elements.
content_start	integer(kind=I8P)		First byte of the content (after the start tag).
text_end	integer(kind=I8P)		Last byte of the text (before the first child or end tag).
content_end	integer(kind=I8P)		Last byte of the content (before the end tag).
is_self_closing	logical		The element is self closing, ``.

Type-Bound Procedures

Name	Attributes	Description
get_attribute	pass(self)	Return the value of an attribute.
has_attribute	pass(self)	Return .true. if an attribute is present.

xml_scanner

Index of the elements of an XML file.

Components

Name	Type	Attributes	Description
element	type(xml_element)	allocatable	Elements, in the order of their start tags.
elements_number	integer(kind=I4P)		Number of elements.
is_stopped	logical		The scan stopped at the start tag of the stop_at element.

Type-Bound Procedures

Name	Attributes	Description
find_child	pass(self)	Return the index of the n-th child element with a given name.
free	pass(self)	Free the index.
scan	pass(self)	Scan an XML file.
add_element	pass(self)	Add an element.

stream_buffer

Buffered reader of a file opened for stream access.

Components

Name	Type	Attributes	Description
unit	integer(kind=I4P)		File unit.
file_size	integer(kind=I8P)		File size in bytes.
first	integer(kind=I8P)		Position in the file of the first character of the buffer.
length	integer(kind=I8P)		Number of valid characters in the buffer.
chars	character(len=:)	allocatable	Buffer.

Type-Bound Procedures

Name	Attributes	Description
char_at	pass(self)	Return the character at a position of the file.
find	pass(self)	Return the position of the next occurrence of a character.
load	pass(self)	Load the chunk starting at a position of the file.

Subroutines

get_attribute

Return the value of an attribute (empty if the attribute is not present).

subroutine get_attribute(self, name, value, is_found)

Arguments

Name	Type	Intent	Attributes	Description
self	class(xml_element)	in		XML element.
name	character(len=*)	in		Attribute name.
value	character(len=:)	out	allocatable	Attribute value.
is_found	logical	out	optional	The attribute is present.

Call graph

free

Free the index.

Attributes: elemental

subroutine free(self)

Arguments

Name	Type	Intent	Attributes	Description
self	class(xml_scanner)	inout		XML scanner.

scan

Scan an XML file, indexing its elements.

The error is 0 on success, 1 if the file cannot be read, 2 if the XML is malformed (unterminated tag, comment or attribute value, end tag not matching the start tag, unclosed element).

subroutine scan(self, filename, error, stop_at)

Arguments

Name	Type	Intent	Attributes	Description
self	class(xml_scanner)	inout		XML scanner.
filename	character(len=*)	in		File name.
error	integer(kind=I4P)	out		Error status.
stop_at	character(len=*)	in	optional	Stop the scan after the start tag of the element with this name.

Call graph

add_element

Add an element, parsing its start tag (the text between '<' and '>').

subroutine add_element(self, tag, id, iostat)

Arguments

Name	Type	Intent	Attributes	Description
self	class(xml_scanner)	inout		XML scanner.
tag	character(len=*)	in		Start tag text.
id	integer(kind=I4P)	out		Index of the new element.
iostat	integer(kind=I4P)	out		Status: non-zero if the tag is malformed.

Call graph

load

Load the chunk starting at a position of the file.

subroutine load(self, pos)

Arguments

Name	Type	Intent	Attributes	Description
self	class(stream_buffer)	inout		File buffer.
pos	integer(kind=I8P)	in		Position in the file.

Call graph

read_tag

Read the text of a tag starting at '<', up to the '>' closing it (outside quoted attribute values).

subroutine read_tag(buffer, lt, tag, gt)

Arguments

Name	Type	Intent	Attributes	Description
buffer	type(stream_buffer)	inout		File buffer.
lt	integer(kind=I8P)	in		Position of '<'.
tag	character(len=:)	out	allocatable	Text of the tag, between ''.
gt	integer(kind=I8P)	out		Position of '>', 0 if the tag is not terminated.

Call graph

add_attribute

Add an attribute to an element.

subroutine add_attribute(element, name, value)

Arguments

Name	Type	Intent	Attributes	Description
element	type(xml_element)	inout		XML element.
name	character(len=*)	in		Attribute name.
value	character(len=*)	in		Attribute value.

Call graph

add_child

Add a child index to an element.

subroutine add_child(element, child)

Arguments

Name	Type	Intent	Attributes	Description
element	type(xml_element)	inout		XML element.
child	integer(kind=I4P)	in		Index of the child.

Call graph

Functions

has_attribute

Return .true. if an attribute is present.

Attributes: pure

Returns: logical

function has_attribute(self, name) result(is_present)

Arguments

Name	Type	Intent	Attributes	Description
self	class(xml_element)	in		XML element.
name	character(len=*)	in		Attribute name.

find_child

Return the index of the n-th (default first) child element with a given name, 0 if there is none.

With parent=0 the root elements are searched.

Attributes: pure

Returns: integer(kind=I4P)

function find_child(self, parent, name, n) result(id)

Arguments

Name	Type	Intent	Attributes	Description
self	class(xml_scanner)	in		XML scanner.
parent	integer(kind=I4P)	in		Index of the parent element, 0 for the root elements.
name	character(len=*)	in		Element name.
n	integer(kind=I4P)	in	optional	Occurrence of the element among the children with that name.

Call graph

char_at

Return the character at a position of the file (a blank beyond its end).

Returns: character(len=1)

function char_at(self, pos) result(c)

Arguments

Name	Type	Intent	Attributes	Description
self	class(stream_buffer)	inout		File buffer.
pos	integer(kind=I8P)	in		Position in the file.

Call graph

find

Return the position of the next occurrence of a character from a position of the file, 0 if there is none.

Returns: integer(kind=I8P)

function find(self, c, pos) result(found)

Arguments

Name	Type	Intent	Attributes	Description
self	class(stream_buffer)	inout		File buffer.
c	character(len=1)	in		Character searched.
pos	integer(kind=I8P)	in		Position in the file where the search starts.

Call graph

decode_entities

Decode the predefined XML entities of a string (< > & " ').

Attributes: pure

Returns: character(len=:)

function decode_entities(string) result(decoded)

Arguments

Name	Type	Intent	Attributes	Description
string	character(len=*)	in		String.

Call graph

is_space

Return .true. if a character is XML white space (blank, tab, line feed, carriage return).

Attributes: elemental

Returns: logical

function is_space(c) result(is_blank)

Arguments

Name	Type	Intent	Attributes	Description
c	character(len=1)	in		Character.

Call graph

skip_spaces

Return the position of the first character not white space from a position of a string (len+1 if none).

Attributes: pure

Returns: integer(kind=I4P)

function skip_spaces(string, c) result(next)

Arguments

Name	Type	Intent	Attributes	Description
string	character(len=*)	in		String.
c	integer(kind=I4P)	in		Start position.

Call graph