Metadata-Version: 2.4
Name: jasminum
Version: 0.3.0
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Rust
Requires-Dist: polars >=1.17.0
Requires-Dist: pyarrow >=18.0.0
Requires-Dist: termcolor >=2.5.0
Requires-Dist: numpy >=2.2.0
License-File: LICENSE
Summary: an implementation of the data analytics programming language jasmine
Keywords: jasmine,jasminum,polars,dataframe,arrow
Author: the Jasmine authors
Requires-Python: >=3.11
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Repository, https://github.com/hinmeru/jasmine

# jasminum

an implementation of the data analytics programming language jasmine powered by [Polars](https://pola.rs/)

## Installation

```
pip install jasminum
```

## Start a jasminum Process

jasminum

## Data Type

### Scalar

| name      | examples                             |
| --------- | ------------------------------------ |
| Null      | 0n, null                             |
| BOOLEAN   | 1b, 0b, true, false                  |
| INT       | 42                                   |
| DATE      | YYYY-MM-DD                           |
| TIME      | HH:mm:ss.sss                         |
| DATETIME  | YYYY-MM-DD[T]HH:mm:ss.sss            |
| TIMESTAMP | YYYY-MM-DD[D]HH:mm:ss.sssssssss      |
| DURATION  | 00000[D]HH:mm:ss.sss,1ns,1s,1m,1h,1D |
| FLOAT     | 4.2, inf, -inf                       |
| STRING    | "string"                             |
| CAT       | `cat, 'cat'                          |

`datetime` and `timestamp` are with timezone information. To convert a timezone

- `` t ~tz `Asia/Hong_Kong ``
- `` tz(t, `Asia/Hong_Kong) ``

### List(Mixed Data Types)

```
l[1, null, `cat]
```

### Series

| name      | data type      |
| --------- | -------------- |
| bool      | Boolean        |
| f32       | Float32        |
| f64       | Float64        |
| i8        | Int8           |
| i16       | Int16          |
| i32       | Int32          |
| i64       | Int64          |
| u8        | UInt8          |
| u16       | UInt16         |
| u32       | UInt32         |
| u64       | UInt64         |
| date      | Date           |
| datetime  | Datetime("ms") |
| timestamp | Datetime("ns") |
| duration  | Duration       |
| time      | Time           |
| string    | String         |
| cat       | Categorical    |
| list      | List           |
| unknown   | Unknown        |

```
// empty series
`i8$[]

// non-empty series
// i64
1 0n -1

// i8
[0i8, 1, 2]

// u8
0n 1u8 3

// bool
1b 0b 1b 0n
[true, null, false]

// cats
`a`b`c
['c','d',null]
```

### Dataframe

a collection of series

```
// empty series
df[series1= `i32$[], series2= `f32$[]]


// non-empty series
df[series1 = `i32$[ , , ], series2 = `f32$[null, 2.0, 3.0]]
df[series1 = [0i32, , ], series2 = [null, 2.0, 3.0]]
```

### Matrix (nyi)

a 2d float array

```
// empty matrix
x[[], [], []]

// non-empty matrix
x[[1, 2], [2, 3], [4, null]]
```

### Dictionary

```
// empty map
{}

// non-empty map
{a:1, b:2, c:3}
dict(`a`b`c, 1 2 3)
```

### Variable Name

- Starts with alphabets, the var name can include alphabets, number and "\_"
- Starts with CJK character, the var name can include CJK character, alphabets, number and "\_"

### Control Flow

```
if(condition) {
  statement1;
  statement2;
}

while(condition) {
  statement1;
  statement2;
}
```

### Error Handling

```
try {
  statement1;
  statement2;
} catch (err) {
  statement1;
  statement2;
}

```

### Function

```
fn(param1, param2, ...){
  statement1;
  statement2;
  return statement3;
  raise "err";
}
```

### Function Call

```
fn(arg1, arg2, ...)
```

### Functional Call with Parted Args

fn2 is a function requires 2 arguments

```
fn2(arg1)
fn2(, arg2)
```

## Expression

### SQL

```
[select | update | delete] series1, series2, ...
  [
    by series1, series2, ...
    | dyn unit, series1, series2, ...
    | rolling unit, series1, series2, ...
  ]
  from table
  [ where condition1, condition2, ...]
  [ sort {series1, -series2, ...} ]
  [ take number ]

// functional query
// select
sel(dataframe, exprs, exprs, exprs)
// update
upd(dataframe, exprs, exprs, exprs)
// delete, no group by parameter
del(dataframe, exprs, exprs)
```

### Assignment

```
var1 = exp1
```

### Unary Operation

```
var1 var2
var1(var2)
```

### Binary Operation

```
var1 ~fn0 var2
fn0(var1, var2)
```

### Iteration

#### Each

```
var1 ~each series1
var1 ~each list1
var1 ~each dataframe1

// apply each for 1st param
f2(var1) ~each var2
// apply each for 2nd param
f2(,var2) ~each var1
```

