22

Is there a standard or conventional system for organizing multi-file Ruby programs? I have embarked on my first large "project" in Ruby, a search program which is logically organized into multiple files and directories. I've outlined below my potential structure:

  • The main file. This file implements the search class and general searching protocol.
  • The algorithmic analysis file. This file implements functions that interpret search results.
  • Protocols directory
    • Contains one file per protocol to search.
  • Feeds Directory
    • Part of the program's purpose is to search archived news feeds. The files for this feature go in this folder.

However, the code currently has a class (let's call it Searcher) that each protocol's search class inherits from (GoogleSearcher < Searcher). In order to manage this, I need to include the main file in these protocol files (right?) which doesn't seem possible given my ideal structure.

Aside from my specific example, I was wondering if there are any conventions, such as "more files rather than less", or "logical structuring of files is unnecessary". Is it common to have a file of "helper" functions (such as in Rails?) What level of abstraction is considered appropriate?

Finally, I'm planning on integrating this into Rails someday as a library (not a plugin; I want it to work standalone as well). I don't know if this would affect the organization.

I know this is a pretty open-ended question, but that's because I would appreciate any advice that is remotely relevant. Thanks in advance.

3 Answers3

12

You may want to consider creating a gem for your library. This would make it easy to use the library both stand-alone and with Rails, as well as make deployment/updates simpler.

Further, because gems normally follow a specific directory structure, it also solves your issue of not knowing how to organize the library.

There is plenty of documentation available for creating gems. Here's a bit more info about file structure, as well as other useful tips.

Ilia Frenkel
  • 1,969
  • 13
  • 19
vonconrad
  • 25,227
  • 7
  • 68
  • 69
  • there's a few neat gem generating tools: newgem, Jeweler, bones. I used newgem for a project (that was actually NOT intended to be released as a gem) and it worked pretty well – RyanWilcox Jan 05 '10 at 03:17
  • This is good, and it only leaves one unanswered question (in retrospect, this question was definitely too wide.) Is there a way to have class inheritance across multiple files, where the main class is in the main file and classes that inherit from it are in periphery files in a subdirectory? Or is that a backwards organization? –  Jan 05 '10 at 06:05
  • Ruby is pretty forgiving when it comes to inheritance. If I understand your question correctly, it would definitely be possible to set it up as you describe. Without knowing any particulars of your project, I would probably do the same thing where a "main class" is in the lib/foo/ directory and classes that inherit from the main class are in lib/foo/bar, lib/foo/baz and so on. Have a look at gems such as Nokogiri for live examples of this type of setup. – vonconrad Jan 05 '10 at 06:17
  • Ah, but I tried this and have come to the conclusion that I cannot inherit from classes from other source files unless I require those files. How do I require files from a parent directory? –  Jan 05 '10 at 06:23
  • @Luke, you should probably make a new question. But, short answer: Put your libraries onto the ruby load path (gem does this for you), and require all files relative to your library base directory. – Jacob Mar 04 '11 at 22:19
  • 1
    First link (http://www.5dollarwhitebox.org/drupal/creating_a_rubygem_package) is dead. – Cumbayah Jan 25 '13 at 13:58
  • http://blog.bogojoker.com/2008/05/building-a-ruby-gem/ is also dead – ggorlen Dec 19 '22 at 03:35
8

Besides the recommended links in vonconrad's Answer, you can refer to the section “Organizing your source” in Chapter 16 of Programing Ruby 1.9 by Dave Thomas et al. There is a free sample PDF of that part of the book.

The chapter mentions:

16.1 Namespaces We’ve already encountered a way that Ruby helps you manage the names of things in your programs. If you define methods or constants in a class, Ruby ensures that their names can be used only in the context of that class

　　

16.2 Organizing Your Source Small, self-contained scripts can be in a single file... bigger programs should consider the RubyGems system

anagram/ <- top-level
  bin/ <- command-line interface goes here
  lib/ <- three library files go here
  test/ <- test files go here
user454322
  • 7,300
  • 5
  • 41
  • 52
0

I know this question is quite old, but will hopefully be of use to those who come after...

I agree with what's been said above: gems are a great way to organize and reuse code. In addition to the links above, may I recommend using Bundler to create gems as outlined in this Ryan Bates RailsCast: http://railscasts.com/episodes/245-new-gem-with-bundler

I find that Bundler makes gem creation and maintenance very straightforward.

Regarding inheritance, check out how Ruby mixins can be used to encapsulate and reuse code across disparate class hierarchies. http://ruby-doc.org/docs/ProgrammingRuby/html/tut_modules.html

jgpawletko
  • 512
  • 4
  • 13