use std::path;
fn alreadyExists(items: Vec<Path>, quer: &str) -> bool {
items.iter().any(|nms: &Path| -> (bool) {nms == &Path::new(quer)})
}
This searches over the items iterator, checking each path against a filename, and returns "true" if the file exists in the directory, or "false" otherwise. It does this by way of a higher-order function (.any) that takes individual &Path's and checking them against a temporary reference to a Path that has the same file name as what is being searched.
This approach is a tad bit intensive, since you will be putting a lot of temporary objects on the heap. However, the overall net effect on memory should be 0 since they all fall out of scope during each iteration of the iterator.
Saturday, June 28, 2014
Rust Note 5: Keyboard input in Rust
Rustlang is all about its functions. You barely have to run your program to make sure it works, and when you do, you write unit tests for them. But, what about good old days of taking keyboard input and faffing about without end in your program? Here's how to bring that back in Rust.
The Program
This program will take input and parrot it back to you. It's as simple as simple gets.
use std::io;
fn main(){
print!("Input: ");
println!("{}", io::stdin().read_line().unwrap());
}
io::stdin() returns a BufferedReader on stdio (the input stream). read_line() returns an IoResult (just used for handling some errors) that .unwrap() turns into a normal string. That is then printed by the println! macro.
Just be careful with .unwrap(). Part of Rust's power is being able to match against errors, and you lose that with .unwrap().
The Program
This program will take input and parrot it back to you. It's as simple as simple gets.
use std::io;
fn main(){
print!("Input: ");
println!("{}", io::stdin().read_line().unwrap());
}
io::stdin() returns a BufferedReader on stdio (the input stream). read_line() returns an IoResult (just used for handling some errors) that .unwrap() turns into a normal string. That is then printed by the println! macro.
Just be careful with .unwrap(). Part of Rust's power is being able to match against errors, and you lose that with .unwrap().
Thursday, June 26, 2014
Rust note 4: Rust unit tests
Unit tests are a crucial part of "real world" development. Manually testing code in some kind of REPL (which rust no longer has) is time-consuming and cannot be verified across distributions of your code. Luckily, rust provides unit testing right inside of its compiler, so you don't even need a third-party solution to bolster your code. Here's how to do it.
The assert! Macro
assert! is a simple concept that can be used in complex ways. It tests to see if a boolean is true, and, if it is, does nothing. Otherwise, it will call the fail!() macro, causing the program to terminate.
The test function
So, before we can test anything we need functions.
fn add_one(x: int) -> int { x + 1 }
fn subtract_one(x: int) -> int { x - 1}
Obviously, add_one(1) will be 2. And subtract_one(1) is zero. So, we put these assertions in a function called "test", which takes no arguments and returns nothing.
#[test]
fn test(){
assert!(add_one(1) == 2, "It's all gone wrong!");
assert!(subtract_one(1) == 0);
assert!(add_one(subtract_one(1)) == 1);
}
The test pragma ("#[test]") will tell rustc that this is a test. The function that tests the code can be named anything, as long as it returns nothing and takes no arguments. The tests inside of the function are just standard boolean expressions, and an optional message for if the code fails ("It's all gone wrong!"). Now, compile put this in a file and compile it with rustc --test file.rs.
Run the resulting executable. It should say "test result: ok. 1 passed, 0 failed; 0 ignored; 0 measured". The number of passed tests refers to how many #[test] pragmas are found. There can be a variable number of tests, so try to group up tests of a related domain under a single function.
Just out of curiosity, what would happen if you made the test fail? Well, it's not pretty.
The assert! Macro
assert! is a simple concept that can be used in complex ways. It tests to see if a boolean is true, and, if it is, does nothing. Otherwise, it will call the fail!() macro, causing the program to terminate.
The test function
So, before we can test anything we need functions.
fn add_one(x: int) -> int { x + 1 }
fn subtract_one(x: int) -> int { x - 1}
Obviously, add_one(1) will be 2. And subtract_one(1) is zero. So, we put these assertions in a function called "test", which takes no arguments and returns nothing.
#[test]
fn test(){
assert!(add_one(1) == 2, "It's all gone wrong!");
assert!(subtract_one(1) == 0);
assert!(add_one(subtract_one(1)) == 1);
}
The test pragma ("#[test]") will tell rustc that this is a test. The function that tests the code can be named anything, as long as it returns nothing and takes no arguments. The tests inside of the function are just standard boolean expressions, and an optional message for if the code fails ("It's all gone wrong!"). Now, compile put this in a file and compile it with rustc --test file.rs.
Run the resulting executable. It should say "test result: ok. 1 passed, 0 failed; 0 ignored; 0 measured". The number of passed tests refers to how many #[test] pragmas are found. There can be a variable number of tests, so try to group up tests of a related domain under a single function.
Just out of curiosity, what would happen if you made the test fail? Well, it's not pretty.
Rust Note 3: For loops in Rust
Rust is a very progressive language. It tries to not make the same mistake that D made, and include parts of the language just because its predecessors had them. One such removal is the for loop.
For the uninformed, a for loop syntax in most languages is as such: for(declaration; guard; statement). An example:
for(int x = 0; x < 100; x++){;}
This for loop will do nothing 100 times. But, Rust doesn't have a for loop? How can you do an equal amount of nothing? The answer is to use the range() function of the standard library. Range() is an iterator, meaning that the rust version of the for loop can act over it. You can generate a list of numbers with range(lowerBounds, higherBounds) and iterate over it. Here's the translation of that loop from above:
for x in range (0, 100){ }
Splendid! You're doing nothing just as efficiently as in a traditional language. However, what if you want to do something other than increment x by one each time? Well, you're in luck. You could either
let mut x: int = 0;
while x < 100{
// Awesome stuff here
x = x + 3
}
For the uninformed, a for loop syntax in most languages is as such: for(declaration; guard; statement). An example:
for(int x = 0; x < 100; x++){;}
This for loop will do nothing 100 times. But, Rust doesn't have a for loop? How can you do an equal amount of nothing? The answer is to use the range() function of the standard library. Range() is an iterator, meaning that the rust version of the for loop can act over it. You can generate a list of numbers with range(lowerBounds, higherBounds) and iterate over it. Here's the translation of that loop from above:
for x in range (0, 100){ }
Splendid! You're doing nothing just as efficiently as in a traditional language. However, what if you want to do something other than increment x by one each time? Well, you're in luck. You could either
- Implement the iterator trait for the type of data you're working on
- Do it the lazy way
let mut x: int = 0;
while x < 100{
// Awesome stuff here
x = x + 3
}
Rust Note 2: Map and Filter
There are two things that any functional programmer will try to implement when they find out that their language of choice has lists and function literals: map and filter. Here is how you do that in Rust:
Like with many things in Rust, it's important to consider the types involved with writing these functions. Map will take a list of any type of data (in this case, a slice of borrowed references (&[T])) and return a shiny new list. Filter will take a list of borrowed references as well, and either return a list of references to references passing the predicate (any function returning a boolean value), or return a new list. Since map is returning a new list, we will make filter do that as well.
Without further adieu, here's the code for filter:
fn filter<T: Clone>(lst: &[T], function: |x: &T| -> bool) -> Vec<T>{
let mut lVec = vec![];
for x in lst.iter(){
if (function(x)) { lVec.push(x.clone()); }
}
lVec
}
Note that whatever type you are filtering over must be a member of the Clone trait. It means that it can return something that's not a reference. So, this code will take any slice and a predicate, and return only the values for which the predicate is true.
Here is the map function:
fn map<T, U>(lst: &[T], function: |x: &T| -> U) -> Vec<U>{
let mut lVec = vec![];
for x in lst.iter(){
lVec.push(function(x));
}
lVec
}
This doesn't need a member of Clone, because it returns a different type, as specified by the parameter "function". Function is a function literal (technically, a closure), meaning that you can give this any function that takes the type of the list and returns any other value.
Like with many things in Rust, it's important to consider the types involved with writing these functions. Map will take a list of any type of data (in this case, a slice of borrowed references (&[T])) and return a shiny new list. Filter will take a list of borrowed references as well, and either return a list of references to references passing the predicate (any function returning a boolean value), or return a new list. Since map is returning a new list, we will make filter do that as well.
Without further adieu, here's the code for filter:
fn filter<T: Clone>(lst: &[T], function: |x: &T| -> bool) -> Vec<T>{
let mut lVec = vec![];
for x in lst.iter(){
if (function(x)) { lVec.push(x.clone()); }
}
lVec
}
Note that whatever type you are filtering over must be a member of the Clone trait. It means that it can return something that's not a reference. So, this code will take any slice and a predicate, and return only the values for which the predicate is true.
Here is the map function:
fn map<T, U>(lst: &[T], function: |x: &T| -> U) -> Vec<U>{
let mut lVec = vec![];
for x in lst.iter(){
lVec.push(function(x));
}
lVec
}
This doesn't need a member of Clone, because it returns a different type, as specified by the parameter "function". Function is a function literal (technically, a closure), meaning that you can give this any function that takes the type of the list and returns any other value.
Friday, June 20, 2014
Rust Note 1: Found Self in Ident Position
If you're anything like me, you know what it's like to wrestle with new technology. No documentation, no guidance, no hope. This series is an attempt to document the pitfalls of the Rust programming language. In the first quickfix, we will fix the "Found Self in Ident Position" error.
Example code: fn rest(&self) -> self;
Fixed code: fn rest(&self) -> Self;
Explanation
The return type is affected by the case of the letter, much like Haskell's types. In most "self in ident position" cases, you just need to swap the case.
Example code: fn rest(&self) -> self;
Fixed code: fn rest(&self) -> Self;
Explanation
The return type is affected by the case of the letter, much like Haskell's types. In most "self in ident position" cases, you just need to swap the case.
Thursday, April 3, 2014
Why Microsoft Open Sourced .NET
20:26 derive: Troll Harder
That's the response from an IRC channel chatter after the news came out about Microsoft's .NET. It left a lot of developers in shock, some in disbelief... But mainly a lot in curiosity. Obviously something provoked Microsoft, a vehemently anti-Open source entity, to Open Source .NET, but what was it? By looking into the technical, political, and commercial implications of what this means, their reasoning becomes obvious.
The announcement for the relicensing of most of the .NET stack came on April 3rd, 2014, which is exactly 5 days before the XPocolypse, Microsoft's termination of their most widely used, widely popular desktop operating system. They need to gain market leverage again, and no legal paradigm has risen to popularity quicker during XP's reign than Open Source. A lot has changed in the decade since XP, and now Microsoft is being forced to catch up to companies like Apple and Google, who learned far sooner than Microsoft that Open Source technologies have technical and managerial advantages over closed source development.
However, the motivation isn't all an act of kindness. Microsoft's watching its Empire be chipped away by community projects that recreate Microsoft functionality. The Mono project, for instance, was a (somewhat) successful attempt at an open source .NET. With Microsoft filling this niche, the only card that Mono has to play is cross-compatibility, a technical feat not far off from possibility with the .NET source code released today.
Let's follow this tangent a little bit more. This isn't a one-off thing. Open source code is part of the new .NET foundation goals. What could the future hold for other community projects similar to Mono, like, say, MingW, if the source for other development tools gets released?
Is it a positive thing that Microsoft is moving into Open Source? Absolutely. But do not confuse business strategy with kindness, for the motives for the move are clouded by the drive for market dominance in a post-XP era.
That's the response from an IRC channel chatter after the news came out about Microsoft's .NET. It left a lot of developers in shock, some in disbelief... But mainly a lot in curiosity. Obviously something provoked Microsoft, a vehemently anti-Open source entity, to Open Source .NET, but what was it? By looking into the technical, political, and commercial implications of what this means, their reasoning becomes obvious.
The announcement for the relicensing of most of the .NET stack came on April 3rd, 2014, which is exactly 5 days before the XPocolypse, Microsoft's termination of their most widely used, widely popular desktop operating system. They need to gain market leverage again, and no legal paradigm has risen to popularity quicker during XP's reign than Open Source. A lot has changed in the decade since XP, and now Microsoft is being forced to catch up to companies like Apple and Google, who learned far sooner than Microsoft that Open Source technologies have technical and managerial advantages over closed source development.
However, the motivation isn't all an act of kindness. Microsoft's watching its Empire be chipped away by community projects that recreate Microsoft functionality. The Mono project, for instance, was a (somewhat) successful attempt at an open source .NET. With Microsoft filling this niche, the only card that Mono has to play is cross-compatibility, a technical feat not far off from possibility with the .NET source code released today.
Let's follow this tangent a little bit more. This isn't a one-off thing. Open source code is part of the new .NET foundation goals. What could the future hold for other community projects similar to Mono, like, say, MingW, if the source for other development tools gets released?
Is it a positive thing that Microsoft is moving into Open Source? Absolutely. But do not confuse business strategy with kindness, for the motives for the move are clouded by the drive for market dominance in a post-XP era.
Microsoft Open Sources Key parts of .NET Stack
git clone http://www.microsoft.com/git/windows
If you've ever dreampt about being able to type that command, your dream got a little bit closer today. During Microsoft's conference today (April 3rd 2014), Microsoft announced that Roselyn, the codename of the .NET Compiler Platform, would be open sourced. To put this into layman's terms: One of the most widely developed platforms in the world now mostly uses permissive licensing. It's more than a gift, it's straight out of left field. But what does this mean for developers, consumers, and the company?
It means an increase in quality for sure. The advantages of open sourcing code as a commercial strategy have been well documented in Eric S. Raymond's "The Magic Cauldron", and now Microsoft is finally learning to follow his advice two decades after the fact. Bugs will be fixed sooner, the number of auditors for the source will skyrocket, reducing the chance of vulnerabilities and malfunctions, and innovations can be made at a much more accelerated pace than previously possible.
So, you're aware of the benefits of Microsoft's decision and want to jump in? Getting the sources for .NET (a line I thought I'd never write on this blog) is as simple a process of just typing this line:
If you've ever dreampt about being able to type that command, your dream got a little bit closer today. During Microsoft's conference today (April 3rd 2014), Microsoft announced that Roselyn, the codename of the .NET Compiler Platform, would be open sourced. To put this into layman's terms: One of the most widely developed platforms in the world now mostly uses permissive licensing. It's more than a gift, it's straight out of left field. But what does this mean for developers, consumers, and the company?
It means an increase in quality for sure. The advantages of open sourcing code as a commercial strategy have been well documented in Eric S. Raymond's "The Magic Cauldron", and now Microsoft is finally learning to follow his advice two decades after the fact. Bugs will be fixed sooner, the number of auditors for the source will skyrocket, reducing the chance of vulnerabilities and malfunctions, and innovations can be made at a much more accelerated pace than previously possible.
So, you're aware of the benefits of Microsoft's decision and want to jump in? Getting the sources for .NET (a line I thought I'd never write on this blog) is as simple a process of just typing this line:
git clone https://git01.codeplex.com/roslynIt's hosted on Codeplex, but it wouldn't be surprising to see a github mirror appear within the week.
Wednesday, April 2, 2014
ReactOS Community Edition Announced
ReactOS is a clean-room reverse engineering of NT, Microsoft's kernel used in Windows. Through binary compatibility, ReactOS is attempting to create a Free (libre) operating system compatible with Windows, in particular Windows XP. After Microsoft announced the impending EOL for XP later this month, ReactOS kicked off their new marketing campaign for this community edition.
The different between the version of ReactOS that already exists and the community edition is a democratic voting system for compatibility. In a system where compatibility is the selling point, not just an added bonus, being able to gauge what your users want finagled into compatibility is of the utmost priority in the project, so this is a step in the right direction for ReactOS, in my opinion. However, I was in a way disappointed that no new technology was being brought along with this release. Hopefully the community addition is a launchpad for the more daring works that the ReactOS devs have in the work, like their proposed Thorium Core Commercial Web OS.
What does this mean for Windows XP users, who will surely be looking for a new home this April? Probably not much, despite what most of us would like to believe. Even with the hype clock, the proof of concept, and the promise for community input, the interest in ReactOS is projected to be at an all time low according to Google Analytics.
This is an example of good marketing from the ReactOS community, and fantastic work from the ReactOS devs. I'm sure that most of us are downloading qemu or Virtualbox this very moment, priming ourselves to give the new (R)evolution project a chance. Whether or not (R)evolution works now is irrelevant. The beauty in the project is the hope that in the near future, having to dual-boot an operating system with ethical and monetary implications will be a thing of the past.
Monday, March 31, 2014
Getting started with Herbstluftwm
It's no secret that I am a fan of tiling window managers. When my workflow consists of having 5+ Windows open in one workpspace, tiling is the easiest and most logical way to do it. So, what distinguishes herbstluftwm from other Window Managers, and how does one get started with it?
What Herbstluftwm does
Herbstluftwm is a manual tiling window manager. Which means, by default it ships with one pane where windows will be placed.
When you open windows in the workspace, they will maximize the space in this master pane. How they do so depends on what kind of layout you choose.
However, this is not the way that herbstluftwm is meant to be used. Manual tiling is about splitting your windows into sub-panes, like a binary tree.
Each pane essentially becomes a new herbstluftwm ready to hold windows or be split down even further.
You're probably saying to yourself "Well, that sounds top! How can I get started?"
The answer is a bit more complex than I would like to admit.
Setting up Herbstluftwm
Herbstluftwm works in a peculiar way, but a way that I personally find to be one of the best design patterns on Unix. Herbstluftwm is configured completely by a client, called herbstclient, that can be called from the command line. To facilitate consistency across sessions, herbstluftwm allows a regular BASH script to be written to bind keys, run autostart programs, etc. This is usually placed in ~/.config/herbstluftwm/autostart. To launch herbstluftwm, just make sure that your ~/.xinitrc contains "herbstluftwm -c ~/.config/herbstluftwm".-c is the flag to set the configuration file.
My autostart script looks like this: https://gist.github.com/anonymous/9893756
Now, barring the wallpaper I use, and a couple of programs that are not installed on many systems by default, it works very well. Windows+v for a horizontal split, Windows+h for a vertical one, etc. Whether or not you can even use this exact configuration, it's a good launching point for your very own herbstluftwm experience.
What Herbstluftwm does
Herbstluftwm is a manual tiling window manager. Which means, by default it ships with one pane where windows will be placed.
However, this is not the way that herbstluftwm is meant to be used. Manual tiling is about splitting your windows into sub-panes, like a binary tree.
You're probably saying to yourself "Well, that sounds top! How can I get started?"
The answer is a bit more complex than I would like to admit.
Setting up Herbstluftwm
Herbstluftwm works in a peculiar way, but a way that I personally find to be one of the best design patterns on Unix. Herbstluftwm is configured completely by a client, called herbstclient, that can be called from the command line. To facilitate consistency across sessions, herbstluftwm allows a regular BASH script to be written to bind keys, run autostart programs, etc. This is usually placed in ~/.config/herbstluftwm/autostart. To launch herbstluftwm, just make sure that your ~/.xinitrc contains "herbstluftwm -c ~/.config/herbstluftwm".-c is the flag to set the configuration file.
My autostart script looks like this: https://gist.github.com/anonymous/9893756
Now, barring the wallpaper I use, and a couple of programs that are not installed on many systems by default, it works very well. Windows+v for a horizontal split, Windows+h for a vertical one, etc. Whether or not you can even use this exact configuration, it's a good launching point for your very own herbstluftwm experience.
Sunday, March 30, 2014
Rust Language Review / Predicitons
Rust is a new systems-level programming language with inspiration from Haskell, C++, and D backed by Mozilla. It has been hailed as everything from "language of the future" to "hobbyist plaything". As someone equally interested in hobbies and viability, I decided to learn Rust, with great help from #rust on irc.mozilla.org.
However, my learning experience was anything but smooth. Let me preface this by saying that I am familiar with 10+ programming languages, with at least two from every paradigm (barring logical). It obvious what snippets of other languages rust takes from, but even then it was impossible for me to write even the simplest code without asking for help in IRC.
As an educational experiment, I was trying to implement "car", a function that returns the first element of a list.
Here is an implementation of that in, say, D:
T car(T)(T[] a){ return a[0]; }
Or Haskell:
car (x:xs) = x
But what about Rust?
fn car<'a,T>(v: &'a [T]) -> &'a T { return & 'a v[0];}
Oh boy.
For a modern language, that type of syntax is frankly unacceptable. This is the part where the rust users will come out of the woodwork with their pitchforks, saying "You can't criticize it once you just started! You can't see the beauty in it!" The harsh fact of the matter is, if any beginner has to type THAT monstrosity, for something that is shorter in even Java, the language won't find wide success.
What the Rust syntax gives it is power and correctness, and those are noble goals in a programming language. They're standing on the shoulders of giants (namely Haskell) with their type system, and extending it with lifetimes, eliminating a slew of errors. But the end result is a correct program that nobody particularly wants to maintain or continue developing. It's not comfortable to work in, but it's pretty on a deeper level. So, here's the conundrum of Rust. How much usability do you want to sacrifice for functionality?
My guess is that Rust will not replace C++, but userland C in many cases. Like C, rust is a paradigm in and of itself, and it serves the same purpose that C does, but safer. But I've seen Java programmers who don't know what an interface is, Lisp programmers who don't use macros, and Haskell players ignorant to typeclasses. The beauty that makes Rust the low-level userland programming language of the future will go right over the heads of most of its prospective users.
However, my learning experience was anything but smooth. Let me preface this by saying that I am familiar with 10+ programming languages, with at least two from every paradigm (barring logical). It obvious what snippets of other languages rust takes from, but even then it was impossible for me to write even the simplest code without asking for help in IRC.
As an educational experiment, I was trying to implement "car", a function that returns the first element of a list.
Here is an implementation of that in, say, D:
T car(T)(T[] a){ return a[0]; }
Or Haskell:
car (x:xs) = x
But what about Rust?
fn car<'a,T>(v: &'a [T]) -> &'a T { return & 'a v[0];}
Oh boy.
For a modern language, that type of syntax is frankly unacceptable. This is the part where the rust users will come out of the woodwork with their pitchforks, saying "You can't criticize it once you just started! You can't see the beauty in it!" The harsh fact of the matter is, if any beginner has to type THAT monstrosity, for something that is shorter in even Java, the language won't find wide success.
What the Rust syntax gives it is power and correctness, and those are noble goals in a programming language. They're standing on the shoulders of giants (namely Haskell) with their type system, and extending it with lifetimes, eliminating a slew of errors. But the end result is a correct program that nobody particularly wants to maintain or continue developing. It's not comfortable to work in, but it's pretty on a deeper level. So, here's the conundrum of Rust. How much usability do you want to sacrifice for functionality?
My guess is that Rust will not replace C++, but userland C in many cases. Like C, rust is a paradigm in and of itself, and it serves the same purpose that C does, but safer. But I've seen Java programmers who don't know what an interface is, Lisp programmers who don't use macros, and Haskell players ignorant to typeclasses. The beauty that makes Rust the low-level userland programming language of the future will go right over the heads of most of its prospective users.
Monday, January 20, 2014
How to use Haddock
Haddock, Haskell's documentation generator of choice, is the de-facto means of communicating the purpose of a module or function in the Haskell ecosystem. Despite this, it not included in Learn you a Haskell, and is only mentioned in passing in Real World Haskell. While those books don't make mention of it, it's as crucial to be able to write Haddock as it is to be able to write Javadoc, or doxygen. Because GHC is exposed as a library, Haddock is able to determine the type signature of your library's functions by parsing its code. So, what is left up to the programmer?
Documenting a Module
The first step is to document the module you're working on. In the picture shown, the chunk of information Portability, Stability, and Maintainer all come from the Module documentation, as do the Module, Copyright, and License fields. This is generated by a multi-line comment with the special Haddock character, "|", in the front position. That's a pipe, not a 1 or l.
The multi-line comment to generate that information in the document is:
Documenting a Module
The first step is to document the module you're working on. In the picture shown, the chunk of information Portability, Stability, and Maintainer all come from the Module documentation, as do the Module, Copyright, and License fields. This is generated by a multi-line comment with the special Haddock character, "|", in the front position. That's a pipe, not a 1 or l.The multi-line comment to generate that information in the document is:
{- |
Module : OpenSSL.Digest.ByteString
Copyright : (c) 2010 by Peter Simons
License : BSD3
Maintainer : simons@cryp.to
Stability : provisional
Portability : portable
Wrappers for "OpenSSL.Digest" that supports 'ByteString'.
-}
The fields are on the left side, separated by a colon and the r-value for the field. Stability and Portability are subjective. If your API for the module is subject to change frequently, or you know that it will change in the foreseeable future, mark this field as 'Unstable'. If your module depends on other Haskell code not included in a default ghc installation, a Foreign Function Interface, or a feature only found in a very recent or very old version of ghc, mark your module as Non-portable, and possibly give a reason why. For instance, in one of my modules, I have the line "Portability : Portable (standalone - ghc)", meaning that it does not rely on any other modules within its own namespace, nor any module not included in a default ghc installation.
Documenting your Function, Typeclass, Method, Instance, etc.
This is the last type of documentation you need to add to your Haskell module to bring its documentation up to speed. Single-line comments above functions, usually separated by a newline from the function's type signature (if included), and preceded immediately after the comment (--) by a pipe (|), are Haddock comments.
Take this trivial function:
rev :: [a] -> [a]
rev [] = []
rev (x:xs) = rev xs ++ [x]
ghc already knows the type signature is [a] -> [a], because you told it. For good measure, it'd know even if you didn't; type inference. Because of this, there's no need to talk about the types of data a function can receive. You need only discuss the purpose of the function. The function rewritten with a haddock comment:
-- | Reverses a finite list.
rev :: [a] -> [a]rev [] = []rev (x:xs) = rev xs ++ [x]
Conclusion
Now you see that it's really super easy (and, dare I say, fun?) to document your Haskell code. However, some people believe that "Good code speaks for itself", and that that idiom holds especially true for ML derivatives with type signatures. In fact, superfluous comments will actually clutter your code more than anything. What's the etiquette for commenting?
I will leave that "as an exercise for the reader", as many Haskell bloggers often do for various topics. My personal preference is to always include Haddock comments in code that will be parsed and documented for me anyway. If you maintain a package on Hackage, the popular repository for Haskell, put a bit of Haddock in your code, even for self-explanatory functions. If you're just going to upload it to github and forget about it? There's no point in using Haddock, unless you're anal about good documentation. Use good judgement on when and when not to use this powerful tool.
Sunday, January 19, 2014
Using Monads in Haskell
Haskell is a bit of a quirky language, to say the least. One of the most talked about features of Haskell is the monad, which is a minimal context that essentially "wraps" a value. Monads are not a part of Haskell itself, but rather a ubiquitous use of the type system. All monads must obey the three Monadic laws of Left Identity, Right Identity, and Associativity. Academics can argue these laws all day, and with good reason, but what about a real programmer more interested in getting real work done than writing proofs for their code? This is a quick run-down to teach those types how they can use monads in their code.
Do Notation
The main way to handle monads is do-notation. It can "unwrap" monads easily, with do and arrows. Here is an example with the IO monad, inside of the main function.
main = do
fileHandle <- openFile "test.txt" ReadMode
x <- hGetContents fileHandle
let x-lines = lines x
return ()
In this block of code, the Handle is "extracted" from the IO Monad in the second line of code. <- will take a Monad, and bind its wrapped value to a named value. Note that this is still lazily evaluated. Afterwards, a new String is taken from an IO (String) and put into x. The next important line, "return ()", uses one of monad's core methods. This is because main must return an IO monad. However, you can see that it is inefficient to bind so many variables. So, here is how to use another one of Monad's methods, >>=, to chain actions together.
main = do
xlines <- openFile "test.txt" ReadMode >>= hGetContents
This is such an essential usage of Monads that >>= is the unofficial symbol representing Haskell. As you can see, the result of the openFile command is "pushed" into hGetContents. It's important to note that a monad is going into hGetContents, and a monad is coming out. <- is what unbinds it.
Functors and Monads
So, you still have to use the <- to "de-monad" the monad you get before it can be used, right? Wrong. There is a typeclass called fmap, which is generally applicable to everything. One of the monad laws dictates the behavior of fmap, so it damn well better be able to manipulate our monads. Here is the program once again rewritten:
main = fmap putStrLn $ openFile "test.txt" ReadMode >>= hGetContents
Here, fmap is a function with the type signature of "String -> IO ()", applied to the result of hGetContents on the monad pushed into it by the openFile. fmap maps putStrLn over the results, and the IO is returned as a result. Nifty? Nifty.
Applicatives
So, the last piece of the puzzle is this: You have multiple monads, and you want to add the result of them without binding temporary variables. This can be done with Applicative Functors. They are like Functors, but with some added goodies. To use Applicative functors, include Control.Applicative and test out this chunk of code:
main = fmap putStrLn $ pure (++) <*> (openFile "test.txt" ReadMode >>= hGetContents) <*> (openFile "test2.txt" ReadMode >>= hGetContents)
Do Notation
The main way to handle monads is do-notation. It can "unwrap" monads easily, with do and arrows. Here is an example with the IO monad, inside of the main function.
main = do
fileHandle <- openFile "test.txt" ReadMode
x <- hGetContents fileHandle
let x-lines = lines x
return ()
In this block of code, the Handle is "extracted" from the IO Monad in the second line of code. <- will take a Monad, and bind its wrapped value to a named value. Note that this is still lazily evaluated. Afterwards, a new String is taken from an IO (String) and put into x. The next important line, "return ()", uses one of monad's core methods. This is because main must return an IO monad. However, you can see that it is inefficient to bind so many variables. So, here is how to use another one of Monad's methods, >>=, to chain actions together.
main = do
xlines <- openFile "test.txt" ReadMode >>= hGetContents
return ()
This is such an essential usage of Monads that >>= is the unofficial symbol representing Haskell. As you can see, the result of the openFile command is "pushed" into hGetContents. It's important to note that a monad is going into hGetContents, and a monad is coming out. <- is what unbinds it.
Functors and Monads
So, you still have to use the <- to "de-monad" the monad you get before it can be used, right? Wrong. There is a typeclass called fmap, which is generally applicable to everything. One of the monad laws dictates the behavior of fmap, so it damn well better be able to manipulate our monads. Here is the program once again rewritten:
main = fmap putStrLn $ openFile "test.txt" ReadMode >>= hGetContents
Here, fmap is a function with the type signature of "String -> IO ()", applied to the result of hGetContents on the monad pushed into it by the openFile. fmap maps putStrLn over the results, and the IO is returned as a result. Nifty? Nifty.
Applicatives
So, the last piece of the puzzle is this: You have multiple monads, and you want to add the result of them without binding temporary variables. This can be done with Applicative Functors. They are like Functors, but with some added goodies. To use Applicative functors, include Control.Applicative and test out this chunk of code:
main = fmap putStrLn $ pure (++) <*> (openFile "test.txt" ReadMode >>= hGetContents) <*> (openFile "test2.txt" ReadMode >>= hGetContents)
This will take the ++ function, turn it into one which can work with Applicatives, and then apply it partially over the <*> elements. If the function can already handle Applicatives, then <$> can be used instead.
In Conclusion
Monads were a tricky subject for me for a long time. Most of my programs look like my first chunk of code, where I did one monadic operation per line. However, learning to master Monads in Haskell to control side-effects and efficienty keep track of your state is of utmost importance in commanding the language. So go on, don't pick up that monad. Wear that >>= with pride.
Subscribe to:
Posts (Atom)