Skip to end of metadata
Go to start of metadata

Boo.Lang.Useful - an assembly rife with things beautiful and useful yet not quite core to the Boo language. Welcome to this introductory guide, where we will plumb its murky depths in search of adventure on the high seas and delicious pirate treasures.

What's so Useful about this Useful assembly?!

Boo.Lang.Useful is meant for user contributions to Boo in Boo - sometimes you have a really good idea for a great addition to Boo, but it just isn't "core" for the language. Enter, Boo.Lang.Useful: an assembly based primarily of user contributions for stuff that is extremely helpful but not quite core. If you want to contribute, please go to JIRA and open a new issue in the "Boo.Lang.Useful" component, and attach a patch for your component. Please follow the Coding Conventions page for submissions.

Here are some of the out-standing features already available ...

Useful.IO

TextFile (class)

Summary

This class is used as a quick and dirty to enumerate through the lines in a text file as if it were any other object that implemented the IEnumerable interface. It is useful for quickly grokking information in newline-delimited (\n, or \r\n) formats. It is also useful for editing a file's contents with a short, sweet, and simple API.

The static methods ReadFile() and WriteFile() are used to respectively read the entire contents of a file to a string, and write the contents of a string to a file.

Example:

text.txt

textReader.boo

forEachFileIn (function)

Summary

eachFile accepts two parameters: a string containing a directory that will act as root, and a function that will be executed for each file in the root directory and all of the root directory's subdirectories. This function is recursive.

listFiles (function)

Summary

listFiles returns an enumerable object, a list of strings that represent filenames in the root directory and every subdirectory specified by the parameter. It is a recursive function.

Example

walk (function)

Summary

walk returns an enumerable object consisting of three elements: the current directory, an array of strings representing subdirectories within the current directory, and an array of strings representing files within the current directory. It is a recursive function.

Example

Useful.Attributes

Singleton (attribute)

Summary

The Singleton attribute automates the implementation of the Singleton design pattern. Attaching this attribute to a structure or a class generates code to protect all constructors and and implements a single property, 'Instance,' that points to an instance of your class.

If you want to initalize certain objects, create a parameter-less constructor (this will be made protected and will be called by the Singleton attribute).

For more information about the singleton design pattern, check out this article.

Example.

Once attribute

Summary

Applied to a method, the Once attribute will automatically cache the value returned by the method on it's first call. Following calls to the method will simply re-use the cached value. This is usefull for methods that do long and / or expensive processing since the processing will be done only 'Once'.
Notes:

  • To avoid confusion for the user of the method, the attribute should not be applied on a method that accepts parameters, since the method will always return the same results even when called with different parameter values.
  • This attribute is intended for expensive calculations, it is not recommended for short methods and properties.
  • The modified method will be made thread safe through the use of a lock.

Example.

Useful.Collections

Set (class)

Summary

A Set class for the math freaks. (stub, fill in later)

  • No labels

1 Comment

  1. TextFile (class) not in Useful.IO

    Impl, Preprossor, & WalkModule are in Useful.IO but aren't documented here.

    AutoFlagsAttribute, NoTrace, & TraceMethodCallsAttribute are in Useful.Attributes but aren't documented here.