Jac Coding Manual

Jac is all of python's goodness wrapped in a language that gives the coder wings. Lets jump right in!

Get Jac

Install Jac.

pip install jaclang

Important Note :

If you have a previous jaclang installation please bash jac clean in order to remove all cached files, before uninstallation.

If you have already uninstalled the previous jaclang version, bash source scripts/clean_jac_gen.sh from source, before installation.

Validate Jac works.

echo "with entry { print('hello world'); }" > test.jac;
jac run test.jac;
rm test.jac;"

If that command prints hello world, Jac is working.

Ok now lets jump into learning Jac!

A Complete Example

We start this journey top down. Lets look at a simple but complete program in Python and two Jac versions. The first implements the module with very close resemblence to Python, and the second is the clean Jactastic way of implemmenting the same functionality. Lets look at the complete examples, then break it down.

Python (circle.py)Jac (circle.jac)circle_clean.jaccircle_clean_impl.jac

"""
This module demonstrates a simple circle class and a function to calculate the area of a circle.
(Module docstrings are optional but good practice in python)
"""

from abc import ABC, abstractmethod
from enum import Enum
import math
import unittest

# Module-level global var
RAD = 5


def calculate_area(radius: float) -> float:
    """Function to calculate the area of a circle."""
    return math.pi * radius * radius


# Multiline comments in python feels like a hack
"""
Above we have the demonstration of a function to calculate the area of a circle.
Below we have the demonstration of a class to calculate the area of a circle.
"""


class ShapeType(Enum):
    """Enum for shape types"""

    CIRCLE = "Circle"
    UNKNOWN = "Unknown"


class Shape(ABC):
    """Base class for a shape."""

    def __init__(self, shape_type: ShapeType):
        self.shape_type = shape_type

    @abstractmethod
    def area(self) -> float:
        """Abstract method to calculate the area of a shape."""
        pass


class Circle(Shape):
    """Circle class inherits from Shape."""

    def __init__(self, radius: float):
        super().__init__(ShapeType.CIRCLE)
        self.radius = radius

    def area(self) -> float:
        """Overridden method to calculate the area of the circle."""
        return math.pi * self.radius * self.radius


c = Circle(RAD)

if __name__ == "__main__":
    # To run the program functionality
    print(f"Area of a circle with radius {RAD} using function: {calculate_area(RAD)}")
    print(f"Area of a {c.shape_type.value} with radius {RAD} using class: {c.area()}")

    # Uncomment the next line if you want to run the unit tests
    # run_tests()


# Unit Tests!
class TestShapesFunctions(unittest.TestCase):
    def test_calculate_area(self) -> None:
        expected_area = 78.53981633974483
        self.assertAlmostEqual(calculate_area(RAD), expected_area)

    def test_circle_area(self) -> None:
        c = Circle(RAD)
        expected_area = 78.53981633974483
        self.assertAlmostEqual(c.area(), expected_area)

    def test_circle_type(self) -> None:
        c = Circle(RAD)
        self.assertEqual(c.shape_type, ShapeType.CIRCLE)

"""
This module demonstrates a simple circle class and a function to calculate
the area of a circle in all of Jac's glory.
"""

import:py math;
# Module-level global var

glob RAD = 5;

"""Function to calculate the area of a circle."""
can calculate_area(radius: float) -> float {
    return math.pi * radius * radius;
}
#* (This is multiline comments in Jac)
Above we have the demonstration of a function to calculate the area of a circle.
Below we have the demonstration of a class to calculate the area of a circle.
*#

"""Enum for shape types"""
enum ShapeType {
    CIRCLE = "Circle",
    UNKNOWN = "Unknown"
}

"""Base class for a shape."""
obj Shape {
    has shape_type: ShapeType;

    """Abstract method to calculate the area of a shape."""
    can area -> float abs;
}

"""Circle class inherits from Shape."""
obj Circle :Shape: {
    can init(radius: float) {
        super.init(ShapeType.CIRCLE);
        self.radius = radius;
    }

    """Overridden method to calculate the area of the circle."""
    override can area -> float {
        return math.pi * self.radius * self.radius;
    }
}

with entry {
    c = Circle(RAD);
}
# Global also works here

with entry:__main__ {
    # To run the program functionality
    print(
        f"Area of a circle with radius {RAD} using function: {calculate_area(RAD)}"
    );
    print(
        f"Area of a {c.shape_type.value} with radius {RAD} using class: {c.area()}"
    );
}
# Unit Tests!

glob expected_area = 78.53981633974483;

test calc_area {
    check almostEqual(calculate_area(RAD), expected_area);
}

test circle_area {
    c = Circle(RAD);
    check almostEqual(c.area(), expected_area);
}

test circle_type {
    c = Circle(RAD);
    check c.shape_type == ShapeType.CIRCLE;
}

"""
This module demonstrates a simple circle class and a function to calculate
the area of a circle in all of Jac's glory.
"""

include:jac circle_clean_impl;

enum ShapeType;

can calculate_area(radius: float) -> float;
can main_run;

"""Base class for a shape."""
obj Shape {
    has shape_type: ShapeType;

    can area -> float abs;
}

"""Circle class inherits from Shape."""
obj Circle :Shape: {
    has radius: float;

    can init(radius: float);
    override can area -> float;
}
# Radius of the demo circle

glob RAD = 5, c = Circle(radius=RAD);

"""Here we run the main program."""
with entry:__main__ {
    main_run();
}

"""Enum for shape types"""

import:py math;

:enum:ShapeType {
    CIRCLE="Circle",
    UNKNOWN="Unknown"
}

"""Function to calculate the area of a circle."""
:can:calculate_area
(radius: float) -> float {
    return math.pi * radius * radius;
}

:obj:Circle:can:init
(radius: float) {
    self.radius = radius;
    super.init(ShapeType.CIRCLE);
}

"""Overridden method to calculate the area of the circle."""
:obj:Circle:can:area -> float {
    return math.pi * self.radius * self.radius;
}

:can:main_run {
    print(f"Area of a circle with radius {RAD} using function: {calculate_area(RAD)}");
    print(f"Area of a {c.shape_type.value} with radius {RAD} using class: {c.area()}");
}

Now lets break it down!

Docstrings, Imports, and Globals

circle.jaccircle.py

"""
This module demonstrates a simple circle class and a function to calculate
the area of a circle in all of Jac's glory.
"""

import:py math;
# Module-level global var

"""
This module demonstrates a simple circle class and a function to calculate the area of a circle.
(Module docstrings are optional but good practice in python)
"""

from abc import ABC, abstractmethod
from enum import Enum
import math
import unittest

# Module-level global var

In this segment we observe a docstring, imports, and a global variable. In Jac docstrings look exactly like python docstrings, however docstrings can only be used as docstrings (not as comments). That means there are a limited number of places you can place them, these places are at the top of a module, and before the declaration of functions, methods, classes (architypes), global variable statements, module level code blocks (i.e., with entry {} style blocks, more on this later), and enumerations.

Import statements are very similar to python, note that you have to denote if you are importing a python module with import:py or jac with import:jac. Module paths and such are pretty much identical.

Quick note on from import, they work like this.

JacPython

import:py from os, getcwd, listdir, path

from os import getcwd, listdir, path

The rationale for this change is purely aesthetic as when reading a file with many imports it looks good to have all the import keywords at the beginning.

Abilities (Functions)

circle.jaccircle.py

"""Function to calculate the area of a circle."""
can calculate_area(radius: float) -> float {
    return math.pi * radius * radius;

def calculate_area(radius: float) -> float:
    """Function to calculate the area of a circle."""

A nomenclature introduced with Jac is to refer to functions (and the soon described data spatial code blocks) as abilities. More on data spatial programming later, but for this example the functions in python and jac are very similar except the def keyword is replaced with can. Also type-hints are manditory in Jac for function signatures (parameters and returns). Any function that doesn't include it's return signature (i.e., -> TYPE) is implicitly assumed to be -> None.

Also note that the docstring appears before the function call. This choice was made for readability (function signatures closer to the code is better for code readability when a large docstring is used).

Multiline Comments

circle.jaccircle.py

#* (This is multiline comments in Jac)
Above we have the demonstration of a function to calculate the area of a circle.
Below we have the demonstration of a class to calculate the area of a circle.
*#

# Multiline comments in python feels like a hack
"""
Above we have the demonstration of a function to calculate the area of a circle.
Below we have the demonstration of a class to calculate the area of a circle.

As Jac does not allow docstrings to be used as comments, Jac provides an elegant way to specify multiline comments. Any text between #* and *# is treated as a multi line comment (and is delightfully pythontic).

Enumeration

circle.jaccircle.py

"""Enum for shape types"""
enum ShapeType {
    CIRCLE = "Circle",
    UNKNOWN = "Unknown"
}

class ShapeType(Enum):
    """Enum for shape types"""

    CIRCLE = "Circle"

Jac includes enums as a language feature, the semantics of this enum is simple currently however will evolve over time. Of course you can import Enum to leverage pythons path if needed. However its important to note you'll have to use Jac's keyword escape feature to avoid a syntax error when referring to the enum package.

import:py from enum, Enum, auto;

If you try to import from enum this way in jac, you'll get a syntax error.

import:py from <>enum, Enum, auto;

This is the way to import from enum. Any language level keyword can be escaped by putting a <> immediately before the keyword.

Shape Class

circle.jaccircle.py

"""Base class for a shape."""
obj Shape {
    has shape_type: ShapeType;

    """Abstract method to calculate the area of a shape."""
    can area -> float abs;
}

class Shape(ABC):
    """Base class for a shape."""

    def __init__(self, shape_type: ShapeType):
        self.shape_type = shape_type

    @abstractmethod
    def area(self) -> float:
        """Abstract method to calculate the area of a shape."""

This is an example of a Shape class in Jac. A couple things to note here.

Circle Class

circle.jaccircle.py

"""Circle class inherits from Shape."""
obj Circle :Shape: {
    can init(radius: float) {
        super.init(ShapeType.CIRCLE);
        self.radius = radius;
    }

    """Overridden method to calculate the area of the circle."""
    override can area -> float {
        return math.pi * self.radius * self.radius;
    }
}

class Circle(Shape):
    """Circle class inherits from Shape."""

    def __init__(self, radius: float):
        super().__init__(ShapeType.CIRCLE)
        self.radius = radius

    def area(self) -> float:
        """Overridden method to calculate the area of the circle."""

Script handling

circle.jaccircle.py

with entry {
    c = Circle(RAD);
}
# Global also works here

with entry:__main__ {
    # To run the program functionality

c = Circle(RAD)

if __name__ == "__main__":
    # To run the program functionality
    print(f"Area of a circle with radius {RAD} using function: {calculate_area(RAD)}")
    print(f"Area of a {c.shape_type.value} with radius {RAD} using class: {c.area()}")

    # Uncomment the next line if you want to run the unit tests

Tests

circle.jaccircle.py

        f"Area of a circle with radius {RAD} using function: {calculate_area(RAD)}"
    );
    print(
        f"Area of a {c.shape_type.value} with radius {RAD} using class: {c.area()}"
    );

# Unit Tests!
class TestShapesFunctions(unittest.TestCase):
    def test_calculate_area(self) -> None:
        expected_area = 78.53981633974483
        self.assertAlmostEqual(calculate_area(RAD), expected_area)

    def test_circle_area(self) -> None:
        c = Circle(RAD)
        expected_area = 78.53981633974483
        self.assertAlmostEqual(c.area(), expected_area)

    def test_circle_type(self) -> None:
        c = Circle(RAD)

Clean Approach

circle_clean.jaccircle_clean_impl.jaccircle_clean_tests.jac

"""
This module demonstrates a simple circle class and a function to calculate
the area of a circle in all of Jac's glory.
"""

include:jac circle_clean_impl;

enum ShapeType;

can calculate_area(radius: float) -> float;
can main_run;

"""Base class for a shape."""
obj Shape {
    has shape_type: ShapeType;

    can area -> float abs;
}

"""Circle class inherits from Shape."""
obj Circle :Shape: {
    has radius: float;

    can init(radius: float);
    override can area -> float;
}
# Radius of the demo circle

glob RAD = 5, c = Circle(radius=RAD);

"""Here we run the main program."""
with entry:__main__ {
    main_run();
}

"""Enum for shape types"""

import:py math;

:enum:ShapeType {
    CIRCLE="Circle",
    UNKNOWN="Unknown"
}

"""Function to calculate the area of a circle."""
:can:calculate_area
(radius: float) -> float {
    return math.pi * radius * radius;
}

:obj:Circle:can:init
(radius: float) {
    self.radius = radius;
    super.init(ShapeType.CIRCLE);
}

"""Overridden method to calculate the area of the circle."""
:obj:Circle:can:area -> float {
    return math.pi * self.radius * self.radius;
}

:can:main_run {
    print(f"Area of a circle with radius {RAD} using function: {calculate_area(RAD)}");
    print(f"Area of a {c.shape_type.value} with radius {RAD} using class: {c.area()}");
}

include:jac circle_clean;

glob expected_area = 78.53981633974483;

test {
    check almostEqual(calculate_area(RAD), expected_area);
}

test {
    c = Circle(RAD);
    check almostEqual(c.area(), expected_area);
}

test {
    c = Circle(RAD);
    check c.shape_type == ShapeType.CIRCLE;
}

Complete list of Differences and Features beyond Python

Jac is a superset of Python 3, all of pythons features and full native compatability is present. However, each of the features and adjustments described here represents Jac's approach to improve programmer effectiveness in a way that is distinct from Python. These choices were made focusing on type safety, readability, expressiveness, and general code ninja goodness. As the Jac language evolves, these features will be refined and expanded based on user feedback, practical usage, and the evolution of python and coding in general.

Additionally, Jac is the first language to implement the data spatial object paradigm. After getting used to Jac, we encourage every coder to expand their toolkit with this powerful programming model.

Whitespace doesn't matter

"""Same functionality 3 white space styles."""

with entry {  # very pythonic
    a = "hello";
    b = len(a);
    print(b); }

with entry {  # a bit more Jac like
    a = "hello" |> len;
    a |> print;
}

with entry { "hello" |> len |> print; }  # more concise
with entry { print(len("hello")); }  # same, but no pipe

Unlike Python, where indentation is crucial for defining code blocks, Jac does not consider whitespace for this purpose. This gives programmers more flexibility in formatting their code, although maintaining a consistent style is still recommended for readability. With more flexibility in how code can be laid out, more beautiful formatting styles are possible.

Types hints are required

"""Type hints aren't that much work."""

can foo(a: int, b: str) -> int { # type hint needed here

c = a + (b |> int);# no type hint needed here
return c;
}

obj Bar {
    has a_list: list[int] = [1, 2, 3]; # type hint needed here
    has b_list: list[str] = ["5", "6", "7"];

    can init() -> None {

        for i in here.b_list {
            foo(5, i) |> print;
        }
    }
}

In Jac, type hints are mandatory for certain variable declarations and function signatures. This enforces type safety and makes the code more self-documenting, aiding in debugging and maintaining the codebase.

Typing library implicitly available

Jac has a built-in typing system, similar to Python's typing library, but it's implicitly available. This means you don't need to import typing modules explicitly to use features like List, Dict, Optional, etc. You can simply reference them with a backtick as `List, `Dict, and `Optional.

Can separate definitions from declarations

AbilityClass MethodAnotherTraditional

# Declaration
can my_print(messag: str) -> str;

# Definition
:can:my_print
(message: str) -> str {
    output = f"from me: {message}";
    print("from me: {message}");
    return output;
}

# Declaration
obj MyPrinter {
    can my_print(messag: str) -> str; # method declaration
}

# Definition
:obj:MyPrinter:can:my_print
(message: str) -> str {
    output = f"from me: {message}";
    print("from me: {message}");
    return output;
}

"""Modified for separate defs/decls."""

obj MyObj {
    has : protect a: int;

    can : priv init(a: int) -> None;
    can : pub set_a(val: int) -> None;
}

:o:MyObj:c:init {
    here.a = a;
}

:o:MyObj:c:set_a {
    here.a = val;
}

# Decl/Def Combined
can your_print(messag: str) -> str {
    output = f"from me: {message}";
    print("from me: {message}");
    return output;
}

# Decl/Def Combined
obj YourPrinter {
    can your_print(messag: str) -> str {
        output = f"from me: {message}";
        print("from me: {message}");
        return output;
    }
}

In Jac, separating the declaration of functions or variables from their definitions contributes to a cleaner code structure, where the high-level structure and relationships between different parts of the code are immediately apparent. This approach simplifies navigation through code, especially in large projects, as it enables developers to quickly understand the code architecture without getting bogged down in implementation details from the outset.

Can have definitions and implementations span multiple files

decl_defs_main.jacdecl_defs_impl.jac

"""Example for separation between declaration and definition.

A data-spatial object is shown in this example, however it applies
to all types of object classes.
"""
include:jac decl_defs_impl;

walker travelor {
    can say_hello with entry;  # data spatial ability declared
    can say_whatever(msg: str) -> None;  # traditional method declared

    # inline ability definition (python only supports this)
    can say_goodbye {
        "Goodbye" |> print;
    }
}

"""Definitions of the walker and abilities."""

:walker:travelor:can:say_hello {
    "Hello" |> print;  # |> is a pipe forward operator
}

# :w: and :c: are aliases for :walker: and :abilitiy:
:w:travelor:c:say_whatever(msg: str) -> None {
    msg |> print;
}

Jac supports separating definitions from implementations across multiple files. This feature enhances modularity and maintainability, as it allows developers to organize their codebase more effectively. Definitions can be placed in one file (e.g., for interfaces or abstract declarations), while their corresponding implementations can reside in separate files. This separation not only makes the codebase easier to manage, especially for large-scale projects, but also facilitates team collaboration. Different team members can work on different aspects of the implementation concurrently without conflicts, as the interface remains consistent and shared across the team. Moreover, this structure aids in clear version control and change tracking, making the development process more efficient and less error-prone.

Proper access control

"""No more `_` and `__` for access/visibility directives."""

obj MyObj {
    has : protect a: int;

    can : priv init(a: int) -> None {
        here.a = a;
    }

    can : pub set_a(val: int) -> None {
        here.a = val;
    }
}

In Jac, access control is more granular and explicit compared to Python. Jac introduces access modifiers similar to those found in languages like Java or C#, allowing for public, private, and protected access levels. This feature enhances encapsulation and allows developers to define the scope of class members more clearly. By controlling access to the internals of a class, programmers can prevent unintended interactions with the class's methods and attributes, leading to more robust and maintainable code.

Proper abstract classes/methods

"""Example of multiple inheritance."""

obj Parent {
    can init {
    # Parent initialization
    }
    can speak() -> None abs;# Abstract method
}

obj Mom :Parent: {
    can init {
    # Mom initialization
    Parent.init();
    }

    can speak() -> None {
        print("I'm good at swimming!");
    }
}

obj Dad :Parent: {
    can init {
    # Dad initialization
    Parent.init();
    }

    can speak() -> None {
        print("I'm good at running!");
    }
}

obj Child :Mom, Dad: { #Child inherits from Mom and Dad

can speak() -> None {
# Child initialization
Mom.speak();
Dad.speak();
}
}

Jac provides built-in support for abstract classes and methods, a feature that is handled through the abc module in Python. In Jac, an abstract class can be defined more intuitively, and any methods that are meant to be abstract can be declared as such directly. This enforces a contract for the derived classes to implement the abstract methods, ensuring consistency and predictability in class hierarchies. The introduction of proper abstract classes and methods in Jac makes it easier to design and work with complex object-oriented systems, as it provides a clear framework for how classes should be structured and interacted with.

Tuples are explicit

Tuples in Jac must be explicitly declared, which differs from Python's implicit tuple creation. This design choice avoids accidental creation of tuples, enhancing code clarity.

Docstrings in the right place

Docstrings in Jac are placed differently compared to Python. This change is aimed at improving readability and making the documentation process more intuitive and consistent.

Elvis Operator

Jac introduces the Elvis operator (?:), which is a shorthand for an if-else statement, similar to the ternary operator in other languages. It provides a more concise way to write conditional expressions.

Null Safe Operator

The Null Safe operator in Jac allows safe access to an object's properties or methods without the risk of encountering a null reference error. This operator helps in writing cleaner, more robust code.

Filter Comprehension

Filter comprehension in Jac is a built-in feature that provides a more intuitive and concise way to filter collections, similar to list comprehensions in Python but with a focus on filtering.

Assign Comprehension

Assign comprehension is a unique feature in Jac that allows for direct assignment within a comprehension, making certain patterns of data processing more succinct and readable.

Dataclass style basis for OOP

Jac's approach to object-oriented programming is based on a dataclass style, where classes are primarily used to store data. This makes data handling more straightforward and efficient.

Abstract Classes, Methods and overrides built in

Application Bundling

Proper multiline Comments

Multiline comments in Jac are more versatile and user-friendly compared to Python. This feature enhances the ability to document code extensively without resorting to string literals or consecutive single-line comments.

Explicit notation for special variables

Special variables in Jac have explicit notations, making it clear when such variables are being used. This feature aids in code readability and helps avoid accidental misuse of these variables.

No need for gratuitous self usage

In Jac, there is no need to use the self keyword in all class method signatures as in Python. This design choice simplifies method definitions and makes the code cleaner and easier to read.

Optional Left to right Pipe style expressivity

Jac offers an optional left-to-right pipe-style syntax for function calls, similar to the Unix pipeline or functional programming languages. This feature allows for more expressive and readable code, especially when chaining multiple function calls.

Full Support of Data Spatial Programming Paradigmn

More on this soon!!!