From dad7db9de86e531104b0783f07a983ea9f922cf0 Mon Sep 17 00:00:00 2001 From: Jayanaka-98 Date: Mon, 29 Jul 2024 16:31:49 +0530 Subject: [PATCH 1/3] Added impl documentation --- support/jac-lang.org/docs/learn/impl_docs.md | 114 +++++++++++++++++++ 1 file changed, 114 insertions(+) create mode 100644 support/jac-lang.org/docs/learn/impl_docs.md diff --git a/support/jac-lang.org/docs/learn/impl_docs.md b/support/jac-lang.org/docs/learn/impl_docs.md new file mode 100644 index 000000000..0cd39b64c --- /dev/null +++ b/support/jac-lang.org/docs/learn/impl_docs.md @@ -0,0 +1,114 @@ +# Separating code Implementation from Declaration + +Jac-lang offers a unique feature which allows the coder to separate the functional declaration of the code and their declaration. This facilitate cleaner code without importing required files manually. + +## Function Declaration and Function Body + +Usually when coding with python the body of a function or a method will be coded right after the function/method declaration (def statement) as shown in the following python code snippet. + +```python +from enum import Enum + +def foo() -> None: + return "Hello" + +class vehicle: + def __init__(self) -> None: + self.name = "Car" + +class Size(Enum): + Small = 1 + Medium = 2 + Large = 3 + +car = vehicle() +print(foo()) +print(car.name) +print(Size.Medium.value) +``` +However, Jac-lang offers novel language features which allows a programmer to organize their code effortlessly. + +## Separating function/object bodies from their declaration. + +In jaclang the declaration of functions and objects can be done independently, as shown in the below code snippet. By doing so, it creates an empty shell for the function/object/enum. + +```python +can foo(); + +obj vehicle; + +enum Size; + +test check_vehicle; + +with entry { + car = vehicle(); + print(foo()); + print(car.name); + print(Size.Medium.value); +} +``` +The bodies should be defined somewhere in the codebase for the program to be compiled successfully. The notation for defining the function/object/enum bodies are as follows, for the given example. + +```python +:can:foo() { + return ("Hello"); +} + +:obj:vehicle { + has name: str = "Car"; +} + +:enum:Size { + Small=1, + Medium=2, + Large=3 +} + +:test:check_vehicle { + check assertEqual(vehicle(name='Van').name, 'Van'); +} +``` + +However, there are multiple locations where this code can be held in order for this implementation separation to work. + +### Same ```.jac``` file as declaration + +The bodies of the objects can be held in the same file as the declaration. This will only improve the code visually during declaration while code management is not sgnificantly improved. + +### Including files in ```<>.impl.jac``` / ```<>.test.jac``` files + +If the programmer requires better codebase management with having the implementations together in a separate file, jac-lang facilitates that as well. In the previous example there are implementation of objects/enums/functions as well as test. These can be separated in a separate files living in the base path as the main module, named as ```.impl.jac``` and ```.test.jac```. Including or importing these files are not required. The file structure can be shown as follows. + +``` +base +├── main.jac +├── main.impl.jac +└── main.test.jac +``` + +However, all implementation files should be located in the base path which can become because of this if there are multiple files, each having their own implementation file. + +### Including files in ```<>.impl``` / ```<>.test``` folders + +The implementation of the program can be coded within individual .impl and .test folders as well. These folders should be named as ```.impl``` and ```.impl```. + +Additional benefits of this separation is that inside the folder the implementations can be broken down into multiple files as per the programmer's preference, as long as each file has the ```.impl.jac``` or ```.test.jac``` suffixes. The file structure can look as follows. + +``` +base +├── main.jac +│ +├── main.impl +│ ├── foo.impl.jac +│ ├── vehicle.impl.jac +│ └── size.impl.jac +│ +└── main.test + └── check_vehicle.test.jac +``` + +These file separation features in jac-lang allows the programmer to organize their code seamlessly without any extra ```include``` or ```import``` statements. + +> **NOTE :** +> Even if adding the suffixes, as described above, to separated files and folders are not done the separated code bodies can still live in separate files and folders as long as they are included in the main module. \ No newline at end of file From ddad354774682a6d1f3e804e0758fdc7440312fe Mon Sep 17 00:00:00 2001 From: Jayanaka-98 Date: Mon, 29 Jul 2024 17:55:22 +0530 Subject: [PATCH 2/3] Trailing white spaces fixed --- support/jac-lang.org/docs/learn/impl_docs.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/support/jac-lang.org/docs/learn/impl_docs.md b/support/jac-lang.org/docs/learn/impl_docs.md index 0cd39b64c..2e4c3a13e 100644 --- a/support/jac-lang.org/docs/learn/impl_docs.md +++ b/support/jac-lang.org/docs/learn/impl_docs.md @@ -26,11 +26,12 @@ print(foo()) print(car.name) print(Size.Medium.value) ``` + However, Jac-lang offers novel language features which allows a programmer to organize their code effortlessly. -## Separating function/object bodies from their declaration. +## Separating function/object bodies from their declaration -In jaclang the declaration of functions and objects can be done independently, as shown in the below code snippet. By doing so, it creates an empty shell for the function/object/enum. +In jaclang the declaration of functions and objects can be done independently, as shown in the below code snippet. By doing so, it creates an empty shell for the function/object/enum. ```python can foo(); @@ -76,7 +77,7 @@ However, there are multiple locations where this code can be held in order for t The bodies of the objects can be held in the same file as the declaration. This will only improve the code visually during declaration while code management is not sgnificantly improved. -### Including files in ```<>.impl.jac``` / ```<>.test.jac``` files +### Including files in ```<>.impl.jac``` / ```<>.test.jac``` files If the programmer requires better codebase management with having the implementations together in a separate file, jac-lang facilitates that as well. In the previous example there are implementation of objects/enums/functions as well as test. These can be separated in a separate files living in the base path as the main module, named as ```.impl.jac``` and ```.test.jac```. Including or importing these files are not required. The file structure can be shown as follows. @@ -91,7 +92,7 @@ However, all implementation files should be located in the base path which can b ### Including files in ```<>.impl``` / ```<>.test``` folders -The implementation of the program can be coded within individual .impl and .test folders as well. These folders should be named as ```.impl``` and ```.impl```. +The implementation of the program can be coded within individual .impl and .test folders as well. These folders should be named as ```.impl``` and ```.impl```. Additional benefits of this separation is that inside the folder the implementations can be broken down into multiple files as per the programmer's preference, as long as each file has the ```.impl.jac``` or ```.test.jac``` suffixes. The file structure can look as follows. @@ -111,4 +112,4 @@ base These file separation features in jac-lang allows the programmer to organize their code seamlessly without any extra ```include``` or ```import``` statements. > **NOTE :** -> Even if adding the suffixes, as described above, to separated files and folders are not done the separated code bodies can still live in separate files and folders as long as they are included in the main module. \ No newline at end of file +> Even if adding the suffixes, as described above, to separated files and folders are not done the separated code bodies can still live in separate files and folders as long as they are included in the main module. From 214bc2752bf090b212e32090516f0eb71d9e478a Mon Sep 17 00:00:00 2001 From: Jayanaka-98 Date: Tue, 30 Jul 2024 17:40:02 +0530 Subject: [PATCH 3/3] Linking to mkdocs --- support/jac-lang.org/docs/learn/impl_docs.md | 4 ++-- support/jac-lang.org/mkdocs.yml | 1 + 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/support/jac-lang.org/docs/learn/impl_docs.md b/support/jac-lang.org/docs/learn/impl_docs.md index 2e4c3a13e..bb66c4eb2 100644 --- a/support/jac-lang.org/docs/learn/impl_docs.md +++ b/support/jac-lang.org/docs/learn/impl_docs.md @@ -33,7 +33,7 @@ However, Jac-lang offers novel language features which allows a programmer to or In jaclang the declaration of functions and objects can be done independently, as shown in the below code snippet. By doing so, it creates an empty shell for the function/object/enum. -```python +```jac linenums="1" can foo(); obj vehicle; @@ -51,7 +51,7 @@ with entry { ``` The bodies should be defined somewhere in the codebase for the program to be compiled successfully. The notation for defining the function/object/enum bodies are as follows, for the given example. -```python +```jac linenums="1" :can:foo() { return ("Hello"); } diff --git a/support/jac-lang.org/mkdocs.yml b/support/jac-lang.org/mkdocs.yml index 06872f883..307ed0e2d 100644 --- a/support/jac-lang.org/mkdocs.yml +++ b/support/jac-lang.org/mkdocs.yml @@ -10,6 +10,7 @@ nav: - ~/for_coders: - 'learn/guide.md' - 'learn/jac_ref.md' + - 'learn/impl_docs.md' - 'learn/with_llm.md' - 'learn/tips_tricks.md' - 'learn/jac_plugins.md'