Emacs Lisp: Find Java Sources

Confession: I really hope someone can tell me I'm doing this wrong. I can't believe there isn't an easier way.

I work with Clojure, in Emacs, almost every day. Navigating the source is usually fairly easy. If I want to navigate to a function definition, all I need to press is M-., and if I want to navigate back, M-, does the trick. This works for Clojure that I've written, as well as Clojure that lives in the libraries that I reference. That's fine the vast majority of the time, but occasionally I need to navigate to the Java source of some library I'm using. This is where I can't believe that no one else has solved this problem.* If I'm in a clj file, my cursor is on a Java class, I don't know of any way to easily navigate to the class definition.

Context: I use fig for dependency management (at work). I have my projects set to put sources in ./the-project/lib/sources; therefore, the following solution assumes the sources are in that directory. If you use Lein (for deps), I'm sure the sources are on your local drive somewhere. All you need to do is change the lisp below to point to your source dir.

Additionally, I use Lein, so I have a project.clj at the root of my project; however, there's nothing special or required about "project.clj". You could just as easily put a this.is.a.project.root file in the root of your project, and search for that file.

The following code will search the your source jars for a Java class, and open the first match that it finds (or no match, if no match is found)

<script src="https://gist.github.com/jaycfields/5272391.js"></script> disclaimer, I'm still an emacs lisp beginner.

The previous code is pretty straightforward. Line 3 uses expand region to mark whatever Java class my cursor is currently on or near. You could type the word instead if you like, this page should help you understand how.
Line 4 and 6 find and verify where the project root lives.
Line 8 (and 9) greps for a string (the Java class) in a directory (my source dir).
Line 10 switches to the grep results.
Line 11 sleeps, waiting for the grep results to return.
Line 12 searches forward, looking for the first match.
Line 13 opens the jar of the first match.
Line 14 assigns the current point to a var named 'current-point'.
Line 15 searches forward to the end of the jar name.
Line 16 grabs the name of the jar and switches to that buffer.
Line 17 searches the jar's dired buffer for the name of the class.
Line 18 opens the first class name match.
(Line 19 lets you know if your project root could not be determined)

That's it, you can now easily find java source (with the occasional conflicting name annoyance). It's not pretty, but it gets the job done.

* I've been told that a few Java modes are good, if I can easily use those to navigate from my Clojure to Java, please leave a link to a manual I can dig into. I assume there are etags solutions, but it's not clear what the best way to go is. I'm sure there's an easy solution for navigating Java from Clojure, I'm just having a hard time finding it.

Episode 42: Why were you suing a website?

Episode 42: Why were you suing a website?:

This week, Ben Orenstein is joined by Peter Moldave, attorney at Gesmer Updegrove to discuss attorney client privilege, what not to do with email, the similarities between lawyers and programmers, how he got into law, his history with technology, and his time as a corporate lawyer at Apple. They also dig into how EULAs work, whether they are binding, whether you should be reading them, and how they can be enforced, software licensing, copyrights and the First-sale doctrine, patent law, software patents, and navigating the patent landscape. They also discuss how to view stock options in your startup job offer, working at startups, how to have a valuable career path, what your employer owns from your side projects or your work for them, how to manage liability in your startup, web site, app on the App Store, and side projects, the best corporate structure and much, much more.

• Episode Notes and Links
• Subscribe via iTunes
• Subscribe via RSS
• Direct Download

Documenting Cookbooks

Our infrastructure has many cookbooks that aim to be reusable, primarily through encapsulating behaviour in LWRPs. This led to an explosion of LWRPs and sometimes the documentation didn't keep up or did just not exist.

Chef has been evolving rapidly and many of the pain points are being addressed by Opscode or by the community at large - which is great. However, one pain point that is not getting easier is writing cookbook documentation. Several threads came together last week to motivate me to change this.

• Incorrect documentation of LWRPs contributed to an outage.
• Mathias Lafeldt wrote a knife plugin that generates an initial README.md from the metadata.rb file in a a cookbook.
• Other languages/frameworks have tools to generate documentation from annotated source code.

So I decided to try and extend Mathias's work so that I could always regenerate README.md from the cookbook source code.

knife cookbook doc DIR

As much as possible the plugin makes use of the same metadata as used by chef when generating the documentation. The plugin will also scan the source files for annotations present in comments. Users can also add fragments of markdown into the doc/ directory to merge into the generated README.md file.

The goal is to keep the code as the authoritative source of information. The hope is that keeping the documentation close to the code will help to maintain it's currency.

Getting Started

Step 1

Populate the metadata.rb of your cookbook according to Opscode's documentation. Particular attention should be paid to documenting the recipes, attributes, platform compatibility and cookbook requirements (i.e. depends, recommends, suggests etc).

Step 2

At the top of each cookbook, add a detailed documentation section such as;

=begin
#<
The recipe is awesome. It does thing 1, thing 2 and thing 3!
#>
=end

Step 3

In each LWRP, add detailed documentation such as;

=begin
#<
This creates and destroy the awesome service.

@action create  Create the awesome service.
@action destroy Destroy the awesome service.

@section Examples

# An example of my awesome service
mycookbook_awesome_service "my_service" do
port 80
end
#>
=end

...

#<> @attribute port The port on which the HTTP service will bind.
attribute :port, :kind_of => Integer, :default => 8080

It should be noted that the documentation of the LWRP requires that the user document the actions, using @action <action> <description> and the attributes using @attribute <attribute> <description>. This allows meaningful descriptions for the actions and attributes to be added to the README.

The other text will be added at the start of the LWRP documentation except if marked with @section <heading>, in which case it will be added to the end of the LWRP documentation.

Step 4

Finally the user should add some documentation fragments into the doc/ dir. Most importantly you should add doc/overview.md which will replace the first Description section of the readme. The remaining fragments will be included at the end of the readme in lexicographic order of the filename.

Step 5

Install the plugin and run the knife command, passing the directory of the cookbook as an argument.

gem install knife-cookbook-doc
knife cookbook doc MY_COOKBOOK_DIR

Examples

For an example of a README generated by the plugin, check out the glassfish cookbook. Unfortunately the plugin highlights the fact that so much of the cookbook is poorly documented. However there are some LWRPs such as glassfish_mq that have the beginning of useful documentation.

Final Thoughts

The plugin is raw but usable now. It needs to evolve to be a more seem-less part of our workflow. It would also be nice to see it or something more complete be adopted by the rest of chef community. I wonder what needs to be done to build such a tool?

Designing for iOS: Blending modes

Let’s say that we have an app that makes use of image assets for icons, custom progress bars, etc. Now we want to allow users to theme the app, and these images need to conform to this new color scheme. The obvious solution is to add 1x and 2x versions of every single possible image asset in the app, right?

No, of course not. Duplication is bad, and duplicating images is just another form of duplication. But we’re clever folks, I’m sure we can find a nice way around this!

We’ll start out with a simple image that we need to tint to our new color scheme. It has an alpha channel, but it’s a flat color and the new color is going to be flat as well.

The smart way to do this would be to redraw the image using a new color using CoreGraphics. Let’s consider the steps needed to make this happen:

1. Create a new image context to draw into.
2. Set the new tint color to be the fill.
3. Get the image size.
4. Draw the source image with the new color while retaining the alpha information.
5. Get the image out of the current context and return it.

Looks pretty straightforward, but retaining the alpha channel will likely be the trickiest part of the exercise. Looking into the UIImage documentation, we know we’re going to want to use -drawInRect:blendMode:alpha: to draw the new image. Looking at the available blending modes leaves us a little… confused:

kCGBlendModeSourceAtop
R = S*Da + D*(1 - Sa)
Available in iOS 2.0 and later.
Declared in CGContext.h.

That’s not actually super helpful. Let’s keep reading, I guess.

The blend mode constants introduced in OS X v10.5 represent the Porter-Duff blend modes.
The symbols in the equations for these blend modes are: 
R is the premultiplied result
S is the source color, and includes alpha
D is the destination color, and includes alpha
Ra, Sa, and Da are the alpha components of R, S, and D

Ah, ok. So we need to do some translation here. What we’re looking for is a blending mode that will draw the new color (Destination, represented by D) using the alpha components from the source (represented by Sa). Looking through the available options armed with this new knowledge, we find one that looks promising:

kCGBlendModeDestinationIn
R = D*Sa
Available in iOS 2.0 and later.
Declared in CGContext.h.

That looks like it’s using the right components, but there’s only one way to be completely sure. Let’s get ready for some good old fashioned trial and error. First, we’ll go ahead and create a category on UIImage:

// UIImage+Tint.h

@interface UIImage (Tint)

- (UIImage *)tintedImageWithColor:(UIColor *)tintColor;

@end

This feels like a nice interface. We can assume that we will either have the image that needs tinting, or we can simply chain it together with -imageNamed: to grab the image from the bundle. Now for the initial implementation:

// UIImage+Tint.m

#import "UIImage+Tint.h"

@implementation UIImage (Tint)

- (UIImage *)tintedImageWithColor:(UIColor *)tintColor
{
    // It's important to pass in 0.0f to this function to draw the image to the scale of the screen
    UIGraphicsBeginImageContextWithOptions(self.size, NO, 0.0f);
    [tintColor setFill];
    CGRect bounds = CGRectMake(0, 0, self.size.width, self.size.height);
    UIRectFill(bounds);
    [self drawInRect:bounds blendMode:kCGBlendModeDestinationIn alpha:1.0];

    UIImage *tintedImage = UIGraphicsGetImageFromCurrentImageContext();
    UIGraphicsEndImageContext();

    return tintedImage;
}

@end

Plugging this into our app is as simple as [[UIImage imageNamed:@"ralph"] tintedImageWithColor:[UIColor thoughtbotRed]];

That was simple enough. But what if we want to retain a gradient from the image? Let’s say we have a nice grayscale button that should be skinned as well:

All we have to do is pass it through our tint method, and voila!

Oops. Looking back at the blending mode, this won’t work at all. The only things that kCGBlendModeDestinationIn takes into account are the destination color, and the source alpha. We’re losing all of the grayscale info from the source image. Looks like we still have more work to do. Once again, we turn to the documentation, and find kCGBlendModeOverlay:

kCGBlendModeOverlay
Either multiplies or screens the source image samples with the background image samples,
depending on the background color. The result is to overlay the existing image samples
while preserving the highlights and shadows of the background. The background color mixes
with the source image to reflect the lightness or darkness of the background.

Available in iOS 2.0 and later.
Declared in CGContext.h.

That sounds like it should tint our gradient nicely. But we don’t want to change the current behavior. This calls for some refactoring. The new interface becomes:

// UIImage+Tint.h

@interface UIImage (Tint)

- (UIImage *)tintedGradientImageWithColor:(UIColor *)tintColor;
- (UIImage *)tintedImageWithColor:(UIColor *)tintColor;

@end

And the new implementation:

// UIImage+Tint.m

#import "UIImage+Tint.h"

@implementation UIImage (Tint)

#pragma mark - Public methods

- (UIImage *)tintedGradientImageWithColor:(UIColor *)tintColor
{
    return [self tintedImageWithColor:tintColor blendingMode:kCGBlendModeOverlay];
}

- (UIImage *)tintedImageWithColor:(UIColor *)tintColor
{
   return [self tintedImageWithColor:tintColor blendingMode:kCGBlendModeDestinationIn];
}

#pragma mark - Private methods

- (UIImage *)tintedImageWithColor:(UIColor *)tintColor blendingMode:(CGBlendMode)blendMode
{
    UIGraphicsBeginImageContextWithOptions(self.size, NO, 0.0f);
    [tintColor setFill];
    CGRect bounds = CGRectMake(0, 0, self.size.width, self.size.height);
    UIRectFill(bounds);
    [self drawInRect:bounds blendMode:blendMode alpha:1.0f];

    UIImage *tintedImage = UIGraphicsGetImageFromCurrentImageContext();
    UIGraphicsEndImageContext();

    return tintedImage;
}

@end

This gets us closer, but you can see that now we’ve lost our alpha information.

Since kCGBlendModeOverlay doesn’t take the source alpha into account, we need to try to get that back. There’s a very simple way that we can accomplish this. We already know that kCGBlendModeDestinationIn` draws the destination image in the source alpha, so we can conditionally redraw the image using this mode:

// UIImage+Tint.m

- (UIImage *)tintedImageWithColor:(UIColor *)tintColor blendingMode:(CGBlendMode)blendMode
{
    UIGraphicsBeginImageContextWithOptions(self.size, NO, 0.0f);
    [tintColor setFill];
    CGRect bounds = CGRectMake(0, 0, self.size.width, self.size.height);
    UIRectFill(bounds);
    [self drawInRect:bounds blendMode:blendMode alpha:1.0f];

    if (blendMode != kCGBlendModeDestinationIn)
        [self drawInRect:bounds blendMode:kCGBlendModeDestinationIn alpha:1.0];

    UIImage *tintedImage = UIGraphicsGetImageFromCurrentImageContext();
    UIGraphicsEndImageContext();

    return tintedImage;
}

@end

And we finally have the desired image:

This image is perfect to assign to a static variable to allow it to be used app-wide, without having to redraw.

By using CoreGraphics to tint our images for us, we open ourselves up to a much wider range of functionality in our apps, and we get the added benefit of smaller bundle sizes, and reduced asset duplication.

Be sure to check out the many different blending modes available in Apple’s documentation. You can check out the sample app that includes the code used here on GitHub.

Ruby Science: Dependency Injection, Inlining Classes, and DRY

We just pushed the latest update to Ruby Science, including three new chapters. Previous purchasers and Prime subscribers can grab the update on Learn.

New chapters this week discuss:

• Using dependency injection to make changes easier and keep decisions close to the objects they affect.
• Inlining classes that no longer pull their own weight to improve readability and simplify dependencies.
• Our first principle chapter, which discusses DRY, including smells and solutions related to detecting and eliminating duplication.

The book is a work in progress, and currently contains around 158 pages of content. Your purchase gets you access to the current release of the book, all future updates, and the companion example application. In addition, purchasers can send thoughtbot their toughest Ruby, Rails, and refactoring questions.

Get your copy of Ruby Science today.

Now Available For Free With Learn Prime

Earlier this week, we announced the launch of our subscription service: Learn Prime.

For just $99/month, you get ongoing access to everything we teach, including books like Ruby Science. You’ll even get access to all our in-person and online workshops. Get access to exclusive subscriber content, as well as access to our private Campfire room, where you can get live help from thoughtbot designers and developers.

Subscribe now.

Denver drinkup

Hey Denver! Our CTO, Joe Ferris, is going to be in Denver next week and we’d like to have a beer with you. We’ll be joining some of our friends over at SendGrid in their spiffy Denver office for good local beer and a talk on “Improving Performance for Real-Time Requests”.

Joe will be schooling us on how to improve slow requests, avoid duplication, invalidate caches, and refactor for performance within Rails applications.

Leave us a comment with your favorite local beer and we’ll do our best to make sure we have you covered. We’ll also have some nonalcoholic beverages on hand as well.

Our Denver/Boulder team now includes, myself, Corey, Elliot, Sean and a few more starting in the next couple of weeks.

Most of us will be there and we are looking forward to meeting you!

RSVP here.

RDoc 4.0.1

• home: https://github.com/rdoc/rdoc
• rdoc: http://docs.seattlerb.org/rdoc
• bugs: https://github.com/rdoc/rdoc/issues

RDoc produces HTML and command-line documentation for Ruby projects. RDoc includes the +rdoc+ and +ri+ tools for generating and displaying documentation from the command-line.

Changes:

• Bug fixes
  • RDoc::Options parser should rescue from OptionParser::ParseError.
  • Updated example of RDoc::Options to include reopening RDoc::Options. Pointed out by Michael Granger
  • Moved RubyGems documentation installed message into RDoc hook. For RubyGems bug #469 by Jeff Sandberg
  • An Error is now raised when a heredoc is not terminated. Fixes exceptions when processing comment blocks. Reported by darix
  • rdoc --quiet --no-ignore-invalid now exits for invalid options. Pull request #192 by Jeremy Evans
  • RDoc::Parser::C no longer ignores a (METHOD) cast in rbdefinemethod. Pull request #184 by Carlos Agarie
  • RDoc::Servlet no longer ignores extra directories from -d. Pull request #173 by Thomas Leitner
  • Fixed rdoc --ri-site. Bug #193 by Michal Papis.
  • RDoc no longer attempts to parse binary files. Bug #189 by postmodern, Bug #190 by Christoffer Lervåg, Bug #195 by Aaron Patterson
  • rdoc --pipe output now contains for markdown compliance.
  • RDoc no longer leaves emacs-style modelines in .txt, .md or .rd files. Bug #178 by Zachary Scott
  • RDoc no longer puts raw markup in HTML output for markdown input. Bug #204 by Erik Hollensbe
  • Code objects with nodoc are no longer included in the ri store. Bug #177 by Thomas Leitner.
  • Text#snippet now creates a RDoc::Markup::ToHtmlSnippet correctly.
  • The C parser now de-duplicates call-seq if the same C function is used for multiple method names. Bug #203 by Pete Higgins