I have added over 20 example ruby files to github. See them at GitHub - braddenn/SketchupEx: How To Examples of Ruby code extensions for Sketchup CAD . They are free. I developed them to learn how to use the API. These are like the examples on the help file BUT these display the results so that you can learn what is happening.
Update them, add to them. Lets help the newbies get going faster.
(1) You do not need the line:
require 'sketchup.rb'
unless you will be calling any of the global methods, that are defined in that file (which is located in the binary “Tools” sub-directory, if you care to read it.)
Most coders make sure it is loaded, when loading their SketchUp extensions, because they are adding items to the menus.
The “sketchup.rb” file adds a couple of global methods, that help make sure that the blocks that add menu items only do so once.
Read the file, and note the file_loaded() and file_loaded?() methods.
(2) I am against any examples that teach newbies to create global variables in the global ObjectSpace, create global methods in the global ObjectSpace, … or otherwise write and execute ANY code outside there OWN author namespace module.
There is NO good reason for it. Teach them how to do it correct from the beginning.
(3) Ruby uses a 2 space ident, not a 8 space indent. (That’s Javascript. Python uses a 4 space indent, FYI.)
Hi Dan,
THANK YOU. I have over 40 years programming experience but this language
throws me a loop. No types. Strange scopes. lambdas (like lisp), single
pass,… and I have only been learning Ruby part time for about 5 months.
If scripts are children and C++ is an adult then Ruby is a wild teenager.
I get comments 1 and 3. I will look into tools (like /bin/tools) and
conserve on spaces. But comment 2 loses me. Oh wait, you mean for me to
create my OWN namespace. Hmmm. Yes that is different from ‘global object
space’. And doing my own stops hidden overrides. OK I will follow up on all
three concepts.
And thanks for reading my files so quickly. You are a great help.
brad
Brad Denniston
408-892-4544
Hi Dan,
All suggested changes have been made. Then I QA’ed every file to make sure
they would all execute without errors.
The git repo has been updated (commit -a -m, push).
Next I will work on the context - make it easy to bring up any example via
a .rb in the startup dir.
Any other suggestions?
brad
Brad Denniston
408-892-4544
That is not what I meant. I mean the “Tools” sub-directory, of the program installation directory. It is different between Mac, Windows 32bit and Windows 64bit.
If you open the Ruby Console window from inside SketchUp, then type:
puts $:
You’ll see a listing of the $LOAD_PATH array (which also has the alias $:.) On 64bit Windows running 64bit SketchUp it looks similar to:```
C:/Program Files/SketchUp/SketchUp 2015/Tools/RubyStdLib
C:/Program Files/SketchUp/SketchUp 2015/Tools/RubyStdLib/platform_specific
C:/Program Files/SketchUp/SketchUp 2015/Tools
C:/Users/Dan/AppData/Roaming/SketchUp/SketchUp 2015/SketchUp/Plugins
The 3rd path is the path to the internal SketchUp ```Tools``` directory. (It is a utility directory that also has the Ruby Standard library in it. Do not confuse the directory name with "tools" that are used by the user in the SketchUp application. The dir name is an old legacy name that really has no meaning anymore. It should really be named "internal" or similar.)Suggested reading: Programming Ruby - 4th Edition
This is the old “Pick-Axe” book (named because it has a Pick-Axe on the cover.)
The 2nd Edition came free in the “doc” sub-directory of a System Ruby install during the 1.8 branch. (It is still a good book to read even that old version.)
Starting in the Ruby 1.9 branch, it was replaced with a simpler book “Book of Ruby” by Huw Collingbone (not what us ol’ programmer geeks would want as much.)
Now and then you can find postings of the Pick-Axe 3rd edition PDF online, but I do not believe these are official. (Probably bootleg.)
I have been spending my time learning how to manipulate Sketchup. But I had
to learn the basics of Ruby to do that. I’ve just discovered a style guide,
did read The Book of Ruby and studied the following links;
Lots of links and references, quick lookup
http://en.wikibooks.org/wiki/Ruby_Programming
Top Level to Docs
Ruby documentation site http://www.ruby-doc.org/
The std library
Ruby Standard Lib (online) includes a debugger module
http://ruby-doc.org/stdlib-2.2.1/
Ruby class library reference (online) Index of Files, Classes & Methods in Ruby 3.1.2 (Ruby 3.1.2)
Ruby general information http://www.ruby-lang.org
Library of examples with source
http://www.crai.archi.fr/rld/links_plugins_sites.php
helpful ruby info
http://www.crai.archi.fr/rld/links_ruby_sites.php
Learn Ruby the Hard Way - Read for Free easy sections with examples
Ruby Tutorial sections with examples
here you can browse the library alphabetically:
http://www.ruby-doc.org/stdlib/
Ruby core classes and standard lib:
Ruby Core Classes3 http://www.ruby-doc.org/core-2.0.0/index.html
Ruby Standard Library1 http://www.ruby-doc.org/stdlib-2.0.0/index.html
Ruby class library reference (to download) Ruby-Doc.org: Documenting the Ruby Language
Ruby On Rails Site http://www.rubyonrails.org/
Model vs Class discussion
http://www.railstips.org/blog/archives/2006/11/18/class-and-instance-variables-in-ruby/
Lots of links and references, quick lookup
http://en.wikibooks.org/wiki/Ruby_Programming
Top Level to Docs
Ruby documentation site http://www.ruby-doc.org/
The std library
Ruby Standard Lib (online) includes a debugger module
http://ruby-doc.org/stdlib-2.2.1/
Ruby class library reference (online) Index of Files, Classes & Methods in Ruby 3.1.2 (Ruby 3.1.2)
Ruby general information http://www.ruby-lang.org
Library of examples with source
http://www.crai.archi.fr/rld/links_plugins_sites.php
helpful ruby info (hacked site)
http://www.crai.archi.fr/rld/links_ruby_sites.php
Learn Ruby the Hard Way - Read for Free easy sections with examples
Ruby Tutorial sections with examples
here you can browse the library alphabetically:
http://www.ruby-doc.org/stdlib/
Ruby core classes and standard lib:
Ruby Core Classes3 http://www.ruby-doc.org/core-2.0.0/index.html
Ruby Standard Library1 http://www.ruby-doc.org/stdlib-2.0.0/index.html
Ruby class library reference (to download) Ruby-Doc.org: Documenting the Ruby Language
Ruby On Rails Site http://www.rubyonrails.org/
Model vs Class discussion
http://www.railstips.org/blog/archives/2006/11/18/class-and-instance-variables-in-ruby/
Brad Denniston
408-892-4544
don’t think I included this interesting style guide - I was reading it
yesterday and did not include it in my list:
Brad Denniston
408-892-4544
That is an internal style guide for GitHub employees.
It is based upon one for general public use here:
Even so,… it is only a guide, and I find many “rules” not to make sense, or just taking one arbitrary way over another. Some “rules” do not jive with the general leaning of other similar “rules” (ie, the variant treatment of spaces with regard to parenthesis and parameter lists, in contrast to treatment of spaces with other types of punctuation, operators and brackets.)
The foremost “rule” should be readability and understandability, if other people will be reading or working on the code other than the original author.
Some coders write code with a minimum of spaces, and use the most cryptic block forms and compound statements. But they do not intend anyone else to work on the code.
Anyway… I am more in agreement with the original “bbatsov” and find more faults in the internal GitHub guide.
We all really tweak our own guide in the end.
You can fork one of those and change it as you become more of a Rubyist. For example, being in the engineering documentation field forever, I find the omission of category, section and clause numbers to be problematic when attempting to discuss changes to such a document.
Just the issue of a style guide would fill it’s own topic thread. (Likely each and every “rule” in a guide could generate it’s own heated debate thread.)
Back to the examples.
(a) You are still creating global variables. (They begin with a $ character.)
Global variables (references) are for use by EVERYONE in a shared ObjectSpace such as an embedded Ruby scripting engine, like SketchUp implements.
Most Ruby books and examples out on the web, do not take into account the clashing issues that might occur in a persistent shared ObjectSpace.
Once created, globals cannot be undefined (ie, garbage collected.) So they clutter up the listing of global variables. There is never really any good reason to use globals, even if you’re sharing data with everyone (for instance exposing state data to all users of the API.) It is better to expose attributes via well-named getter methods, of either a singleton class instance, or a module.
To share variables between the various methods, of an instance of a custom class, use @instance_vars. (If evaluated before explicitly initialized, Ruby will initialize them as referencing nil.)
To share variables between methods in a module, use @@module_vars.They must be initialized before they are ever evaluated. (Some authors avoid @@vars altogether because they act semi-globally within a class and all their sub-classes, but that is what they are for, and is their strength. It’s just that newbies some times get in trouble with them, so they are recommended only for experienced Rubyists.)
Anyway,… since A module definition is actually AN instance of class Module, you can also use @instance_vars within a module scope, and they will be visible to all module methods.
To share custom values that do not change, between any kind of method locally, use a custom CONSTANT_IDENTIFIER local to that object scope. (Ie, a module constant, or a class constant.)
To share custom constants between various scopes (classes and modules of differing plugins,) collect the constants into “mixin” library sub-module(s) of only constants, and mix them (as needed) into sub-modules and classes, using the include() method.
(b) The “Name” in Namespace implies ownership.
Never use a name for a (or begins a) toplevel namespace (module or class identifier) that belongs to some other entity, company or person, (ie, a trademark, salesmark, copyright, or brandname, etc. that you do not have permission to use.)
In the SketchUp Ruby API world, Sketchup, SketchUp, Layout,… or any case combination of, and compound name beginning with these, belong to the owner of the SketchUp application. (Currently add Trimble or any name beginning with this. ADD: List of current Trimble trademarks.)
For example most of the API classes are defined within a toplevel Sketchup module namespace.
But there are also some miscellaneous API class names that are compound names that begin with Sketchup, such as SketchupExtension. You should expect that there are others, and that any others could be created by the API team, anytime. (Sometimes they are unpublished classes for internal testing use only.)
Normally, you’d pick a unique toplevel module name either your company name or something unique based on your personal name, nickname etc.
But when writing examples that would be wrapped in an author’s namespace, I often just use the toplevel module name Author which implies that it should be changed to the author’s actual module name if they add to it, use it as a template, etc.
Any specific plugins would be created inside this toplevel module, in their own sub-module. Any custom classes specific to a certain plugin is defined within that plugin’s sub-module.
Any shared custom classes or library modules are created within the author’s toplevel module, but outside any specific plugin sub-module.
Your examples could do this, or use the module name Student.
Specific examples could be wrapped within sub-modules or classes, whose names correspond with example types.
Also… the examples are improperly indented.
#####################################################
# ex_3cubes.rb
# by Brad Denniston Copyright (c) 2014
#
# Demonstrate making cube instances
#
# THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR
# IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
# WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
module SketchUpEx
#
# add a cube component
#
$inst1
$inst2
$inst3
#
# cubecomp - create a cube definition and 3 instances
#
def SketchUpEx.cubecomp
points = Array.new
points[0] = ORIGIN
#... more code
end
SketchUpEx.cubecomp
end #module
Should be more like:
# ex_3cubes.rb
#{#===============================================
# ... folding documentation block ...
#}#===============================================
module Student
#
# add a cube component
def self.reset
@inst1 = nil
@inst2 = nil
@inst3 = nil
end
# cubecomp - create a cube definition and 3 instances
#
def self.cubecomp
self.reset
points = Array.new
points[0] = ORIGIN
#... more code
end
self.cubecomp
end # module
Also, one blank line after documentation block & before the start of the code’s first block opener statement, …
… and one blank line at the end of the file after the last block end closure.
Got it. Thanks Dan.
Little busy today and tomorrow - looking for my next software contract. But
I will work on this tonight and maybe Sunday afternoon.
Brad Denniston
408-892-4544
Got them done. All indents at 2 spaces, module names are now proper, no use
of SketchUp, use of self everywhere, added reset of globals. Did a run test
of each one. All checked in.
Thanks for the great reviews.
Brad Denniston
Brad Denniston
408-892-4544
A big thank you to both of you, seriously looking into the ruby side of Sketchup now
Bonjour ,
new and ols in Sketchup 6/7
i want to test scripts.
in the README of github said ‘move startup.skp …’
where is ‘startup.skp’ ?
thanks
Ignore that file. I didn’t realize it was still in the readme.
brad
Brad Denniston
408-892-4544