Data::Sofu::Map - A Sofu Map

- DESCRIPTION
- Synopsis
- SYNTAX
- METHODS

- new([DATA])
- set(DATA)
- object(KEY)
- remAttribute(KEY)
- setAttribute(KEY, OBJECT)
- hasAttribute(KEY)
- hasValue(KEY)
- hasMap(KEY)
- hasList(KEY)
- list(KEY)
- map(KEY)
- value(KEY)
- `asMap()`
- `asHash()`
- `isMap()`
- `next()`
- `each()`
- `length()`
- opApply(CODE)
- opApplyDeluxe(CODE)
- `storeComment(TREE,COMMENT)`
- `orderedKeys()`
- `stringify(LEVEL, TREE)`
- `binaryPack(ENCODING, BYTEORDER, SOFUMARK)`
- `binarify(TREE,BINARY DRIVER)`

- BUGS
- SEE ALSO

# 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

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