Latest articles on xrefactor.com

Linux Desktop Screenshots 2016

2016-12-31T04:20:07Z

Linux Desktop Screenshots 2016

In keeping with tradition, here is what I used in 2016:

Four years in a row, i3

2016 was the year of computing. Leading the charge, AlphaGo and TensorFlow are just the tip of the iceberg, with other breakthroughs in the field of machine learning, 2016 was the year to be remembered.

How to Use Mercurial as Git Front-end

2016-01-02T17:10:02Z

How to Use Mercurial as Git Front-end

In this document, I am going to show you how to use mercurial as a git front-end. This is about a mercurial extension called Hg-Git, if you are already using it, or not going to use mercurial to push and pull from a git server, then this guide is not for you.

Note

If you want to learn how to use mercurial, please check out the new mercurial book, it is free online.

Why Mercurial?

I hear you, why mercurial? Why, when seemingly open source projects are migrating to git en masse? Why, when git and to some extent Github had become the de facto tool-chain for OOS development? Why, when python itself is moving away from mercurial (actually, this document is a response to this decision)? Isn't it the DVCS flame war long gone and git is the declared winner? Isn't it mercurial no longer relevant, like bzr became long ago. This is 2016, not 2006 when both git and mercurial are barely one-year-old.

To begin answering these questions, I need to state my observation first, that the git dominance is not because of mercurial is a less capable contender, it is mostly because of celebrity endorsement (git was written by Linus Torvalds and used in Linux Kernel) and Github's dominance and social lock down.

Feature-wise, there is no clear winner between git and mercurial technically, in some scenarios git works better while in some cases mercurial works better. So, there is no evidence that mercurial is superior than git, why mercurial?

I am not going to get into details about these in this document, just pointing out that mercurial has some unique features that one may find useful and cannot be found in other alternatives, such as:

Specifically designed query languages revset and fileset for searching in history
Built-in web server for quick one-off pulling/pushing/reviewing session
Extension for large files
Extension Mercurial Queues (mq), like multi-level index (in git's parlance), the mq patches can also be put under revision control
Phase, a feature that provide fine-grained control about changesets' publicity, no more accidental push of secret, private changes
Mercurial are easy to customize, read scaling mercurial for a real world example
Some interesting ideas, like Changeset Evolution for safe sharing of history rewrites, most are experimental right now, though

Nothing is perfect, mercurial is no exception, besides the smaller market share, there is currently no plan to port the code base from python 2 to python 3 due to technical restriction. That being said, with those unique features and intuitive user interface, mercurial is a viable option even today.

I am a strong believer in "biodiversity and competition are good for a ecosystem", this is another reason that I keep using mercurial and promoting mercurial whenever possible, and the reason behind writing this document.

Okay, enough talk, so how do we use mercurial as a git client? You need an extension called Hg-Git.

Installing Hg-Git

Hg-Git can be installed as normal mercurial extension, please follow the instructions on the Hg-Git official site. Hg-Git might as well be able to be installed from your linux distribution's software repository directly.

Please make sure both extensions bookmarks and hggit are enabled afterward.

For example, with these lines in ~/.hgrc:

[extensions]
hgext.bookmarks =
hggit =

Talking to Git Server

When properly setup, you can use hg clone, hg push and hg pull against a git server as if it is serving mercurial repositories. Just remember the difference in uri schema, for example, to clone from one of my projects on github, using git:

git clone git@github.com:pyx/hymn.git

while using mercurial, the command will be:

hg clone git+ssh://git@github.com/pyx/hymn.git

Notice the difference in schema part git+ssh:// and the separator : between host and user directory became a /

You can simply hg push and hg pull from then on.

Caveat

Hg-Git keeps track of the changesets under the bookmark master, so any destructive changes, e.g hg strip or hg histedit involving master will be recorded and visible in git's history. To avoid this, deactivate bookmark master before applying any destructive changes.

For the same reason, only history up to the point of master will be pushed, and I suggest to first deactivate bookmark master while working on development branches, you are supposed to checkout a dev branch anyway, right?

It is so important that I have to mention again that, if you rewrite history involving bookmark master, Hg-Git will record the changes while mercurial will not, so things will get really messy if you forget about that. Please work on development branches with bookmark master deactivated, when you finish all the history rewriting and rebasing and the changes are ready to be published, then and only then can you checkout master and push the changes to a git server.

Mercurial use explicit files to track some metadata, such as .hgtags for tags, it is of no use to git, but it is there, and the sha-1 hash for the same changeset is different in mercurial and git because they have different strategies in calculating them, so keep that in mind.

Conclusion

With Hg-Git, one can use mercurial as a client for a git server, and publishes mercurial repositories as git repositories at the same time, without much work, this is how I managed to publish my open source projects to both Bitbucket (as mercurial repositories) and Github. To people who prefer mercurial like me, but are forced to use git, it is the best of both worlds.

Linux Desktop Screenshots 2015

2015-12-31T21:17:27Z

Linux Desktop Screenshots 2015

What I used in 2015:

Boring as always, that's the norm with tiling wm, still i3

Since perl 6 was released few days ago, I guess 2015 was the year of linux desktop, too. :)

R.I.P Ian Murdock

2015-12-30T23:19:05Z

R.I.P Ian Murdock

It was a shock to hear the news of the passing of Ian Murdock (1973-2015), the creator of Debian.

As the father of Debian, the second oldest GNU/Linux distribution that is still in widely used and in existence (the oldest being Slackware), Ian Murdock was a true pioneer, his great contribution to the Open Source Movement and in building a healthy open source community benefits us all and helped make the world a better place.

Debian is the first ever open source operating system I used, and am still using day-to-day, for over a decade. It is also the go-to distro for new installations whenever I do not need the flexibility of compiling from source. Like many others, I've learned a lot from the project, the community, and the people therein.

It is a tragic loss for his family and for our open source community, he will be terribly missed, may his soul rest in peace.

My sincere condolences.

The Frist Public Release of Hymn

2015-12-09T20:45:21Z

The Frist Public Release of Hymn

I am happy to announce the first public release of hymn, a new monad library for Hy and Python. In addition to implementing many common monad types, with the help of lisp macro, it is possible to write monadic code in do notation, like so (example in Reader Monad):

=> (require hymn.dsl)
=> (import [hymn.types.reader [lookup]])
=> ;; do notation with reader monad, lookup assumes the environment is subscriptable
=> (def r (do-monad [a (lookup 'a) b (lookup 'b)] (+ a b)))
=> ;; run reader monad r with environment
=> (.run r {'a 1 'b 2})
3

I also wrote some interesting examples with it, just check out the examples directory, to get a taste of it, here is the example that using writer monad for logging:

(import [hymn.dsl [tell]])

(require hymn.dsl)

(defn gcd [a b]
  (if (zero? b)
    (do-monad
      [_ (tell (.format "the result is: {}\n" (abs a)))]
      (abs a))
    (do-monad-m
      [_ (tell (.format "{} mod {} = {}\n" a b (% a b)))]
      (gcd b (% a b)))))

(defmain [&rest args]
  (if (-> args len (!= 3))
    (print "usage:" (get args 0) "number1 number2")
    (let [[a (int (get args 1))]
          [b (int (get args 2))]]
      (print "calculating the greatest common divisor of" a "and" b)
      (print (.execute (gcd a b))))))

And here is the state monad example, using monte carlo method to calculate pi:

(import
  [collections [Counter]]
  [time [time]]
  [hymn.dsl [get-state replicate set-state]])

(require hymn.dsl)

;;; Knuth!
(def a 6364136223846793005)
(def c 1442695040888963407)
(def m (** 2 64))

;;; linear congruential generator
(def random
  (do-monad
    [seed get-state
     _ (set-state (-> seed (* a) (+ c) (% m)))
     new-seed get-state]
    (/ new-seed m)))

(def random-point (do-monad [x random y random] (, x y)))

(defn points [seed]
  "stream of random points"
  (while true
    ;; NOTE:
    ;; limited by the maximum recursion depth, we take 150 points each time
    (setv [random-points seed] (.run (replicate 150 random-point) seed))
    (for [point random-points]
      (yield point))))

(defn monte-carlo [number-of-points]
  "use monte carlo method to calculate value of pi"
  (def samples (take number-of-points (points (int (time)))))
  (def result
    (Counter (genexpr (>= 1.0 (+ (** x 2) (** y 2))) [[x y] samples])))
  (-> result (get true) (/ number-of-points) (* 4)))

(defmain [&rest args]
  (if (-> args len (!= 2))
    (print "usage:" (get args 0) "number-of-points")
    (print "the estimate for pi =" (-> args (get 1) int monte-carlo))))

This should replace the older monad library.

Linux Desktop Screenshots 2014

2014-12-31T16:03:45Z

Linux Desktop Screenshots 2014

What I used in 2014:

Nothing changed, except wallpapers, i3

2048 in OCaml

2014-03-21T11:56:14Z

2048 in OCaml

A New Flappy Bird

Have you ever heard about a game called 2048? There are discussions about it everywhere recently, be it on Stack Overflow, hacker news, reddit, twitter, facebook, you name it. It even got its own wikipedia entry.

The gameplay is simple, you have a 4 x 4 grid with numbers, you can move all tiles in four directions, while moving, a couple adjacent tiles with same number will collide and be merged into a new tile with the number of their values added up, a new tile with number 2 or 4 will also appear randomly after each move, your goal is to come up with a tile with value 2048 (hence the name) before the game board is too crowded for new tile, in which case, you lose the game.

If you haven't already, please try to play it a few times, it's quite straightforward and fun to play, yet challenging and somewhat addictive. You will not regret, or you will, for it's such a time sink.

NIH Syndrome, anybody?

Do you know what's more fun to do? Dogfooding, that's correct, write your own version of 2048, because that's fun and doable in a few hours. This is why all the cool kids in town were busy reimplementing 2048 using their favorite programming languages lately.

In just a few days, I have seen many implementations and variants, in varying languages and technologies: javascript (same as the original one), C, C++, java, C#, python, ruby, Objective-C, haskell, etc., and the number keeps growing.

It seems like this thing is becoming the new Hello world, just like "roll-your-own-static-website-generator" was last year, and "write-your-own-dynamic-blog-engine-with-a-framework" a few years before that.

What I found interesting is, the game can make good use of monad, each game move can be implemented as monadic function and be chained, composed, transformed as such. So, with that pattern, I wrote my own version of 2048, in OCaml.

Monadic WTF?

For one thing, monad yields beautiful code, for example, the following code snippet from my version shows how to initialize a game board and then place two tiles randomly to begin with:

let init x y =
  Random.self_init ();
  let board = Board.init x y in
  let open Infix in
  playing board >>= spawn >>= spawn

Notice how I implemented this action "placing a new tile randomly", as a monadic function (spawn) and how actions are chained with bind operator (>>=), magnificent, isn't it?.

You don't have to be able to read OCaml to agree.

The following shows how to handle move:

let move m game =
  let open Infix in
  let action = match m with
  | Up -> Board.move_up
  | Down -> Board.move_down
  | Left -> Board.move_left
  | Right -> Board.move_right
  in Monad.lift action game >>= spawn

See how we combine "making a move" (Monad.lift action game) with "placing a new tile" (spawn) then "checking for game winning/losing condition" (check) automatically by bind function, as follows:

let bind game action =
  match game with
  | Playing, board ->
      begin match action board with
      | Playing, board' -> check board'
      | game -> game
      end
  | game -> game

let ( >>= ) = Monad.bind

As you can see, the bind function is smart enough to stop taking moves when the game has finished. That is, if we are trying to play an action on a finished game, nothing will happen but passing the game object through the chain as it is, without explicit testing in each action function. Talk about avoiding boilerplate code again.

Hint

More specifically, the game-board object is modelled as a Writer Monad, tuple of (grid, step-count, score), while the game object is modelled as something similar to the Maybe Monad, tuple of (game-state, game-board). Each game action takes a game-board and yields, as after the action taken, the game-board in which contains updated step-count and score. The bind function takes responsibility for chaining game actions in turn, accumulating step-count and score, and updating game-state afterward. By freeing from these burden, we can have cleaner, less repetitive code in action functions.

Language support of automatic currying and infix operator defining make the above pattern possible. This is why I chose an ML family language (OCaml) for this project. Why not haskell then, you asked? As much as I love haskell, I picked OCaml because there are at least two implementations in haskell as of today already, besides, OCaml comes with cross-platform graphics library, so without external dependency, making a GUI is possible, here is how it looks:

2048 screenshot

Have time to spare? Get the source from Bitbucket or Github, and have fun.

Linux Desktop Screenshots 2013

2013-12-31T01:14:23Z

Linux Desktop Screenshots 2013

What I used in 2013:

Same old thing, i3

Introducing Simple - an Ena Theme

2013-07-07T13:30:19Z

Introducing Simple - an Ena Theme

Simple is the default theme that comes with Ena. The following shows how different elements are styled by Simple.

Markup

Emphasis

This is *emphasized text*.

This is emphasized text.

Strong Emphasis

This is **strong text**.

This is strong text.

Inline Code

This is :code:`inline code`.

This is inline code.

Hyperlinks

Hyperlinks look like this: https://en.wikipedia.org/wiki/ReStructuredText

Special Admonitions

All special admonitions supported by reStructuredText are styled, the following shows each of them, with corresponding reStructuredText code:

note

Note

This is note

.. note::

  This is note

warning

Warning

This is warning

.. warning::

  This is warning

caution

Caution!

This is caution

.. caution::

  This is caution

attention

Attention!

This is attention

.. attention::

  This is attention

danger

!DANGER!

This is danger

.. danger::

  This is danger

error

Error

This is error

.. error::

  This is error

hint

Hint

This is hint

.. hint::

  This is hint

important

Important

This is important

.. important::

  This is important

tip

Tip

This is tip

.. tip::

  This is tip

admonition

This is admonition

Content here.

.. admonition:: This is admonition

  Content here.

Images

Images come in two flavors, image and figure:

image

In reStructuredText, an image can be defined with image directive:

.. image:: picture.png

It looks like this:

By default, images will be scaled to full width of the containing elements with a border in red, if that is not what you want, add :class: as-is to it:

.. image:: picture.png
  :class: as-is

figure

figure is an image with an optional caption and an optional legend:

.. figure:: picture.png

  This is the caption

  This is the legend.

The logo of xrefactor.com

I made it with GIMP.

:class: as-is can be used here as well:

The logo of xrefactor.com

I made it with GIMP.

Body Elements

code

Source code blocks can be defined by:

.. code:: c

  #include <stdio.h>

  int main(int argc, char *argv[])
  {
      printf("%s\n", "Hello, world!");
      (void)argc;
      (void)argv;
      return 0;
  }

Calculating the Maximum, Minimum and Average of Three Numbers

2013-07-03T20:26:23Z

Calculating the Maximum, Minimum and Average of Three Numbers

The title says it all. As always, I love to answer those homework questions with obfuscated solutions, for that is unsuitable to hand in those solutions.

A simple way to make a solution to entry-level question like this one harder to understand, is leveraging the fact that functions are first-class in python, so basically logic and I/O operations, almost everything we need here can be stuffed inside a single expression, like this:

[f(n) for f, n in zip((max, min, lambda s: float(sum(s))/len(s)), ([list(map(int, map(raw_input, ':::')))]*3))]

This is the Python 2 version, for Python 3, substitute raw_input with input.

It works like so:

>>> [f(n) for f, n in zip((max, min, lambda s: float(sum(s))/len(s)), ([list(map(int, map(raw_input, ':::')))]*3))]
:1
:2
:3
[3, 1, 2.0]

For extra fun, I use the number of : (Colon) to control how many numbers can be accepted, i.e, for six numbers instead of three, change ':::' to '::::::':

>>> [f(n) for f, n in zip((max, min, lambda s: float(sum(s))/len(s)), ([list(map(int, map(raw_input, '::::::')))]*3))]
:12
:34
:56
:78
:90
:42
[90, 12, 52.0]

Because of the incompatible differences between Python 2 and Python 3, it can be a little bit shorter if I am only targeting specific branch of Python.

In Python 2, map returns a list, so explicit list conversion is not needed:

[f(n) for f, n in zip((max, min, lambda s: float(sum(s))/len(s)), ([map(int, map(raw_input, ':::'))]*3))]

On the other hand, division operator returns floating-point numbers by default in Python 3, float function call is no longer necessary:

[f(n) for f, n in zip((max, min, lambda s: sum(s)/len(s)), ([list(map(int, map(input, ':::')))]*3))]