Tutorial

F#, Tutorial

As I’ve been thinking more about F#, I began to wonder how certain methods in the F# stack work, so I decided to implement F#’s List.filter method.

For those of you who aren’t familiar, List.Filter takes a function that returns true or false and a list of values. The result of the call is all values that fulfill the fuction.

For example, if we wanted to keep just the even numbers in our list, then the following would accomplish that goal.

Now that we know the problem, how would we begin to implement? First, we need to define a function called filter:

However, to match the signature for List.filter, it needs to take a function that maps integers to bools and the list of values to work on

Now that we have the signature, let’s add some logic to match on the list of values. When working with lists, there are two possibilities, an empty list and a non-empty list. Let’s first explore the empty list option.

In the case of an empty list of values, then it doesn’t matter what the func parameter does, there are no possible results, so we should return an empty list for the result.

Now that we’ve handled the empty list, let’s explore the non-empty list scenario. In this branch, the list must have a head and a tail, so we can deconstruct the list to follow that pattern.

Now that we’ve deconstructed the list, we can now use the func parameter with the head element. If the value satisfies the func parameter, then we want to add the head element to the list of results and continue processing the rest of the list. To do that, we can use recursion to call back into filter with the same func parameter and the rest of the list:

At this point, we need to handle the case where the head element does not satisfy the func parameter. In this case, we should not add the element to the list of results and we should let filter continue the work

By handling the base case first (an empty list), filter can focus on the current element in the list (head) and then recurse to process the rest of the list. This solution works, but we can make this better by removing the type annotations. Interestingly enough, we don’t care if we’re working with integers, strings, or whatever. Just as long as the function takes some type and returns bool and the list of values matches the same type as the func parameter, it works. So then we end up with the following:

In general, when working with lists, I tend to start by matching the list with either an empty list or non-empty. From there, I’ve got my base case, so I can focus on the implementation for the first element. After performing the work for the first element, I can then recurse to the next element.

Tutorial

As a follow up to my Basic’s post of Source Control, I’m going to show you how to setup Mercurial (Hg) for source control. First, I’m going to show you how to install Mercurial on your workstation. Next, we’re going to set up a central repository using Bitbucket. Afterwards, we’re going to go over the major workflows when working with Mercurial. To wrap up this tutorial, I’ve included some additional resources that helped me understand Mercurial when I first started using it.

Installing Mercurial

Installing Mercurial is very easy, just click here to download the installer for TortoiseHg for Windows. However, if you’re running Mac, the workflow is going to be a little more complicated.

  1. Download Mercurial from here (it will be a ZIP file)
  2. Expand the ZIP file and run the MPKG file to install
  3. Follow the prompts to complete the installation
  4. After installation, open the command prompt and enter the following: hg –version (should see version information
  5. Next, you need to check if there’s a .hgrc file by entering: ls ~/.hgrc
  6. If there isn’t, create it by using touch: touch ~/.hgrc
  7. After creating, open it using your favorite text editor
  8. In the text editor, enter the following: username = Name To Appear <email address>
  9. Save and close the file
  10. Congratulations, you now have Mercurial on your workstation.

Working with Mercurial

When using Mercurial, you have two options: you can use the UI (TortoiseHg for Windows or SourceTree for Mac), or you can use the command prompt. For this tutorial, I’m going to show you how to work with Mercurial using the command prompt. Not only is it just as easy as the UI, but if you’re like me and use both Windows and Mac for development, it’s nice to have one tool that behaves the same on both environments.

Using Bitbucket to Host Your Central Repository

Why Use Bitbucket?

As part of using any source control, there still needs to be a server to host the central repository. When it comes to setting a server, you could setup your own server, use the command “hg serve” to activate a lightweight server, or you could use Bitbucket. Each of these options have merit depending on your situation, but my go-to solution is to use Bitbucket. Bitbucket is essentially a server that hosts repositories for their users (similar to GitHub) but unlike GitHub, Bitbucket supports both Git and Mercurial for source control and offers many cool features like unlimited repositories, providing a wiki and bug tracking capabilities.

Great, since we’ve decided to use Bitbucket to host our central repository, why don’t we go ahead and set that up now?

Setting up a Central Repository

  1. Create an account for Bitbucket and login
  2. After logging in, you should be at the Dashboard, choose Create Repository
  3. Next, you should see a dialog for Creating a New Repository. For this example, let’s call the repo “Simple Repo”
  4. Set the Repository type to Mercurial and click ‘Create Repository’
  5. After creating the repository, you’ll see an option for adding code, choose the “I’m starting from scratch option’
  6. Follow the steps for creating a directory and copy the “hg clone” command to your command prompt
    1. For this example, I created C:\Dev\ to use for development
  7. After running the “hg clone” command, you may be prompted for your password.
  8. If everything works, you should see a folder in the directory you created called “simple-repo”
    1. For this example, in C:\Dev\, I would see a folder called “simple-repo”
  9. Congratulations, you’ve successfully created your first repository on Bitbucket and have copied it your workstation.

Time To Start Developing

Great, you have this empty repository, but it’s time to start developing. While developing software, your workflow is going to look a lot like this:

  1. Add files / Modify files
  2. At certain intervals, committing these changes to your local repository
  3. If necessary, pull latest changes, update local repository, and merge
  4. Commit any outstanding changes to the local repository
  5. Repeat steps 1 through 4 until you’re ready to share your changes with the rest of the team.
  6. Push changes to the central repository
  7. Start from Step 1

Adding Files

An empty repository is nice and all, but if we’re going to get anything done, we need to add some files to the repository. It’s easy to add files to Mercurial using the command prompt.

  1. Create a file (I called mine Grocery_List.txt)
  2. Move the file to the repository folder
    1. For this example -> C:\Dev\simple-repo
  3. In the command prompt, navigate to your local repository and run the “hg status” command
  4. You should see a question mark “?” followed by the name of the file you created.

So what’s the deal with the question mark and what does the “hg status” command do? “hg status” provides a way to see what changes have been made to your local repository since the last push. Since we have never performed a push, it’s letting us know that there is a file in the repository called Grocery_List.txt and that it’s not being tracked by Mercurial (hence the “?”). Other options include “A” (for files that were newly created and added), “M” (for files that have been modified),  and “R” (for files that Mercurial has removed). There are other symbols, but these are the more common symbols to see.

Now that we have this file, we need to tell Mercurial to track this file. In order for Mercurial to track the file, we need to add the file to the repository by using the “hg add” command. This command is pretty simple, just enter ‘hg add Grocery_List.txt’ and Mercurial will add the file to the local repository. When working with the “hg add” command here are some slick tricks to use when adding files

  • hg add (adds every file in every folder for the repository to track)
  • hg add ‘NameOfFile’ (adds just the file with the name)
  • hg add *.txt (adds all .txt files in the current directory)

After adding Grocery_List.txt to the local repository, if we run the “hg status” command, we’ll see that Grocery_List.txt now has a new symbol “A”.

Committing Files

After making changes to the repository (adding files), it’s time to commit these changes to our local repository. In Mercurial, to commit changes to the local repository, we need to use the “hg commit” command. After using this command, a text editor will appear. All we need to do is to enter a comment about what we changed. For this example, I’m going to write that is my initial commit and then I’m going to save the text document. Gotcha: If you don’t save the text file, then the “hg commit” command fails. It forces the user to enter something for a comment.

After committing this change, if we were to run the “hg status” command, you’ll get a message saying that there aren’t any changes. But wait a minute, we just committed changes to our local repository, not the central repository, so why don’t we have changes? It’s really easy, it’s because the “hg status” command only looks for changes based off what our latest local repository has. Since we just committed changes to our local repository, “hg status” return nothing.

Making and Reviewing Changes

Alright, we’ve committed our first file. We’re done now right? Not quite, as part of developing software, you’re going to be making changes all over the place. In this regard, we’re going to explore how Mercurial reacts to files that have changed and how we can review what changes we’ve made to a file.

To begin, let’s open Grocery_List.txt and make some changes. In this example, I’m going to add some items for me to pick up at the store. After saving your changes, run the “hg status” command. This time you should see Grocery_List.txt is listed with a new symbol ‘M’. This means that (M)odifications have been made to the document. To see what has changed, you can use the “hg diff” command to see what changes have been made to the file between revisions. The default behavior is to compare what changes have been made since the last commit to the local repository.

Using the “hg diff” command is great for reviewing what changes have been made between commits of the local repository (if you’re like me and don’t keep track of all the things you change between change sets, then the “hg diff” command is a lifesaver). Like the “hg add” command, there are a number of shortcuts that can be used to diff on certain files and options to diff files between revisions.

After making the changes and ensuring that Grocery_List.txt has been marked for modifications, let’s go ahead and commit that change using the “hg commit” command.  Congratulations, you just finished making some changes to your local repository and now it’s time to start pushing those changes to the rest of your team.

Pushing Changes

Great, so you’ve been making changes to your local repository, but now it’s time to push these changes to the rest of your team. Like most Mercurial commands, pushing changes is pretty simple, just use the “hg push” command. This will push each change in the local repository back to the central repository for your team to access.

  1. In the command prompt, navigate to your local repository (C:\Dev\simple-repo)
  2. Type “hg push”
  3. You may be prompted for a password, enter it here
  4. A message will be printed showing what files have been added and the number of change sets.

My Push failed, what’s up?

When you’re about to push changes to the central repository, the push will fail if you don’t have the latest copy of code. I like to think of this as a fail safe so you don’t accidentally commit old code or code that depends on other files that have since changed. If this happens, see below on how to pull and merge changes.

Pulling and Merging Changes

It’s great that you finally made changes to the central repository, however, as development continues, you’re not the only developer making changes. A fair question is how do I know if I have the latest source code? And if I don’t have the latest source code, how can I grab the latest without losing my changes?

Thanks to the Mercurial command “hg pull”, grabbing the latest changes is a breeze. Navigate to your local repository via command prompt and enter “hg pull”. This command will grab the latest source code from the central repository. However, the “hg pull” command doesn’t automatically update your local repository. You will need to run the “hg update” command to update to the latest version.

Sometimes, running the “hg pull” command will give you a message about multiple heads. All this means is that there are you don’t have all the changes and that some of the files you’ve changed have also been modified. Mercurial is very helpful when it tells you use “hg merge” to merge the files. The “hg merge” command takes your copy of the file and merges it with the latest version. If there are no conflicts, then the merge works and it’s up to you to verify that the software is behaving correctly.

However, merging isn’t always that easy. For example, let’s say that I modified Grocery_List.txt so that it says 2 dozen eggs. However, if before I push my changes, another dev modified the file to say 2 pounds of bacon, then that will cause a legitimate conflict that I would have to resolve it before I could commit my changes.

When handling conflicts, you get a spiffy interface (called KDiff3) that allows you to pick which version is correct (it even allows you to pick both versions, see here for a great example of handling merges). After handling the conflicts, you’re ready to commit your changes and attempt to push your changes back to the central repository.

Wrapping Things Up

Congratulations, you just finished setting up Mercurial for your source control! I know it’s a lot of information to take in, but trust me, you’re work is going to improve once you start using source control. In this tutorial, you’ve learned how to install Mercurial on your workstation, setup a central repository using Bitbucket and the major workflows of working with Mercurial to handle your source code (adding/modifying files, pulling and merging changes, and pushing your changes).

Now, there is still plenty to learn about Mercurial, but you now have the foundation from which to start experimenting with Mercurial.

Additional Resources