mdbs99 / xavier

Xavier is a small object-oriented XML library for Lazarus and Delphi

Xavier

Xavier is a small XML library, object-oriented, and cross-platform that simplifies the work with XML files and streams using XPath.

ATTENTION: We're still in a very early alpha version, the API may and will change frequently. Please, use it at your own risk, until we release version 1.0.

Table of Contents

• Overview
• Installing
  • Dependencies
  • On Lazarus
  • On Delphi
• Getting Started
  • Find a Node
  • Add Node
  • Childs Count
  • Find Attribute
  • Add Attribute
• License

Overview

This API is being written in Free Pascal and Lazarus. However, it is also compatible with Delphi.

Most XML libraries are very complex. Each class has so many methods that could be hard to use and understand them. These implementations are very procedural too.

The main goal is to replace common procedural code, which could have so many conditionals and variables, to a declarative and object-oriented code to work more easily with XML.

The code follows a restrict rules about naming and style, as prefixes and suffixes, to help programmers to find the correct class or method to do the job quickly.

Installing

Clone the repository in some directory in your computer.

Dependencies

Internally, this project uses the built-in XML library for each compiler.

Besides that, we are using other libraries:

• James — is a collection of classes and interfaces for truly object-oriented projects.
• mORMot — client-server ORM SOA MVC framework for Delphi 6 up to latest Delphi and FPC

On Lazarus

It has been tested using these versions:

• FPC 3.1.1 revision 40491
• Lazarus 2.1.0 revision 59757

To install on Lazarus:

• Make sure that you have JamesLib.lpk, and mormot_base.lpk available - see dependencies
• Open the package in /pkg/XavierLib.lpk
• Compile it
• That's all.

The IDE will be aware about XavierLib Package to use in any project.

Considering <xavier> as the path where you have saved the sources, your project must include these paths:

On Delphi

Considering <xavier> as the path where you have saved the sources, you must include these paths in your project:

• Search Path <xavier>\src;<xavier>\src\delphi

Getting Started

You can find some examples to use Xavier in its own source. Just take a look into Xavier*Tests units.

Additionally, below you can find the basics to start.

Take this XML for all examples below:

<?xml version="1.0" encoding="UTF-8"?>
<root>
  <foo a1="f1" a2="f2">
    <value>foo</value>
  </foo>
  <bar a1="b1" a2="b2">
    <value>bar</value>
  </bar>
</root>

Find a Node

If you want to find the value child node of foo node, do this:

var
  pack: IXMLPack;
  n: IXMLNode;
begin
  pack := TXMLPack.Create(
    TDataFile.Create('file.xml').Ref.Stream
  );
  n := pack.Node('/root/foo/value');
  ShowMessage(n.Text); // "foo"
end.

In fact, we don't need variables pack or n. Just call directly:

begin
  ShowMessage(
    TXMLPack.Create(
      TDataFile.Create('file.xml').Ref.Stream
    )
    .Ref
    .Node('/root/foo/value')
    .Text
  ); // "foo"
end.

Add Node

You can add a node easily doing this:

// add a new node: name="item" value="a"
begin
  TXMLPack.Create(TDataFile.Create('file.xml').Ref.Stream)
    .Ref
    .Node('/root')
    .Add('item')
    .Text('a')
end;

Childs Count

You can count how many childs a node have doing this:

// How many childs
begin
  TXMLPack.Create(TDataFile.Create('file.xml').Ref.Stream)
    .Ref
    .Node('/root')
    .Childs
    .Count
end;

Find Attribute

You can find any attribute by name doing this:

// Find by name "id"
begin
  TXMLPack.Create(TDataFile.Create('file.xml').Ref.Stream)
    .Ref
    .Node('/root')
    .Attrs
    .Item('id')
end;

Add Attribute

Adding an attribute is quite easy too:

// Add an attribute: name="foo" value="bar"
begin
  TXMLPack.Create(TDataFile.Create('file.xml').Ref.Stream)
    .Ref
    .Node('/root')
    .Attrs
    .Add('foo', 'bar')
end;

License (MIT)

This project is released under MIT license. See LICENSE.

xavier's Issues

name of type

XMLString = DOMString;
maybe in big app, app uses anotjher XML lib, and XMLString name is busy. maybe use name XavString?

Improve README file, including some examples

Let's improve README file including some examples to compare the three syntaxes.
For example:

Task	FPC	Delphi	Xavier
Open XML file	<code>	<code>	<code>
Open XML stream	<code>	<code>	<code>
Add a node	<code>	<code>	<code>
Childs Count	<code>	<code>	<code>
Find an attribute	<code>	<code>	<code>
Add an attribute	<code>	<code>	<code>

Find attributes by name

Let's create a new overloaded method to find a Item by its name.

XPath for Delphi

Let's implements XPath for Delphi (TXMLPack.Nodes method).

Add method to access the owner node of an attribute

Let's add a new method to access the owner node of an attribute.

Core classes

Let's create the basics:

• IXMLNode will represent a single node in a XML file
• IXMLNodes will be a collection of nodes
• IXMLAttribute will represent a node attribute
• IXMLAttributes will be a collection of attributes
• IXMLPack will represents the whole XML as a stream and may have some method to search using XPATH

Change the Value of Node

The IXMLNode interface has Value: XMLString, but it is missing a Value(const AValue: XMLString) to change the value.

Add method to create new attributes

Let's create IXavierAttributes.Add method. I will handle it.

XPath method should be renamed?

The IXMLPack interface has a method XPath that returns a IXMLNode (a single node).
I don't know if this is the better approach.
If XPath doesn't return a valid instance, means that we'll get nil, ie, access violation error.

A safe option is returns a IXMLNodes list. But this makes the design a little bit ugly when we want to work with only a node.

See this example below.
Let's suppose that we want to know the node value:

   TXMLPack.New(TFile.New('file.xml').Stream).XPath(
      '/CONFIG/Package/Name'
    )
    .Item(0)  // << We'll need this, if we return a list 
    .Value

However, this design/syntax already exists.

In the example below, if we want to know the value of the first attribute of the first node found, we need to code like that:

   TXMLPack.New(TFile.New('file.xml').Stream).XPath(
      '/CONFIG/Package/Name'
    )
    .Item(0)  // << new, as explaned above
    .Attrs
    .Item(0)
    .Value

Another option is having two methods which returns a single node or a node list:

function XPath(const AExpr: XMLString): IXMLNode;
function XPaths(const AExpr: XMLString): IXMLNodes;

Or could be:

function Node(const AExpr: XMLString): IXMLNode;
function Nodes(const AExpr: XMLString): IXMLNodes;

For the method that returns a single node, the library must raise an exception if couldn't find anything.
For the method that returns a list, it will be just a empty list, but without any problems with nil.

Add a package

Introduce XavierPack package.
It will use mormot_base as an dependency instead of PATHs.

API Unit

Create an API Unit.

Rename all classes to use Xavier as prefix

I don't like short prefixes — as proposed in #11 — using just 2 or 3 letters. This does not prevent (all) the collision of names problems because others libraries could use the same short prefix that you chose.

But Lib mean "specialist in something". Then, instead of a class named TXMLNode, I suggest TXavierNode and so on. That is the same to say "the Xavier implementation to a XML Node" — the "XML" is omitted because this is the problem or the context that Xavier is specialist.

Refactoring to use James.API

Refactor all units to use James.API instead of use James's units directly.

Change design of IXMLNodes

I added a new Add method in IXMLNodes to add more items in the list.
Unfortunately, that design was not good because we cannot add items and subitems sequentially like this:

  TXMLPack.New(TFile.New('data.xml').Stream)
    .Node('/root/items')
      .Add('level-1')
      .Add('level-2')
      .Add('level-3')

The output will be:

<root>
  <items>
    <level-1>
      <level-2>
        <level-3 />
      </level-2>
    </level-1>
  </items>
</root>

We cannot add because Add method should be in IXMLNode instead IXMLNodes.
I will handle it.

Add new nodes

Let's implement a new Add method to include new nodes in a list updating the XML stream.

Delphi packages

Let's build packages (lib and test) for Delphi.
We need to code the same implementation using xavier.core.fpc.pas unit. The unit for Delphi should be named xavier.core.delphi.pas.

TXMLAttributes tests

Let's create some tests for TXMLAttributes class.

TXMLNodes tests

Let's create some tests for TXMLNodes class.

Move to James

Moving to James:

• Copy README and create a new page into James based on it.

Find nodes by name

Let's create a new overloaded method to find a node by name.