Merge pull request #4 from ash-shell/br.package-imports

Br.package imports

Author: BrandonRomano

README.md

@@ -2,64 +2,78 @@
 
 Obj is an [Ash](https://github.com/ash-shell/ash) module that adds object support to Bash.
 
+> If you want to first get excited about this before reading the entire README, jump to [this section](#class-example).
+
 # Getting started
 
-## Ash Users
+Obj is part of the Ash core, so you can just start using it in your Ash modules.
 
-Obj is part of the Ash core, so you can immediately start using it within your Ash modules.
+For an example of an ash module that uses objects, [look here](https://github.com/BrandonRomano/ash-obj-examples).
 
-Simply place your Classes in a directory named `classes` in the root of your modules directory, and start using them!
+# Features + Usage
 
-For an example of an ash module that uses objects, [look here](https://github.com/BrandonRomano/ash-obj-examples).
+## Imports
 
-## Non Ash Users
+Before we can start using any objects, we must first import them.
 
-Even if you're not an Ash user, this module can be used as a library.
+If the objects you want to use are in your current module, they are already imported for you.
 
-Just include the `obj.sh` library file in your script, and also point to where you're going to be keeping your classes.
+If the objects you want to use are outside of your current module, you must import them. You can import an external module with `Obj__import`:
 
-The start of your script will look something like this:
+```bash
+Obj__import "$package_to_import" "$package_alias"
+```
+
+`$package_to_import` is the modules package (as specified in its `ash_config.yaml` file), while `$package_alias` is the alias in which we will refer to the newly imported package.
+
+If I have `https://github.com/BrandonRomano/ash-obj-examples` installed and would like to import its classes in a different module, I would this following line to my module:
 
 ```bash
-. lib/obj.sh                            # Importing Obj library
-Obj__classes_directory="./classes"      # Setting classes directory
+Obj__import "github.com/BrandonRomano/ash-obj-examples" "objex"
 ```
 
-# Features + Usage
+> External modules must first be installed before importing them.  See [apm](https://github.com/ash-shell/apm).
 
 ## Creating Classes
 
 Before getting into any details, as you would expect classes are the definition of what an object is.
 
-Classes must be placed in the directory defined to hold classes (for Ash users, this is in a directory named `classes` in the root of your module).  Classes also must be named as their classname with `.sh` as their extension.  By convention, you should use [PascalCase](http://c2.com/cgi/wiki?PascalCase) for class naming as many modern programming languages use.
+Classes must be placed in the directory named `classes` in the root of a module.  Classes also must be named as their classname with `.sh` as their extension.  By convention, you should use [PascalCase](http://c2.com/cgi/wiki?PascalCase) for class naming as many modern programming languages use.
 
 > For example, if I were to create a class that would define what a Person object is, I would name the file `Person.sh`.
 
+### Class Example
+
 I'll explain the different components of what a class is below, but here is what a class looks like.  This would be in a file named Person.sh in our classes diretory:
 
-> For a fully commented version of this class, look [here](https://github.com/ash-shell/obj-examples/blob/master/classes/Person.sh)
+> For a fully commented version of this class, look [here](https://github.com/BrandonRomano/ash-obj-examples/blob/master/classes/Person.sh)
 
 ```bash
 #!/bin/bash
 # This is a simple class that represents a Person.
 
+# Public member variables
 Person__id=""
 Person__name=""
 Person__age=""
 
+# Private member variable
 Person_birthdays_count=0
 
+# Constructor
 Person__construct(){
     Person__id="$1"
     Person__name="$2"
     Person__age="$3"
 }
 
+# Public method
 Person__make_older(){
     Person__age=$((Person__age+1))
     Person_update_birthday_count
 }
 
+# Private method
 Person_update_birthday_count(){
     Person_birthdays_count=$((Person_birthdays_count+1))
     echo "Happy Birthday $Person__name!"
@@ -101,7 +115,7 @@ A private method is a function denoted by the Class name followed by a single un
 
 ### Constructors
 
-Constructors are magically named funcitons that get called when an object is initialized.  Constructors can take an arbitrary amount of parameters, and have all of the same powers as a public method (as it technically is a public method).
+Constructors are magically named funcitons that get called when an object is initialized.  Constructors can take an arbitrary amount of parameters, and have all of the same powers as a public method (as it technically is just a public method).
 
 A constructor is a function denoted by the class name followed by `__construct`.
 
@@ -134,6 +148,21 @@ Obj__init $brandon 1 "Brandon" 23
 
 Now I have a reference to `$brandon`, which is a pointer to a initialized object representing myself.
 
+##### From an External Package
+
+If I wanted to create an object from an external package that I've imported, we must specify the package alias in `Obj__alloc`, in `alias.ClassName` format:
+
+```bash
+# Importing
+Obj__import "github.com/BrandonRomano/ash-obj-examples" "objex"
+
+# Creating the Object
+brandon=$(Obj__alloc "objex.Person")  # Note the `objex.` before the class name
+Obj__init $brandon 1 "Brandon" 23
+```
+
+> When you're creating an object from the current context, you could actually say `this.ClassName` - Although, it isn't necessisary because if you don't specify a package, `Obj__alloc` by default assumes you mean `this`.
+
 ##### A quick Obj__init Gotcha
 
 It's worth nothing that if you use `Obj__init` within a subshell, the object will only be initialized within the scope of that subshell.  Your best bet is to not wrap this call in a subshell unless you really know what you're doing.  However, we are allowed to pass objects into subshells after they have been initialized.  This follows the same rules as variables in a subshell:
@@ -151,7 +180,6 @@ If I were to run `Obj__dump $brandon`, immediately after initializing the object
 | age=23
 | id=3
 | name='Brandon Romano'
-=====================================
 ```
 
 As you can see, `Obj__dump` prints out all of the public variables in an object.
@@ -183,7 +211,6 @@ An `Obj__dump` on our `$brandon` object would now yield:
 | age=23
 | id=3
 | name='Brandon Romano'
-=====================================
 ```
 
 #### Accessing Member Variables (Obj__get)
@@ -211,7 +238,7 @@ Brandon Romano
 
 ### Calling Public Methods
 
-Inside of a class, methods are called with the full name of the function (e.g. `Person__make_older`).
+Inside of a class, all methods are called with the full name of the function (e.g. `Person__make_older`).
 
 Outside of the class, this is different, and public methods must be called via `Obj__call`.
 

lib/import.sh

@@ -0,0 +1,79 @@
+#!/bin/bash
+
+# Alias for current context
+Obj__THIS="this"
+
+# Imports map
+Obj_imports=( )
+
+################################################################
+# Imports a package
+#
+# @param $1: The module to import
+# @param $2: The alias of the module
+################################################################
+Obj__import() {
+    # Params
+    local import_module="$1"
+    local module_alias="$2"
+
+    # Checking if package path exists
+    local package_path=$(Ash__find_module_directory "$import_module" 0)
+    if [[ "$package_path" = "" ]]; then
+        Logger__error "Cannot import $import_module, no module with that package is installed"
+        exit
+    fi
+
+    # Verifying there is an alias
+    if [[ "$module_alias" = "" ]]; then
+        Logger__error "Cannot import without an alias"
+        exit
+    fi
+
+    # Checking if the alias already exists
+    local import=""
+    local pos=0
+    for import in "${Obj_imports[@]}" ; do
+        local key=${import%%:*}
+        local value=${import#*:}
+        if [[ "$key" = "$module_alias" ]]; then
+            # Replace it
+            Obj_imports[$pos]="$module_alias:$import_module"
+            return
+        fi
+        pos=$((pos+1))
+    done
+
+    # Appending to imports
+    Obj_imports+=("$module_alias:$import_module")
+}
+
+
+################################################################
+# Gets the import directory from the alias
+#
+# @param $1: The alias of an import
+# @returns: The package of the module
+################################################################
+Obj_get_imported_package() {
+    local import=""
+    for import in "${Obj_imports[@]}" ; do
+        local key=${import%%:*}
+        local value=${import#*:}
+        if [[ "$key" = "$1" ]]; then
+            echo "$value"
+            return
+        fi
+    done
+}
+
+################################################################
+# Gets the import directory from the alias
+#
+# @param $1: The alias of an import
+# @returns: The directory of the module
+################################################################
+Obj_get_imported_directory() {
+    local package="$(Obj_get_imported_package $1)"
+    echo "$(Ash__find_module_directory "$package" 0)"
+}

lib/obj.sh

@@ -1,18 +1,23 @@
 #!/bin/bash
 
-# The directory we are pulling the classes from.
-# This will need to bet set!
-Obj__classes_directory=""
-
 ################################################################
 # Allocates an object pointer.  Must call `Obj__init` on this
 # pointer after this is called.
 #
-# @param $1: The name of the class to instantiate
+# @param $1: The class to instantiate, following the format:
+#   alias.ClassName
 # @returns: A pointer to the object
 ################################################################
 Obj__alloc(){
-    echo "$1_$(Obj_generate_uuid)"
+    local class="$1"
+
+    # Setting 'this' package if no package was specified
+    if [[ ! "$class" =~ .*\..* ]]; then
+        class="$Obj__THIS.$class"
+    fi
+
+    class=${class//\./_}
+    echo "$class""_$(Obj_generate_uuid)"
 }
 
 ################################################################
@@ -28,17 +33,33 @@ Obj__init(){
     IFS='_' read -ra segment <<< "$1"
     for part in "${segment[@]}"; do
         if [[ "$position" -eq 1 ]]; then
-            local class="$part"
+            local package_alias="$part"
         elif [[ "$position" -eq 2 ]]; then
+            local class="$part"
+        elif [[ "$position" -eq 3 ]]; then
             local uuid="$part"
         fi
         position=$((position+1))
     done
 
+    # Getting the class directory for the package
+    local class_directory="$(Obj_get_imported_directory "$package_alias")/$Ash__module_classes_folder"
+    if [[ "$class_directory" = "" ]]; then
+        Logger__error "Cannot create an object with the alias of $package_alias, as it has not been imported"
+        exit
+    fi
+
+    # Verifying file exists
+    local class_file="$class_directory/$class.sh"
+    if [[ ! -f "$class_file" ]]; then
+        Logger__error "There is no file named $class.sh in the aliased package"
+        exit
+    fi
+
     # Creating unique variable / method names
     local to_find="$class"_
-    local to_replace="$class"_"$uuid"_
-    eval "$(cat "$Obj__classes_directory/$class.sh" | sed -e "s:$to_find:$to_replace:g")"
+    local to_replace="$package_alias"_"$class"_"$uuid"_
+    eval "$(cat "$class_directory/$class.sh" | sed -e "s:$to_find:$to_replace:g")"
 
     # Calling the constructor
     Obj__call $1 construct "${@:2}"
@@ -65,6 +86,10 @@ Obj__get(){
 ################################################################
 Obj__set(){
     variable="$1__$2"
+    if [ -z ${!variable+x} ]; then
+        Logger__error "Cannot set the variable '$2' to the object, it is not defined in its class"
+        exit
+    fi
     eval $variable="\"$3\""
 }
 
@@ -76,7 +101,27 @@ Obj__set(){
 # @param ${@:3} Any additional parameters to the method
 ################################################################
 Obj__call(){
+    # Params
+    local pointer="$1"
+    local method_name="$2"
+
+    # Getting package alias
+    IFS='_' read -ra segment <<< "$pointer"
+    for part in "${segment[@]}"; do
+        local package_alias="$part"
+        break
+    done
+
+    # Swapping current context so we can self-reference in any method calls
+    local old_context=$(Obj_get_imported_package "$Obj__THIS")
+    local new_context=$(Obj_get_imported_package "$package_alias")
+    Obj__import "$new_context" "$Obj__THIS"
+
+    # Calling method
     "$1__$2" "${@:3}"
+
+    # Resetting context
+    Obj__import "$old_context" "$Obj__THIS"
 }
 
 ################################################################
@@ -87,7 +132,6 @@ Obj__call(){
 Obj__dump(){
     echo "====== $1 ======"
     (set -o posix ; set) | grep ^$1__ | sed -e "s:$1__::g" | sed -e "s:^:| :g"
-    echo "====================================="
 }
 
 ##################################
@@ -103,13 +147,13 @@ Obj_generate_uuid(){
 
     while [ "$count" -le $UUID_LENGTH ]
     do
-        random_number=$RANDOM
+        local random_number=$RANDOM
         let "random_number %= 16"
-        hexval=$(Obj_map_hex "$random_number")
-        uuid="$uuid$hexval"
+        local hexval=$(Obj_map_hex "$random_number")
+        local uuid="$uuid$hexval"
         let "count += 1"
     done
-    echo $uuid
+    echo "$uuid"
 }
 
 ##################################