NAME

Data::Sofu::Map - A Sofu Map

DESCRIPTION

Provides a interface similar to the original SofuD (sofu.sf.net)

Synopsis

        require Data::Sofu::Map;
        my $map = Data::Sofu::Map->new();
        $map->setAttribute("foo","bar");
        print $map->value("foo")->toString();
        $tree = Data::Sofu::loadfile("1.sofu");
        $tree->opApply(sub {print $_[0],"\n"}); #Prints all keys

SYNTAX

This Module is pure OO, exports nothing

METHODS

Also look at Data::Sofu::Object for methods, cause Map inherits from it

new([DATA]) Creates a new Data::Sofu::Map and returns it

Converts DATA to appropriate Objects if DATA is given. DATA has to be a Hash or a hashlike structure.

        $env = Data::Sofu::Map->new(%ENV);

set(DATA)

Sets the contents of the Map to match a Hash.

        $map->set(%ENV);

object(KEY)

Return an attribute identified by KEY of this Map.

        $o = $env->object("PATH");
        if ($o->isList()) {
                ...
        }
        elsif ($o->isValue()) {
        ...

Note: Changing the returned Object will change the Map as well. (OO 101)

remAttribute(KEY)

Deletes an Attribute from this Map.

        $env->remAttribute("OSTYPE");

setAttribute(KEY, OBJECT)

Replaces/creates an Attribute in this Map identified by KEY and sets it to OBJECT.

        $env->setAttribute("PATH", Data::Sofu::List->new(split/:/,$env->value("PATH")->toString()));

hasAttribute(KEY)

Return a true value if this Map has an Attribute identified by KEY

        if ($env->hasAttribute("Lines")) {
                print "X" x $env->value("Lines")->toInt();

hasValue(KEY)

Returns 1 if this Map has an Attribute called KEY and this Attribute is a Data::Sofu::Value.

        $env->hasValue("PATH") === $env->hasAttribute("PATH") and $env->object("PATH")->isValue();

Note: Return 0 if the Object is not a Value and under if the Element doesn't exist at all.

hasMap(KEY)

Returns 1 if this Map has an Attribute called KEY and this Attribute is a Data::Sofu::Map.

        $env->hasMap("PATH") === $env->hasAttribute("PATH") and $env->object("PATH")->isMap();

Note: Return 0 if the Object is not a Value and under if the Element doesn't exist at all.

hasList(KEY)

Returns 1 if this Map has an Attribute called KEY and this Attribute is a Data::Sofu::List.

        $env->hasList("PATH") === $env->hasAttribute("PATH") and $env->object("PATH")->isList();

Note: Return 0 if the Object is not a Value and under if the Element doesn't exist at all.

list(KEY)

Returns the Object at the key called KEY as a Data::Sofu::List.

Dies if the Object is not a Data::Sofu::List.

        $env->list("PATH") === $env->object("PATH")->asList()

map(KEY)

Returns the Object at the key called KEY as a Data::Sofu::Map.

Dies if the Object is not a Data::Sofu::Map.

        $env->map("PATH") === $env->object("PATH")->asMap()

value(KEY)

Returns the Object at the key called KEY as a Data::Sofu::Value.

Dies if the Object is not a Data::Sofu::Value.

        $env->value("PATH") === $env->object("PATH")->asValue()

asMap()

Returns itself, used to make sure this Map is really a Map (Data::Sofu::List and Data::Sofu::Value will die if called with this method)

asHash()

Perl only

Returns this Map as a real perl Hash.

isMap()

Returns 1

next()

Returns the next Key, Value pair in no specific order. Used to iterate over the Map.

If called in list context it returns the (Key, Value) as a list, in scalar context it returns [Key, Value] as an Arrayref and in Void Context it resets the Iterator.

        while (my ($k,$v) = $env->next()) {
                last if $k eq "PATH";
                print "$k = ".$v->asValue()->ToString()."\n";
        }
        $env->next() #Reset Iterator

each()

Returns the next Key, Value pair in no specific order. Used to iterate over the Map.

If called in list context it returns the (Key, Value) as a list, in scalar context it returns [Key, Value] as an Arrayref and in Void Context it resets the Iterator.

        while (my ($k,$v) = $env->each()) {
                last if $k eq "PATH";
                print "$k = ".$v->asValue()->ToString()."\n";
        }
        $env->each() #Reset Iterator

length()

Returns the length of this Map

Warning: Resets the Iterator.

opApply(CODE)

Takes a Subroutine and iterates with it over the Map. Values and Keys can't be modified.

The Subroutine takes two Arguments: first is the Key and second is the Value.

        $env->opApply(sub {
                print "Key = $_[0], Value = ",$_[1]->asValue->toString(),"\n";
        });

Note: The Values are Objects, so they still can be changed, but not replaced.

opApplyDeluxe(CODE)

Perl only.

Takes a Subroutine and iterates with it over the Map. Keys can't be modified, but Values can.

The Subroutine takes two Arguments: first is the Key and second is the Value.

        my $i=0;
        $env->opApplyDeluxe(sub {
                $_[1]=new Data::Sofu::Value($i++);
        });

Note: Please make sure every replaced Value is a Data::Sofu::Object or inherits from it.

storeComment(TREE,COMMENT)

Stores a comment in the Object if TREE is empty, otherwise it propagades the Comment to all its Values

Should not be called directly, use importComments() instead.

orderedKeys()

Return all Keys of the Map in insertion Order

stringify(LEVEL, TREE)

Returns a string representing this Map and all its children.

Runs string(LEVEL+1,TREE+keyname) on all its values.

binaryPack(ENCODING, BYTEORDER, SOFUMARK)

Returns a String containing the binary representaion of this Map (according the Sofu Binary File Format)

Look at Data::Sofu::Binary for the Parameters.

Note: This uses Data::Sofu::Binary::Bin0200 as a only packer.

binarify(TREE,BINARY DRIVER)

Returns the binary version of this Map and all its children using the BINARY DRIVER. Don't call this one, use binaryPack instead

BUGS

This only supports the 2 Argument version of opApply, I have no idea how to find out if a codereference takes 2 or 1 Arguments.

SEE ALSO

Data::Sofu, Data::Sofu::Binary, Data::Sofu::Object, Data::Sofu::List, Data::Sofu::Value, Data::Sofu::Undefined, http://sofu.sf.net

cpanm Data::Sofu

perl -MCPAN -e shell
install Data::Sofu