fancy 0.3.3 → 0.4.0

data/lib/rbx/date.fy

@@ -1,10 +1,19 @@
 require("date")
 
 class Date {
+  """
+  Date class. Used for timely stuff.
+  """
+
+  forwards_unary_ruby_methods
+  metaclass forwards_unary_ruby_methods
+
   metaclass ruby_alias: 'today
   ruby_alias: '==
   ruby_alias: '-
   ruby_alias: '+
+  ruby_alias: '<
+  ruby_alias: '>
 
   def != other {
     self == other not

data/lib/rbx/directory.fy

@@ -43,4 +43,22 @@ class Directory {
       IOError new: (e message) . raise!
     }
   }
+
+  def self list: pattern {
+    """
+    @pattern Directory pattern or name containing files to be returned as an @Array@.
+    @return @Array@ of files matching directory @pattern.
+
+    Example usage:
+        Directory list: \"tests/**/*.fy\"  # => [\"tests/file1.fy\", \"tests/more/file2.fy\"]
+    """
+
+    match pattern {
+      case /\/$/ -> pattern = pattern + "*"
+      case "." -> pattern = pattern + "/*"
+      case ".." -> pattern = pattern + "/*"
+    }
+
+    Dir glob(pattern)
+  }
 }

data/lib/rbx/environment_variables.fy

@@ -1,3 +1,4 @@
 class Rubinius EnvironmentVariables {
+  forwards_unary_ruby_methods
   ruby_alias: '[]
 }

data/lib/rbx/exception.fy

@@ -1,6 +1,13 @@
+class Exception {
+  forwards_unary_ruby_methods
+}
+
 class StandardError {
-  ruby_alias: 'message
-  ruby_alias: 'backtrace
+  """
+  StandardError. Base class of most Exception classes.
+  """
+
+  forwards_unary_ruby_methods
 
   def initialize {
     "Creates a new Exception with an empty message."

data/lib/rbx/fiber.fy

@@ -1,22 +1,40 @@
-require("fiber")
-
 Fiber = Rubinius Fiber
 
 class Fiber {
+   forwards_unary_ruby_methods
+   metaclass forwards_unary_ruby_methods
+
    metaclass ruby_alias: 'yield
-   metaclass ruby_alias: 'current
    ruby_alias: 'resume
-   ruby_alias: 'alive?
 
    def self new: block {
+     """
+     @block @Block@ to be run in a new Fiber.
+
+     Creates a new Fiber running @block.
+     """
+
      new(&block)
    }
 
    def Fiber yield: vals {
+     """
+     @vals @Array@ of values to pass along to parent @Fiber@.
+
+     Returns execution control to the parent @Fiber@ and passes along @vals.
+     """
+
      yield(*vals)
    }
 
    def resume: vals {
+     """
+     @vals @Array@ of values to pass along to @self for resuming.
+
+     Resumes @self (if paused) or raises an exception, if @Fiber@ is dead.
+     Passes along @vals as the return value of the last call to @yield in @self.
+     """
+
      resume(*vals)
    }
 }

data/lib/rbx/file.fy

@@ -22,11 +22,11 @@ class File {
 
     E.g. to open a File with read access and read all lines and print them to STDOUT:
 
-      File open: \"foo.txt\" modes: [:read] with: |f| {
-        { f eof? } while_false: {
-          f readln println
+        File open: \"foo.txt\" modes: ['read] with: |f| {
+          { f eof? } while_false: {
+            f readln println
+          }
         }
-      }
     """
 
     modes_str = modes_str: modes_arr
@@ -93,7 +93,7 @@ class File {
 
     str = ""
     modes_arr each: |m| {
-      str = str ++ (@@open_mode_conversions[m])
+      str << (@@open_mode_conversions[m])
     }
     str uniq join: ""
   }

data/lib/rbx/fixnum.fy

@@ -1,6 +1,10 @@
 require: "../number"
 
 class Fixnum {
+  """
+  Standard class for integer values in Fancy.
+  """
+
   include: Number
 
   ruby_alias: '==
@@ -18,6 +22,7 @@ class Fixnum {
   ruby_alias: 'to_f
   ruby_alias: '**
   ruby_alias: '&
+  ruby_alias: '|
 
   alias_method: 'to_s: for: 'to_s
   alias_method: 'modulo: for: 'modulo

data/lib/rbx/float.fy

@@ -1,6 +1,12 @@
 class Float {
+  """
+  Standard class for floating point number values in Fancy.
+  """
+
   include: Number
 
+  forwards_unary_ruby_methods
+
   ruby_alias: '+
   ruby_alias: '-
   ruby_alias: '*
@@ -8,8 +14,10 @@ class Float {
   ruby_alias: '==
   ruby_alias: '>=
   ruby_alias: '<=
-  ruby_alias: '<=>
-  ruby_alias: 'to_i
-  ruby_alias: 'to_f
   ruby_alias: '**
+  ruby_alias: '<
+  ruby_alias: '>
+
+  alias_method: 'modulo: for: 'modulo
+  alias_method: ":%" for: "modulo:" # use a : so we dont overwrite ruby's % operator
 }

data/lib/rbx/hash.fy

@@ -1,26 +1,12 @@
 class Hash {
+  forwards_unary_ruby_methods
 
-  alias_method: ":size" for: 'size
   alias_method: ":[]" for: '[]
   alias_method: 'at:put: for: "[]="
+  alias_method: '[]: for: "[]="
   alias_method: 'at: for: '[]
-  ruby_alias: 'keys
-  ruby_alias: 'values
   ruby_alias: '==
 
-  def inspect {
-    str = "<["
-    max = size - 1
-    i = 0
-    each: |key,val| {
-      str = str ++ (key inspect) ++ " => " ++ (val inspect)
-      { str = str + ", " } if: (i < max)
-      i = i + 1
-    }
-    str = str + "]>"
-    str
-  }
-
   def each: block {
     each(&block)
   }
@@ -36,4 +22,33 @@ class Hash {
   def map: block {
     map(&block)
   }
+
+  def delete: key {
+    """
+    @key Key of key-value pair to be deleted in @self.
+
+    Deletes a key-value pair from @self.
+    """
+
+    delete(key)
+  }
+
+  def merge: other_hash {
+    merge(other_hash)
+  }
+
+  def merge!: other_hash {
+    merge!(other_hash)
+  }
+
+  def includes?: key {
+    """
+    @key Key to search for.
+    @return @true, if Hash includes @key, @false otherwise.
+
+    Indicates if a given key is in @self.
+    """
+
+    include?(key)
+  }
 }

data/lib/rbx/integer.fy

@@ -2,6 +2,7 @@ class Integer {
   # common ruby-forwarding methods used by Fixnum & Bignum classes
 
   def times: block {
+    # this version gets replaced in lib/integer.fy with a native one
     times(&block)
   }
 }

data/lib/rbx/io.fy

@@ -1,10 +1,4 @@
-class IO {
-  ruby_alias: 'readlines
-  ruby_alias: 'readline
-  ruby_alias: 'read
-  ruby_alias: 'close
-  ruby_alias: 'eof?
-
+class IOMixin {
   def readln {
     readline
   }
@@ -28,3 +22,19 @@ class IO {
   alias_method: 'write: for: 'print:
   alias_method: 'writeln: for: 'println:
 }
+
+class IO {
+  """
+  Base class for IO related classes (like @File@, @Socket@, @Console@ etc.).
+  """
+
+  include: IOMixin
+
+  ruby_alias: 'readlines
+  ruby_alias: 'readline
+  ruby_alias: 'read
+  ruby_alias: 'close
+  ruby_alias: 'eof?
+
+  forwards_unary_ruby_methods
+}

data/lib/rbx/match_data.fy

@@ -1,15 +1,26 @@
 class MatchData {
+   """
+   MatchData instances are created when using the #=== match operator
+   (e.g. by using match/case expressions).
+   """
+
    ruby_alias: 'size
+   ruby_alias: '[]
 
    def at: idx {
-     ruby: '[] args: [idx]
-   }
+     """
+     @idx Index of value to get.
+     @return Value at index @idx.
+     """
 
-   def [] idx {
-     at: idx
+     self[idx]
    }
 
    def to_a {
+     """
+     @return @Array@ representation of @self containing matched values of @self.
+     """
+
      arr = []
      self size times: |i| {
        arr << (at: i)

data/lib/rbx/method.fy

@@ -1,15 +1,27 @@
 class MethodMixin {
+  """
+  Mixin class with common methods included by @Method@ and @UnboundMethod@.
+  """
+
   def documentation {
+    """
+    @return Docstring for @self.
+    """
+
     Fancy Documentation for: (executable())
   }
 
-  def documentation: str {
-    Fancy Documentation for: (executable()) is: str
+  def documentation: docstring {
+    """
+    @docstring New docstring for @self.
+    """
+
+    Fancy Documentation for: (executable()) is: docstring
   }
 
   def visibility {
     """
-    Returns the visibility ('private, 'protected, 'public) of a @Method@ in its defined context, if any.
+    @return The visibility (@'private, @'protected, @'public) of a @Method@ in its defined context, if any.
     """
     entry = @defined_in method_table() lookup(@name)
     { entry visibility() } if: entry
@@ -17,33 +29,54 @@ class MethodMixin {
 
   def public? {
     """
-    Returns true, if the @Method@ is public in its defined context.
+    @return @true, if the @Method@ is public in its defined context.
     """
     visibility == 'public
   }
 
   def protected? {
     """
-    Returns true, if the @Method@ is protected in its defined context.
+    @return @true, if the @Method@ is protected in its defined context.
     """
     visibility == 'protected
   }
 
   def private? {
     """
-    Returns true, if the @Method@ is private in its defined context.
+    @return @true, if the @Method@ is private in its defined context.
     """
     visibility == 'private
   }
+
+  def tests {
+    """
+    Returns an Array of all the FancySpec SpecTests defined for a
+    Method.
+    """
+
+    @__method_tests__ =  @__method_tests__ || []
+    @__method_tests__
+  }
+
+  def test: test_block {
+    it = FancySpec new: self
+    test_block call: [it]
+    tests << it
+  }
 }
 
 class Method {
   ruby_alias: 'arity
   include: MethodMixin
+  forwards_unary_ruby_methods
 }
 
 class UnboundMethod {
+  """
+  An instance UnboundMethod represents a Method object not bound to a specific @Class@ or @Object@.
+  """
+
   ruby_alias: 'arity
   include: MethodMixin
+  forwards_unary_ruby_methods
 }
-

data/lib/rbx/name_error.fy

@@ -1,3 +1,7 @@
 class NameError {
+  """
+  NameError exception class. Used within Rubinius.
+  """
+
   ruby_alias: 'name
 }

data/lib/rbx/object.fy

@@ -1,81 +1,149 @@
-class Class {
-  def alias_method: new for: old {
-    alias_method(new, old)
-  }
-
-  def ruby_alias: method_name {
-    alias_method(":" + (method_name to_s), method_name)
-  }
-}
-
-class String {
-  alias_method: ":+" for: "+"
-}
-
 class Object {
-
   ruby_alias: '==
   ruby_alias: '===
   ruby_alias: 'class
   ruby_alias: 'inspect
+  ruby_alias: 'object_id
+  ruby_alias: 'instance_variables
 
   def initialize {
     initialize()
   }
 
+  def require: file_path {
+    """
+    Loads and evaluates a given Fancy source file by trying to find the specified
+    @file_path in Fancy's loadpath (see @Fancy::CodeLoader@).
+    Relative paths are allowed (and by default expected).
+    """
+    Fancy CodeLoader require: file_path
+  }
+
   def dclone {
     "Returns a deep clone of self using Ruby's Marshal class."
     Marshal load(Marshal dump(self))
   }
 
   def to_s {
+    """
+    @return @String@ represenation of @self.
+    """
+
     to_s()
   }
 
   def set_slot: slotname value: val {
+    """
+    @slotname Name of slot to be set.
+    @val Value for slot to be set.
+
+    Sets an object's slot with a given value.
+    """
+
     instance_variable_set("@" ++ slotname, val)
   }
 
   def get_slot: slotname {
+    """
+    @slotname Name of slot to get the value of.
+    @return Value of slot with name @slotname.
+
+    Returns the value of a slot of @self.
+    """
+
     instance_variable_get("@" ++ slotname)
   }
 
   def define_singleton_method: name with: block {
+    """
+    @name Name of the method to be defined on @self.
+    @block @Block@ to be used as the method's body.
+
+    Dynamically defines a method on @self's metaclass (a singleton method) using a given @Block@.
+    """
+
     metaclass define_method: name with: block
   }
 
   def undefine_singleton_method: name {
+    """
+    @name Name of the method to be undefined no @self's metaclass.
+
+    Undefines a singleton method of @self.
+    """
+
     metaclass undefine_method: name
   }
 
   def is_a?: class {
-    "Indicates, if an object is an instance of a given Class."
+    """
+    @class @Class@ to check for if @self is an instance of.
+    @return @true if @self is an instance of @class, @false otherwise.
+
+    Indicates, if an object is an instance of a given Class.
+    """
+
     is_a?(class)
   }
 
   def kind_of?: class {
-    "Indicates, if an object is an instance of a given Class."
+    """
+    Same as Object#is_a?:
+    Indicates, if an object is an instance of a given Class.
+    """
+
     kind_of?(class)
   }
 
-  def send_message: message {
+  def receive_message: message {
+    """
+    @message Name of message to be sent to @self dynamically.
+
+    Dynamically sends a given message (without parameters) to @self.
+    """
+
     send(message_name: message)
   }
 
-  def send_message: message with_params: params {
-    ruby: (message_name: message) args: params
+  def receive_message: message with_params: params {
+    """
+    @message Name of message to be sent to @self dynamically.
+    @params @Array@ of parameters used with @message.
+
+    Dynamically sends a given message with parameters to @self.
+    """
+
+   ruby: (message_name: message) args: params
   }
 
   def message_name: symbol {
     symbol = symbol to_s
-    if: (symbol =~ /:/) then: {
-      symbol
-    } else: {
-      ":" ++ symbol
+    match symbol =~ /:/ {
+      case nil ->
+        ":" ++ symbol
+      case _ ->
+        symbol
     }
   }
 
   def responds_to?: message {
+    """
+    @message The message to check for (preferably a Symbol).
+    @return @true if @self responds to @message, @false otherwise.
+
+    Indicates if an object responds to a given message.
+    """
+
     respond_to?(message_name: message)
   }
+
+  def extend: class {
+    """
+    @class @Class@ to extend @self with.
+
+    Extends @self with the methods in @class (by including its methods in @self's metaclass).
+    """
+
+    metaclass include: class
+  }
 }