Humanizer helps turn "geeky strings, type names, enum fields, date, timespan values into a human friendly format"

Description

Today's project is one of those libraries that you might not know you need until you see it. Or it has parts you've invented yourself, but only so far as you needed them to solve a specific problem. When you see Mehdi Khalili's project you'll see what I mean...

Humanizer hit V1

Humanizer is a small framework that helps .Net developer turn their otherwise geeky strings, type names, enum fields, date, timespan values into a human friendly format plus a lot more.

Humanize Strings

String extensions are at the heart of this micro-framework. The foundation of this was set in the BDDfy framework where class names, method names and properties are turned into human readable sentences.

...

Dehumanize Strings

Much like you can humanize a computer friendly into human friendly string you can dehumanize a human friendly string into a computer friendly one:

...

Transform

There is a Transform method that supersedes LetterCasing, ApplyCase and Humanize overloads that accept LetterCasing. Transform method signature is as follows:

...

Humanize Enums

Calling ToString directly on enum members usually results in less than ideal output for users. The solution to this is usually to use DescriptionAttribute data annotation and then read that at runtime to get a more friendly output. That is a great solution; but more often than not we only need to put some space between words of an enum member - which is what String.Humanize() does well. For an enum like:

...

Humanize Dates

This is borrowed from StackOverFlow algorithm - although I had to apply some minor fixes on top of it. I am not going to bore you with all the examples as I am sure you know what this does: you basically give it an instance of DateTime and get back a string telling how far back in time that is:

...

Humanize TimeSpan

You can call Humanize on a TimeSpan to a get human friendly representation for it:

Inflector methods

There are also a few inflector methods:

  • Pluralize: pluralizes the provided input considering irregular words
  • Singularize: singularizes the provided input considering irregular words
  • Ordinalize: turns a number into an ordinal string used to denote the position in an ordered sequence such as 1st, 2nd, 3rd, 4th
  • Underscore: separates the input words with underscore
  • Dasherize: replaces underscores with dashes in the string

Fluent Date

Humanizer provides a fluent API to deal with DateTime and TimeSpan as follows:

...

Number to words

Humanizer can change numbers to words using the ToWords extension:

...

Number to ordinal words

This is kind of mixing ToWords with Ordinalize. You can call ToOrdinalWords on a number to get an ordinal representation of the number in words!! Let me show that with an example:

...

Integrate Humanizer with ASP.Net MVC

This is just a baseline and you can use this to simplify your day to day job. For example, in Asp.Net MVC we keep chucking Display attribute on ViewModel properties so HtmlHelper can generate correct labels for us; but, just like enums, in vast majority of cases we just need a space between the words in property name - so why not use string.Humanizer for that?!

You may find an Asp.Net MVC sample [in the code][5] that does that (although the project is excluded from the solution file to make the nuget package available for .Net 3.5 too).

This is achieved using a custom DataAnnotationsModelMetadataProvider I called HumanizerMetadataProvider. It is small enough to repeat here; so here we go:

...

How to contribute?

Your contribution to Humanizer would be very welcome. Just check out the list of issues. They should be relatively straightforward. We us GitHub flow for pull requests. So if you want to contribute, fork the repo, fix an issue and send a PR.

One area Humanizer could definitely use your help is localisation. Currently Humanizer supports French, Belgium, Spanish, Greek, German, Arabic, Russian and Romanian languages for Date.Humanize method. Humanizer could definitely do with more translations. We also need localization for TimeSpan.Humanize.

To add a translation, fork the repository if you haven't done yet, duplicate the resources.resx file, add your target locale code to the end (e.g. resources.ru.resx for Russian), translate the values to your language, commit, and send a pull request for it. Thanks.

Some languages have complex rules when it comes to dealing with numbers; for example, in Romanian "5 days" is "5 zile", while "24 days" is "24 de zile" and in Arabic "2 days" is "يومين" not "2 يوم". Obviously a normal resource file doesn't cut it in these cases as a more complex mapping is required. In cases like this in addition to creating a resource file you should also subclass DefaultFormatter in a class that represents your language; e.g. RomanianFormatter and then override the methods that need involve the complex rules. We think overriding the GetResourceKey method should be enough. To see how to do that check out RomanianFormatter and RussianFormatter to see an example. Then you return an instance of your class in the Configurator class in the FormatterFactories based on the current culture.

And what's cool is that the whole thing is OSS;

MehdiK / Humanizer

Humanizer is a small framework that helps .Net developer turn their otherwise geeky strings, type names, enum fields, date, timespan values into a human friendly format plus a lot more.

Installation

You can install Humanizer as a nuget package: Install-Package Humanizer

...

Here's a snap of the project;

image

And a touch that show's the project's maturity, the unit tests;

image

One thing to note about the Unit Tests, they are built with XUnit, so you'll need that if you want to execute them, which Nuget makes painfully easy. In most cases, all you'll need to do is Build the project and Nuget will get everything you need.

Here's some snaps of what you can do with this library...

image

image

image

image

image

image

image

image

image

And more... Now do you see what I mean about this being a library you might not of known you needed until you see it? I'll bet you're already thinking of ways to use this or problems this will help you solve...

 

Page Image Credit: Beth Scupham - Anatomy Trains

Tags:

.NET, C#, Coding4Fun

The Discussion

Comments closed

Comments have been closed since this content was published more than 30 days ago, but if you'd like to continue the conversation, please create a new thread in our Forums, or Contact Us and let us know.