# Mathematica::Serializer

Raku package for converting Raku objects and expressions into Mathematica expressions, and for converting Mathematica expressions back into Raku objects.

**Remark:** Mathematica is also known as Wolfram Language (WL). Mathematica and WL are used as synonyms below.

---

## Installation 

From Zef ecosystem:

```
zef install Mathematica::Serialization
```

From GitHub:

```
zef install https://github.com/antononcube/Raku-Mathematica-Serialization.git
```

---

## Plain text serialization

Here we convert an array of pairs into a WL expression.
```perl6
use Mathematica::Serializer;
encode-to-wl([ "a" => 23, "karma" => 'interest', "instance" => 1/3, "ary" => Whatever, "condo" => Nil]):!encoded-head;
```
```
# List[Rule["a",23],Rule["karma","interest"],Rule["instance",Rational[1,3]],Rule["ary",Automatic],Rule["condo",NULL]]
```

Here is a list of date-time objects:

```perl6
my @dts = (DateTime.new(2022,1,1,2,9,0), DateTime.new(2022,1,1,11,35,0), DateTime.new(2022,1,1,11,36,0)).Seq;
```
```
# [2022-01-01T02:09:00Z 2022-01-01T11:35:00Z 2022-01-01T11:36:00Z]
```

Here we convert that list into a Mathematica expression:

```perl6
@dts ==> encode-to-wl
```
```
# WLEncoded[List[DateObject[{2022,1,1,2,9,0}],DateObject[{2022,1,1,11,35,0}],DateObject[{2022,1,1,11,36,0}]]]
```

----

## [Wolfram Exchange Format (WXF)](https://reference.wolfram.com/language/ref/format/WXF.html)

### Serialization to WXF

WXF binary serialization is available through `encode-to-wxf` or the
`Mathematica::Serializer::WXF` class (or the synonym symbol `WXF`):

```raku
my @ds = %(name => 'Ada'), %(name => 'Grace');
my Blob $wxf = encode-to-wxf(@ds);
my Str $wxf-string = encode-to-wxf(@ds):string;
my Blob $same = WXF.new.serialize(@ds);
```
```
# Buf:0x<38 3A 66 02 73 04 4C 69 73 74 41 01 2D 53 04 6E 61 6D 65 53 03 41 64 61 41 01 2D 53 04 6E 61 6D 65 53 05 47 72 61 63 65>
```

Hashes become WXF associations and arrays become WL lists. Consequently, an
array of hashes deserializes to the list of associations accepted by
`Dataset`.

### Deserialization from WXF

Uncompressed WXF byte arrays and ISO-8859-1 strings can be converted back into
Raku values with `Mathematica::Deserializer`:

```raku
use Mathematica::Deserializer;

my $value = decode-from-wxf($wxf);
my $same = WXFDeserializer.new.deserialize($wxf-string);
```
```
# [{name => Ada} {name => Grace}]
```

Known Wolfram heads are converted to native Raku values. General Wolfram
symbols and expressions are represented by `WXFSymbol` and `WXFExpression`.
Packed and numeric arrays are returned as nested Raku arrays.

-------

## References

### Articles

[AA1] Anton Antonov,
["Connecting Mathematica and Raku"](https://rakuforprediction.wordpress.com/2021/12/30/connecting-mathematica-and-raku/),
(2021),
[RakuForPrediction at WordPress]([https://rakuforprediction.wordpress.com/).

[WRI1] Wolfram Research, Inc.,
[WXF (.wxf)](https://reference.wolfram.com/language/ref/format/WXF.html),
(2018), 
[Wolfram Documentation Center](https://reference.wolfram.com/language).

[WRI2] Wolfram Research, Inc.,
[WXF Format Description](https://reference.wolfram.com/language/tutorial/WXFFormatDescription.html),
(2018),
[Wolfram Documentation Center](https://reference.wolfram.com/language).

### Packages

[AAp1] Anton Antonov
[Text::CodeProcessing Raku package](https://github.com/antononcube/Raku-Text-CodeProcessing),
(2021-2022),
[GitHub/antononcube](https://github.com/antononcube).

[AAp2] Anton Antonov
[Mathematica-Grammar Raku package](https://github.com/antononcube/Raku-Mathematica-Grammar),
(2021-2022),
[GitHub/antononcube](https://github.com/antononcube).

[AAp3] Anton Antonov,
[RakuMode Mathematica package](https://github.com/antononcube/ConversationalAgents/blob/master/Packages/WL/RakuMode.m),
(2020-2021),
[ConversationalAgents at GitHub/antononcube](https://github.com/antononcube/ConversationalAgents).

