[](https://rubygems.org/gems/facets)
[](https://github.com/rubyworks/facets/actions/workflows/ci.yml)
+**More of Ruby, one method at a time.** Facets is a collection of extensions to Ruby's core classes and standard library, plus a few small, reusable classes and modules. Most methods live in their own files, so you can load one extension, a class's extensions, or the core collection.
-*"ALL YOUR BASE ARE BELONG TO RUBY"*
+Facets began in 2005 and is still maintained. The current release is **3.2.2**, which requires **Ruby 3.1 or newer**. See the [release history](HISTORY.md) for changes and migration notes from earlier versions. The `main` branch also contains changes awaiting the next release.
+## Install
-## Introduction
+```sh
+gem install facets
+```
-Ruby Facets is the premier collection of general purpose method
-extensions and standard additions for the Ruby programming language.
+With Bundler, add this to your Gemfile:
-Facets houses the largest single collection of methods available for
-extending the core capabilities of Ruby's built-in classes and modules.
-This collection of extension methods are unique by virtue of their atomicity.
-The methods are stored in individual files so that each can be required
-independently. This gives developers the potential for much finer control over
-which extra methods to bring into their code.
+```ruby
+gem 'facets', require: false
+```
-In addition Facets provides a collection of extensions to Ruby standard library
-plus a small collection of add-on classes and modules. Together these
-libraries constitute an reliable source of reusable components, suitable
-to a wide variety of usecases.
+`require: false` lets you choose which extensions to load. Omit it if you want Bundler to load the core collection automatically.
+## Choose how much to load
-## Resources
+### One method
-* Homepage: https://rubyworks.github.io/facets
-* Report Bugs: https://github.com/rubyworks/facets/issues
-* Wiki Pages: https://github.com/rubyworks/facets/wiki
-* Source Code: https://github.com/rubyworks/facets
+```ruby
+require 'facets/array/to_ranges'
+[1, 2, 3, 6, 7].to_ranges
+#=> [1..3, 6..7]
+```
-## Documentation
-
-Facets has special documentation needs due to its extensive breadth.
-The documentation generated when installing via RubyGems, or the YARD
-docs provided by rubydoc.info can be somewhat unwieldy because it
-combines all of Facets in one large set. When using these resources,
-it is important to remain aware of the source location of particular
-methods.
-
-For better organized online documentation, generated to separate core
-extensions from standard libraries, see the [Learn Facets](https://rubyworks.github.io/facets/learn.html) page on the website for links to available documentation.
-
-
-## Installation
-
-### Bundler
-
-If you are using Bundler with your project, add the facets gem to the project's
-Gemfile. Unless you want all of facets loaded be sure to add the `:require => false`
-option.
-
- gem "facets", require: false
-
-### RubyGems
-
-The easiest way to install is via RubyGems.
-
- $ gem install facets
-
-### Requirements
-
-Facets 3.2+ requires Ruby 3.1 or higher.
-
-
-## Mission
-
-Facets holds to the notion that the more we can *reasonably* integrate into
-a common foundation, directed toward general needs, the better that foundation
-will be able to serve the community. There are a number of advantages here:
-
-* Better Code-reuse
-* Collaborative Improvements
-* Greater Name Consistency
-* One-stop Shop and Installation
-
-
-## Usage
-
-### CORE Library
-
-At the heart of Ruby Facets is the CORE extensions library. CORE provides
-a sizable collection of generally useful methods, along with a few supporting
-classes, that extend the functionality of Ruby's core classes and modules.
-
-With the exception of a few *uncommon* extensions, CORE contains anything that
-will load automatically when issuing:
-
- require 'facets'
-
-This loads all the CORE functionality at once. If you plan to use more then a
-handful of Facets core methods it is recommended that you require the library in
-this way. However, you can also "cherry pick" the CORE library as you prefer.
-And for uncommon extensions this must be done. The general require statement for
-a core extension library is:
-
- require 'facets/As programmers are wont to do, I started collecting reusable pieces of +Ruby long ago. At first it was just a small function here, a useful +module there. Eventually the collection became sizable and I called it TomsLib. +As time wore on and my library grew, I started to feel it worth a general +release and I had renamed it Raspberry Lib. But sometime shortly thereafter +I hit upon the idea of atomicity of the core extensions. And that's how the +name Facets came about --it's all about the little things. Of course, that name +took a while to decide upon too. The library was almost called "Atomix & Trix"!
+ +Facets has eveolved considerably over the years --and lessons were learned. Probably +the biggest lesson was the 2.0 release, where the idea of atomicity was eroded and +and alternate means of library requiring was attempted. Both were rectified by 2.4.
+ +Much has changed since those first days. But time has been good to Facets. +Today, Facets is a more solid and leaner library than ever before and will +continue in the fashion for version to come.
diff --git a/docs/_src/archive/2008-03-24-release-2-4.html b/docs/_src/archive/2008-03-24-release-2-4.html new file mode 100644 index 000000000..ebe212355 --- /dev/null +++ b/docs/_src/archive/2008-03-24-release-2-4.html @@ -0,0 +1,57 @@ +Facets 2.4.3 is now out in the wild. The release is primarily a maintenance +release —fixing a handful of small bugs and adding some small feature +improvements, but a few significant changes are also present.
+ +Note that this release does not include a setup.rb script. We are working +on a new version of this script, which we plan to include in the next +release.
+ +Special thanks to:
+ +And of course, to anyone else I failed to mention that has contributed.
+ +Finally, Facets 2.4+ now encourages using:
+ +require 'facets'
+when testing, even if you are cherry-picking methods. It may seem counter-intuitive, +but it actually proves more advantages to do this for the sake of improved +interoperability. The practice of cherry-picking can become problematic if +other dependent libraries have cherry-picked different methods, and the +the different choices go unaccounted and untested.
+ +Facets is almost fully interoperable with ActiveSupport and Ruby 1.9. We +will continue to improve this interoperability in upcoming releases.
diff --git a/docs/_src/archive/2009-07-21-new-website.html b/docs/_src/archive/2009-07-21-new-website.html new file mode 100644 index 000000000..f0f614f71 --- /dev/null +++ b/docs/_src/archive/2009-07-21-new-website.html @@ -0,0 +1,8 @@ +The old Ruby Facets website was a static 100% XML/XSLT site. When I originally created +the site, I though XML/XSLT suredly was the pinnicale and proper way to build a +modern site --for no other reason that XSL is a pain in the ass! Well, we all know +the ultimate outcome of this story. XML/XSLT is turning out to be an exmplar of +over engineering by academics.
+ +The new Facets website runs of Jekyll, a static site generator supoprted by GitHub. +(another good site tool is Shunman)
diff --git a/docs/_src/archive/2009-08-22-release-2-7.html b/docs/_src/archive/2009-08-22-release-2-7.html new file mode 100644 index 000000000..97ca89f07 --- /dev/null +++ b/docs/_src/archive/2009-08-22-release-2-7.html @@ -0,0 +1,122 @@ +Facets 2.7 is most significant release of Facets since 2.4. Rather then trickle-release +these changes over the course of the 2.6.x series, I made the decision to let 2.7 have them +all at once. In so doing this release nearly completes the process of trimming down +the MORE library to its essentials. Over 40 high-level libraries have been spun-off +as separate gems and/or deprecated. No doubt this is a big change for Facets, and the +transition may be a bit bumpy over the short-term, but I am certain that in the long-run +everyone involved will be better served. To help, I have listed the effected libraries +and the alternate gems available to take their place.
+ +A few other changes have also been made in the release that may also effect your code. +In particular you should note that #class_extension has been renamed to #class_extend +(require 'facets/class_extend'). In addition we have added a few new core methods such +as Exception#raised? and Symbol#thrown?.
+ +These libraries have been deprecated from Facets entirely, but are available +as separate gems (or soon will be).
+ +LIBRARY GEM
+------------------- -------------------------
+overload.rb overload
+binreadable.rb binaryio
+downloader.rb downloader
+xoxo.rb xoxo
+bicrypt.rb bicrypt
+typecast.rb typecast
+association.rb association
+syncarray.rb sync
+synchash.rb sync
+paramix.rb paramix
+crypt.rb crypt3
+lrucache.rb lrucache
+net/smtp_tls.rb smtp_tls
+advisable.rb advisable
+buildable.rb buildable
+memoizer.rb memoizer
+harray.rb sparray
+sparse_array.rb sparray
+iteration.rb iteration
+interval.rb stick
+infinity.rb stick
+pool.rb pool
+linkedlist.rb linkedlist
+semaphore.rb semaphore
+pqueue.rb pqueue
+censor.rb language
+macther.rb language
+basex.rb radix
+minitar.rb archive-tar-minitar, folio
+These libraries have been spun-off into stand-alone gems, but remain +available via Facets too. Ultimately some of these will be removed +from Facets too (in particular the ansi libraries).
+ +LIBRARY GEM
+------------------- -------------------------
+ansicode.rb ansi
+progressbar.rb ansi
+logger.rb ansi
+tracepoint.rb tracepoint
+dictionary.rb dictionary
+recorder.rb recorder
+ostructable.rb ostructable, openhash
+openobject.rb openhash
+opencollection.rb openhash
+opencascade.rb openhash
+openhash.rb openhash
+openmodule.rb openmodule
+fileable.rb fileable
+expirable.rb expirable
+enumerablepass.rb enumargs
+The libraries have been deprecated but do not yet have replacements. +Separate gems for these are planned though.
+ +* bbcode.rb
+* ini.rb
+* settings.rb
+* xmlhash.rb
+These libraries have been deprecated because their functionality was merged into +the CORE library and/or made available in some another way.
+ +* 1stclassmethod.rb #method! and #instance_method! are now part of CORE.
+* elementor.rb #per has been added to CORE.
+* elementwise.rb #ewise has been added to CORE.
+* consoleutils.rb #ask is in CORE, for the rest see Ansi or Clio project.
+* attr.rb Added Module#attr_setter to CORE, and separated the rest in MORE.
+These libraries have simply been deprecated because they were found lacking in +some significant fashion.
+ +* nilstatus.rb Poved rather useless, not to mention trivial.
+* heap.rb Heap was just an alias for PQueue anyway. Use 'pqueue' instead.
+* dependency.rb Other solutions exist that are much better (like Advisable).
+* classmethods.rb #class_extend solution is more robust.
+* ziputils.rb Have a look at Folio (gem install folio) for replacement.
+* unheritable.rb Implementation is trivial and usefulness questionable.
+* instantise.rb Replaced by instance_function.rb.
+In addition to all this we've also taken some time to ensure Ruby Facets is more compatible +with Ruby 1.9 --indeed, at this point, it should be very close to fully compatibility. In +the process of doing this, btw, it has become clear that Ruby 1.9 picked up a good number +of methods already supported by Facets (some with the same exact names and some with +changed names). There's no way to know if Facets had any influence in these additions +to 1.9, but at the very least we can be sure that Facets contributed to "airing the field" +that led to their addition. That's a great thing, as it means Facets is directly contributing +to Ruby's future. I hope that will continue.
diff --git a/docs/_src/archive/2009-11-09-release-2-8.html b/docs/_src/archive/2009-11-09-release-2-8.html new file mode 100644 index 000000000..64630b604 --- /dev/null +++ b/docs/_src/archive/2009-11-09-release-2-8.html @@ -0,0 +1,62 @@ +Facets 2.8 effectively completes the MORE library clean-up which peaked +with the previous 2.7 release. In so doing, five additional libraries +have been deprecated:
+ +Three other libraries have been deprecated, but have been spun-off +to the new 'ansi' project:
+ +This version of Facets also reverts a few of the deprecations made before -- +reconsiderations made due to analysis of the code as suitable for release +as separate projects. These libs will thus remain in Facets's MORE library +at least for the forseeable future.
+ +Other minor enhancements have also been made in the release. These include:
+ +In addition to all this, we have recently set up a new Ruby 1.9 compliance procedure +using RunCodeRun.com. Actually RunCodeRun helps us to ensure 1.8.6 compabiltiy as well. +This is great tool for improving code quality, and comes highly recommended.
diff --git a/docs/_src/archive/2010-09-01-release-2-9.html b/docs/_src/archive/2010-09-01-release-2-9.html new file mode 100644 index 000000000..37e0c8a2e --- /dev/null +++ b/docs/_src/archive/2010-09-01-release-2-9.html @@ -0,0 +1,28 @@ +Facets 2.9 is fairly extensive as it was originally intended to be v3.0. +After further consideration it was decided to reserve v3.0 for something a +little bolder (to be announced). The primary goal of this release was to +trim Facets down to a true core extensions library. All tertiary add-on classes +and mixins have now been spun-off to other projects. Only a very select set of +general purposes classes and mixins remain.
+ +A new TOUR library division has been added to complement CORE and MORE. +This division houses purely optional extensions. The new division serves +a couple of useful purposes. In particular, it helps separates the standard +library extensions from optional core extension in the RDocs and thus makes +the perfect place to vet new extension ideas.
+ +One important change that will effect anyone using Facets along side +ActiveSupport is that Facets no longer tries to conditionally avoid +method overlaps with ActiveSupport. This is fine for the upcoming +ActiveSupport 3.0 library which extends core classes directly instead of +using mixins. One need only require 'facets' in Rails' config/preinitializer.rb +file, and ActiveSupport will take precedence over Facets. For older versions +of ActiveSupport, the best approach is to cherry pick from Facets just the +extensions you want, thus avoiding any conflicts. There are actually only a +dozen or so overlaps and all are intended to compatible, but it doesn't hurt +to be sure.
+ +I won't detail each change here, have a look at the HISTORY.rdoc file for that. +Needless to say, it's a good idea to read it over to see what changes might +effect your usage --and it also gives you a glimpse at what other extensions are +available that you might not yet be familiar.
diff --git a/docs/_src/index.erb b/docs/_src/index.erb new file mode 100644 index 000000000..b2741f948 --- /dev/null +++ b/docs/_src/index.erb @@ -0,0 +1,55 @@ +A Ruby library since 2005
+A thoughtfully collected set of extensions for Ruby's core classes and standard library. Load the whole core collection or pick just the methods you need.
+ +Version 3.2.2 Ruby 3.1+ BSD 2-Clause
+# Load only what you need
+require 'facets/array/to_ranges'
+
+[1, 2, 3, 6, 7].to_ranges
+#=> [1..3, 6..7]
+ THE IDEA
Facets brings useful Ruby methods together in a form you can discover, reuse, and improve. Each extension stays easy to find and easy to require.
01 / GRANULAR
Most methods have their own file. Add a single method without loading a larger set of extensions.
02 / FAMILIAR
Build on the classes and modules you already use, from Array and String to parts of the standard library.
03 / COMMUNITY
Years of contributions and refinement live in one collection, with tests and source credits alongside the code.
MAKE IT YOURS
Choose the amount of Facets that fits your project. You can change that choice as your needs grow.
See the loading guiderequire 'facets/time/stamp'require 'facets/time'require 'facets'require 'facets/ostruct'LATEST RELEASE
Version 3.2.2 includes compatibility fixes across Ruby 3.1–3.4, following the 3.2 modernization release.
Read the release notes
Ruby Facets
+
+ GitHub
+ THE GUIDE
Install the gem, choose how much to load, and make Ruby feel a little more like yours.
01 / GET READY
Facets 3.2.2 requires Ruby 3.1 or newer. Install it directly with RubyGems or add it to a Bundler project.
gem install facetsgem 'facets', require: falserequire: false keeps Bundler from loading the entire core collection automatically, so you can choose the files your project needs.
02 / CHOOSE YOUR SCOPE
Most core extension methods are stored in individual files. You can require one method, a class's core methods, or the core collection.
# One method
+require 'facets/array/to_ranges'
+
+# A class's core extensions
+require 'facets/string'
+
+# Most core extensions
+require 'facets'Standard library extensions are separate from the core collection. Require each one explicitly. For example, require 'facets/ostruct' loads Ruby's ostruct and the Facets additions for it.
ostruct gem separately if you use Facets' OpenStruct extensions. Ruby no longer includes it as a default gem.03 / SEE IT WORK
These examples use methods present in the 3.2 release.
require 'facets/array/to_ranges'
+[1, 2, 3, 6, 7].to_ranges
+#=> [1..3, 6..7]
+
+require 'facets/string/dashcase'
+'Ruby Facets'.dashcase
+#=> "ruby-facets"
+
+require 'facets/range/intersection'
+Range.intersection(1..10, 5..15)
+#=> 5..10Extensions add methods to Ruby's existing classes. When combining libraries that extend the same classes, choose your requires deliberately and check for method name overlap.
04 / KEEP EXPLORING
RubyDoc.info hosts generated API documentation; check the displayed gem version when browsing. In the published 3.2.2 gem, lib/core belongs to the core collection and lib/standard contains separately loaded libraries. The source repository also contains unreleased changes, including a new lib/rails area.
RELEASES & HISTORY
Facets has been growing since 2005. Here are the recent releases and a path back through its story.
LATEST RELEASES
The 3.2 series brings the library forward for Ruby 3.1 and newer. Work merged since 3.2.2 is listed under Unreleased in the release history.
LATEST
Fixes range intersection on Ruby 3.1 and 3.2, restores Range#overlap? where Ruby does not provide it, and corrects Binding#caller_locations argument handling.
Repairs stale require paths that affected require 'facets' in 3.2.0, and adds a load-path regression check. Also adds OpenDSL and PIC.
Moves the minimum Ruby version to 3.1, adds methods such as Array#to_ranges and String#dashcase, and retires extensions now built into Ruby.
FROM THE ARCHIVE
These posts are preserved as published. Their install advice and API links describe older Facets releases; use the current guide for 3.x.
OPEN SOURCE
Facets was made by Rubyists sharing useful ideas. There is room for better methods, better tests, clearer docs, and thoughtful bug reports.
GET INVOLVED
Browse the source to see how extensions are organized, or open an issue when something could work better.
See the core, standard, and developing Rails-compatible libraries, plus tests and demos, in the GitHub repository.
Share a reproducible bug, a documentation gap, or an idea for a generally useful extension.
Learn the project's conventions for method files, tests, demos, and pull requests.
DEVELOP LOCALLY
Core extensions live under lib/core/facets, standard library extensions under lib/standard/facets, and unreleased Rails-compatible helpers under lib/rails/facets. Keep focused changes close to their tests and demos.
git clone https://github.com/rubyworks/facets.git
+cd facets
+bundle install
+bundle exec rake testPEOPLE & LICENSE
Thomas Sawyer began Facets in 2005. Many contributors have shaped its methods, tests, and documentation since then. Credits for individual pieces appear in the source, and the collection is distributed under the BSD 2-Clause License.
Read the licenseFROM THE ARCHIVE / #{date}
This post is preserved from an earlier Facets release. For current installation and API guidance, use the guide.
-
-
-
- 
+ Skip to content
+ Ruby Facets
+
+ GitHub
A Ruby library since 2005
+A thoughtfully collected set of extensions for Ruby's core classes and standard library. Load the whole core collection or pick just the methods you need.
+ +Version 3.2.2 Ruby 3.1+ BSD 2-Clause
+# Load only what you need
+require 'facets/array/to_ranges'
+
+[1, 2, 3, 6, 7].to_ranges
+#=> [1..3, 6..7]
Ruby Facets was first released in 2005. Since then it has evolved into the -single largest and most refined core extensions library for the Ruby programming -language. All facets can be loaded with a single require or cherry-picked -individually. There are hundreds of quality methods in the collection which -have been derived from years of experience of dozens of top Ruby programmers.
- -In addition to the core libraries, Facets provides extensions to Ruby standard -library, as well as as a small collection of add-on classes and mixins. -Together with core extensions these libraries provide a broad general-purpose -set of components commonly useful across a wide variety of applications.
- -Who uses Facets? Lots of Rubyists do!
- -Many developers use Facets as a copy-and-paste resource, others use it as a dependency -cherry-picking just the methods they need, and still others use the library whole-clothe. -How you use Ruby Facets to facilitate your Ruby development is completely yours to decide.
- -
The philosophy of Facets can be summed -up in a simple mantra, ALL BASE COMMON. The idea being, that by sharing a broad foundation -of general purpose code, the Ruby community will be better served. There are a number of -advantages to this approach. Among them: name consistency, better code-reuse, collaborative -improvements and reduced installation requirements.
- -Facets also embodies the idea of "having it your way". You can use as much or as little -of Facets as you see fit. In fact, Ruby Facets originated the idea cherry-pickable extensions.
- -Facets is not the sole achievement of one person, but was made possible by the hard -work of many excellent programmers. Some persons contributed code directly, other's simply -had their code picked-up from another open resource. In either case, three cheeers -for all!
- - Thibaut Barrère Daniel J. Berger Ken Bloom
- Rich Bradley Paul Brannan Mikael Brockman
- Jamis Buck Renald Buter Brian Candler
- Shashank Date Robert Feldt Mauricio Fernandez
- Florian Frank Hal Fulton Noah Gibbs
- Michael Granger Florian Gross Sean O'Halpin
- Michael Harmer Matthew Harris David Heinemeier Hansson
- Thomas-Ivo Heinen Dave Hoover Ara T. Howard
- MenTaLguY Mohammad Khan Robert Klemme
- Michael Kohl Richard Laugesen Lavir the Whiolet
- Derek Lewis Jan Molic George Moschovitis
- Michael Neumann Marco Otte-Witte Roger Pack
- Jeena Paradies Tim Pease Jonas Pfenniger
- Ryan Platte Oliver Renaud Tyler Rick
- Christoph Rippel Daniel Schierbeck Louis J Scoras
- Gavin Sinclair Tilo Sloboda Sandor Szücs
- Phil Tomson Mauro Tortonesi Peter Vanbroekhoven
- Jim Weirich Jeff Wood Jean-Denis Vauguet
- Erik Veenstra Austin Ziegler Why The Lucky Stiff
-Facets is true open source software. Ruby Facets is distributed under the terms of the -Ruby License, -just like Ruby.
- -Ruby Facets, Copyright (c) 2005-2010 Thomas Sawyer
- -Credit and any additional copyrights for particular code fragments are -given in their respective source. All secondary licenses are either compatible -with the Ruby license or the original author has given permission for -inclusion of their code under this license.
- -THE IDEA
Facets brings useful Ruby methods together in a form you can discover, reuse, and improve. Each extension stays easy to find and easy to require.
01 / GRANULAR
Most methods have their own file. Add a single method without loading a larger set of extensions.
02 / FAMILIAR
Build on the classes and modules you already use, from Array and String to parts of the standard library.
03 / COMMUNITY
Years of contributions and refinement live in one collection, with tests and source credits alongside the code.
MAKE IT YOURS
Choose the amount of Facets that fits your project. You can change that choice as your needs grow.
See the loading guiderequire 'facets/time/stamp'require 'facets/time'require 'facets'require 'facets/ostruct'
-
- LATEST RELEASE
Version 3.2.2 includes compatibility fixes across Ruby 3.1–3.4, following the 3.2 modernization release.
Read the release notes
-
-
-
-
+ Skip to content
+ Ruby Facets
+
+ GitHub
THE GUIDE
Install the gem, choose how much to load, and make Ruby feel a little more like yours.
01 / GET READY
Facets 3.2.2 requires Ruby 3.1 or newer. Install it directly with RubyGems or add it to a Bundler project.
gem install facetsgem 'facets', require: falserequire: false keeps Bundler from loading the entire core collection automatically, so you can choose the files your project needs.
02 / CHOOSE YOUR SCOPE
Most core extension methods are stored in individual files. You can require one method, a class's core methods, or the core collection.
# One method
+require 'facets/array/to_ranges'
+
+# A class's core extensions
+require 'facets/string'
+
+# Most core extensions
+require 'facets'Standard library extensions are separate from the core collection. Require each one explicitly. For example, require 'facets/ostruct' loads Ruby's ostruct and the Facets additions for it.
ostruct gem separately if you use Facets' OpenStruct extensions. Ruby no longer includes it as a default gem.03 / SEE IT WORK
These examples use methods present in the 3.2 release.
require 'facets/array/to_ranges'
+[1, 2, 3, 6, 7].to_ranges
+#=> [1..3, 6..7]
+
+require 'facets/string/dashcase'
+'Ruby Facets'.dashcase
+#=> "ruby-facets"
+
+require 'facets/range/intersection'
+Range.intersection(1..10, 5..15)
+#=> 5..10Extensions add methods to Ruby's existing classes. When combining libraries that extend the same classes, choose your requires deliberately and check for method name overlap.
04 / KEEP EXPLORING
RubyDoc.info hosts generated API documentation; check the displayed gem version when browsing. In the published 3.2.2 gem, lib/core belongs to the core collection and lib/standard contains separately loaded libraries. The source repository also contains unreleased changes, including a new lib/rails area.
Facets can be dowloaded and installed easily using RubyGems:
- -$ gem install facets
-Gems will automatically generate rdocs on installation. Unfortunately -the Gem generated rdocs are very poor --in fact Facets only allows them -to be generated to ensure the creation of ri docs (ruby api index files). -We recommend instead that you use the pre-generated rdocs on the website.
- -Note this is a very old-school installation method. We should probably remove this, -but for the moment we leave it her for posterity's sake.
- -
If you would like to install from source, you can download the tarball -package from GitHub -and use Ruby Setup, e.g.
- -$ tar -xvzf facets-2.9.0.tgz
-$ cd facets-2.9.0
-$ setup.rb
-The last step may require super-user permissions (eg. use sudo).
Of course, to use Facets you also need Ruby. The 2.x versions of Facets are -designed to work with Ruby 1.8.6 and up. Facets is fully compatible with Ruby 1.9.
- -The YARD documentation includes all of Facets, -both the core extensions and standard library, in a single reference resource.
- -Facets offical API documentation is divided into two documentation sets, one for the core extensions, -and the other for the standard library extensions and additions.
- -PLEASE NOTE THE FOLLOWING DOCUMENTATION RESOURCES ARE DOWN UNTIL YOURS TRULY HAS A CHANCE TO FIX.
- -The CORE API -(alt) -includes only the core extensions. These methods are at the heart of Facets. Any application or library that makes use of Facets -is encouraged to write their tests with all of these methods loaded to ensure cross-application support. Also included is the -Functor class, which is a Higher Order Message class. It is used by a number of methods to provide fluid interfaces.
- -The STANDARD API -(alt) -documents a variety of extension methods to Ruby's standard library, and additional -classes and modules Facets provides as optional libraries.
- -The Wiki is a place for end-users to create their own documentation. Ultimately, -it is hoped, this documentaiton will make a great source for sharing real-world -use cases. The community wiki, that anyone can use to help document Facets, is at -Facets Wiki.
- -Facets has a dedicated mailing list hosted via -Google Groups. -The same list is used by developers and end-users alike. If you have a -question or a suggestion, the list this is a place you can use to get feedback. -However the Github Issues page is so good these days that most people opt just to use it -instead, which is fine.
- -
-
-
-
-
-
- Facets 2.9 is fairly extensive as it was originally intended to be v3.0. -After further consideration it was decided to reserve v3.0 for something a -little bolder (to be announced). The primary goal of this release was to -trim Facets down to a true core extensions library. All tertiary add-on classes -and mixins have now been spun-off to other projects. Only a very select set of -general purposes classes and mixins remain.
- - -Facets 2.8 effectively completes the MORE library clean-up which peaked -with the previous 2.7 release. In so doing, five additional libraries -have been deprecated:
- -Three other libraries have been deprecated, but have been spun-off -to the new 'ansi' project:
- -Facets 2.7 is most significant release of Facets since 2.4. Rather then trickle-release -these changes over the course of the 2.6.x series, I made the decision to let 2.7 have them -all at once. In so doing this release nearly completes the process of trimming down -the MORE library to its essentials. Over 40 high-level libraries have been spun-off -as separate gems and/or deprecated. No doubt this is a big change for Facets, and the -transition may be a bit bumpy over the short-term, but I am certain that in the long-run -everyone involved will be better served. To help, I have listed the effected libraries -and the alternate gems available to take their place.
- - -The old Ruby Facets website was a static 100% XML/XSLT site. When I originally created -the site, I though XML/XSLT suredly was the pinnicale and proper way to build a -modern site --for no other reason that XSL is a pain in the ass! Well, we all know -the ultimate outcome of this story. XML/XSLT is turning out to be an exmplar of -over engineering by academics.
- -The new Facets website runs of Jekyll, a static site generator supoprted by GitHub. -(another good site tool is Shunman)
- - -Facets 2.4.3 is now out in the wild. The release is primarily a maintenance -release —fixing a handful of small bugs and adding some small feature -improvements, but a few significant changes are also present.
- -Note that this release does not include a setup.rb script. We are working -on a new version of this script, which we plan to include in the next -release.
- - -As programmers are wont to do, I started collecting reusable pieces of -Ruby long ago. At first it was just a small function here, a useful -module there. Eventually the collection became sizable and I called it TomsLib. -As time wore on and my library grew, I started to feel it worth a general -release and I had renamed it Raspberry Lib. But sometime shortly thereafter -I hit upon the idea of atomicity of the core extensions. And that's how the -name Facets came about --it's all about the little things. Of course, that name -took a while to decide upon too. The library was almost called "Atomix & Trix"!
- - -
-
- Ruby Facets
+
+ GitHub
+ RELEASES & HISTORY
Facets has been growing since 2005. Here are the recent releases and a path back through its story.
LATEST RELEASES
The 3.2 series brings the library forward for Ruby 3.1 and newer. Work merged since 3.2.2 is listed under Unreleased in the release history.
LATEST
Fixes range intersection on Ruby 3.1 and 3.2, restores Range#overlap? where Ruby does not provide it, and corrects Binding#caller_locations argument handling.
Repairs stale require paths that affected require 'facets' in 3.2.0, and adds a load-path regression check. Also adds OpenDSL and PIC.
Moves the minimum Ruby version to 3.1, adds methods such as Array#to_ranges and String#dashcase, and retires extensions now built into Ruby.
FROM THE ARCHIVE
These posts are preserved as published. Their install advice and API links describe older Facets releases; use the current guide for 3.x.
-
-
-
- 
Ruby Facets
+
+ GitHub
As programmers are wont to do, I started collecting reusable pieces of
+ FROM THE ARCHIVE / 2008-01-01 This post is preserved from an earlier Facets release. For current installation and API guidance, use the guide. As programmers are wont to do, I started collecting reusable pieces of
Ruby long ago. At first it was just a small function here, a useful
module there. Eventually the collection became sizable and I called it TomsLib.
As time wore on and my library grew, I started to feel it worth a general
@@ -88,53 +42,23 @@ Much has changed since those first days. But time has been good to Facets.
Today, Facets is a more solid and leaner library than ever before and will
continue in the fashion for version to come.How Facets Was Born
How Facets Was Born
-
-
-
-
-
-
-
-
-
- Ruby Facets
+
+ GitHub
Facets 2.4.3 is now out in the wild. The release is primarily a maintenance
+ FROM THE ARCHIVE / 2008-03-24 This post is preserved from an earlier Facets release. For current installation and API guidance, use the guide. Facets 2.4.3 is now out in the wild. The release is primarily a maintenance
release —fixing a handful of small bugs and adding some small feature
improvements, but a few significant changes are also present. Facets is almost fully interoperable with ActiveSupport and Ruby 1.9. We
will continue to improve this interoperability in upcoming releases.Facets 2.4.3
Facets 2.4.3
-
-
-
-
-
-
-
-
-
- Ruby Facets
+
+ GitHub
The old Ruby Facets website was a static 100% XML/XSLT site. When I originally created
+ FROM THE ARCHIVE / 2009-07-21 This post is preserved from an earlier Facets release. For current installation and API guidance, use the guide. The old Ruby Facets website was a static 100% XML/XSLT site. When I originally created
the site, I though XML/XSLT suredly was the pinnicale and proper way to build a
modern site --for no other reason that XSL is a pain in the ass! Well, we all know
the ultimate outcome of this story. XML/XSLT is turning out to be an exmplar of
@@ -80,55 +34,23 @@ The new Facets website runs of Jekyll, a static site generator supoprted by GitHub.
(another good site tool is Shunman)New Website with Jekyll
New Website with Jekyll
-
-
-
-
-
-
-
-
-
- Ruby Facets
+
+ GitHub
Facets 2.7 is most significant release of Facets since 2.4. Rather then trickle-release
+ FROM THE ARCHIVE / 2009-08-22 This post is preserved from an earlier Facets release. For current installation and API guidance, use the guide. Facets 2.7 is most significant release of Facets since 2.4. Rather then trickle-release
these changes over the course of the 2.6.x series, I made the decision to let 2.7 have them
all at once. In so doing this release nearly completes the process of trimming down
the MORE library to its essentials. Over 40 high-level libraries have been spun-off
@@ -194,55 +148,23 @@ Facets 2.7 is a Significant Release
General Deprecations
to 1.9, but at the very least we can be sure that Facets contributed to "airing the field"
that led to their addition. That's a great thing, as it means Facets is directly contributing
to Ruby's future. I hope that will continue.
-
-
-
-
-
- Ruby Facets
+
+ GitHub
Facets 2.8 effectively completes the MORE library clean-up which peaked
+ FROM THE ARCHIVE / 2009-11-09 This post is preserved from an earlier Facets release. For current installation and API guidance, use the guide. Facets 2.8 effectively completes the MORE library clean-up which peaked
with the previous 2.7 release. In so doing, five additional libraries
have been deprecated: In addition to all this, we have recently set up a new Ruby 1.9 compliance procedure
using RunCodeRun.com. Actually RunCodeRun helps us to ensure 1.8.6 compabiltiy as well.
This is great tool for improving code quality, and comes highly recommended.Facets 2.8 Release
Facets 2.8 Release
-
-
-
-
-
-
-
-
-
- Ruby Facets
+
+ GitHub
Facets 2.9 is fairly extensive as it was originally intended to be v3.0.
+ FROM THE ARCHIVE / 2010-09-01 This post is preserved from an earlier Facets release. For current installation and API guidance, use the guide. Facets 2.9 is fairly extensive as it was originally intended to be v3.0.
After further consideration it was decided to reserve v3.0 for something a
little bolder (to be announced). The primary goal of this release was to
trim Facets down to a true core extensions library. All tertiary add-on classes
@@ -100,53 +54,23 @@ Facets 2.9 Release
Facets 2.9 Release
Needless to say, it's a good idea to read it over to see what changes might
effect your usage --and it also gives you a glimpse at what other extensions are
available that you might not yet be familiar.
-
-
-
-
-
-
+ Skip to content
+ Ruby Facets
+
+ GitHub
OPEN SOURCE
Facets was made by Rubyists sharing useful ideas. There is room for better methods, better tests, clearer docs, and thoughtful bug reports.
GET INVOLVED
Browse the source to see how extensions are organized, or open an issue when something could work better.
See the core, standard, and developing Rails-compatible libraries, plus tests and demos, in the GitHub repository.
Share a reproducible bug, a documentation gap, or an idea for a generally useful extension.
Learn the project's conventions for method files, tests, demos, and pull requests.
DEVELOP LOCALLY
Core extensions live under lib/core/facets, standard library extensions under lib/standard/facets, and unreleased Rails-compatible helpers under lib/rails/facets. Keep focused changes close to their tests and demos.
git clone https://github.com/rubyworks/facets.git
+cd facets
+bundle install
+bundle exec rake testPEOPLE & LICENSE
Thomas Sawyer began Facets in 2005. Many contributors have shaped its methods, tests, and documentation since then. Credits for individual pieces appear in the source, and the collection is distributed under the BSD 2-Clause License.
Read the licenseGitHub houses our working git repository.
-Anyone is welcome to fork this repository and contribute back to the master branch
-via pull requests. If you are not familiar with using GitHub, here is a
-overview.
The master source is avaiable here.
- -The widely accepted practice of contributing to GitHub projects entails:
- -Following this procedure will make everyone’s life easier.
- -As with all good libraries, testing is vital. Facets handles testing via two different -libraries. Lemon is used for unit testing and QED is used for behavior specifications. -Lemon was actaully designed specifially for Ruby Facets which forces tests to be on -a per-method basis. QED is a tool for literate BDD. In fact Facets inline -docuemtation is fully executable via QED.
- -If you have any questions, suggestions or contributions you'd like to make privately, -you can contact Trans <transfire AT gmail DOT com>.
- -
-
-