Ruby in Chief Architect Chapter 43 Ruby is a popular, open-source programming language that can be used for a wide variety of purposes. In Chief Architect Premier, you can use Ruby 2.4.0 to create custom macros which can be used to produce object labels for specific needs and customized Materials List calculations. You can also type Ruby macro code bookended by percent signs into text objects and object labels. Ruby is considered to be easy to use by its many users - not all of whom are software developers. If you’d like to learn more, visit:  www.ruby-lang.org. TOPICS Creating User Defined Macros 1387 Working with NVPublishers 1387 Working with Name-Value Pairs 1389 Macros and Context 1390 Measurement and NumberFormatter Classes 1393 Text Macro Management Dialog 1396 The Ruby Console 1399 Viewing the Interactive Tutorial 1401 Migrating Legacy Ruby Code 1401 1386 Chief Architect Premier X15 Reference Manual - Creating User Defined Macros Creating User Defined Macros You can create your own custom macros for a variety of purposes in Chief Architect Premier, including: l Shortcuts for strings of text that are used repeatedly throughout a project. For examples, see Designer/Client Information on page 541. l Custom object labels. See Label Panel on page 700. l Custom labels inserted into text objects, callouts, and markers in plan view. See Referenced Object Context on page 1391. l Object Information that can be included in schedules and the Materials List. See Object Information Panel on page 1331. l Materials List formulas. See Materials List Formulas on page 1320. There are two broad categories of macro: l Text macros are essentially shortcuts that replace long strings of text with an inserted macro. Text macros can include Global macros with general information about the current view or file, but they cannot perform calculations. l Ruby macros, on other hand, can include Name-Value Pairs, perform calculations, and even reference scripts written in Ruby. They do not, however, use regular text. In order to function, the information in each Ruby macro must have a defined Context: Owner Object, Referenced Object, or Materials List Line Item. Macros will update whenever the display is redrawn. You can prompt the screen to redraw by zooming, panning, or selecting View> Refresh Display. See Window and View Tools on page 143. NAME-VALUE PAIRS AND PUBLISHERS At the heart of most Ruby macros are Name-Value Pairs, or NVPs, and Name-Value Publishers, or publishers. A publisher is simply an object that has attributes that can be reported by a Ruby macro, and an NVP is the name of such an attribute and its value. For example: l A cabinet is an example of a publisher. l The name of one of its attributes is height. l 36” is the value reported by height in a basic macro in a plan using US units. Most objects in Chief Architect Premier have a selection of NVPs which can be used to report information about them in Ruby macros. See To view a publisher’s Name-Value Pairs on page 1388. A Name-Value Pair can be used as a simple macro by bookending it with percent signs. For example, %height% will report the height of a wide variety of objects. See To insert a macro on page 541.   CREATING AND EVALUATING CUSTOM MACROS Custom Ruby macros are created in the Edit Text Macro dialog. See Edit Text Macro Dialog on page 1397.   Custom macros can be evaluated in the Ruby Console. See The Ruby Console on page 1399.   Working with NVPublishers NVPublishers, or publishers, are objects in Premier that have attributes that can be reported by a Ruby macro.   1387 Chief Architect Premier X15 Reference Manual - Working with NVPublishers In plan view, a publisher can either be an Owner Object or a Referenced Object.   l An Owner Object reports its own attributes directly in a label or using Object Information in a schedule or materials list.   l A Referenced Object’s attributes are reported by a macro inserted into a text object that is connected to the publisher by a line with arrow. See Referenced Object Context on page 1391.   To view a publisher’s Name-Value Pairs 1. Select Tools> Ruby Console .   2. Select an object in your plan - for example a base cabinet. This is an Owner Object.   3. Type owner.names in the Input text field of the Ruby Console and press the Enter key.   4. An array of NVPs will display in the Output field. These values are all attributes of the selected object.   5. To view the array as a list, type puts owner.names and press Enter.   You can request the NVPs for a Referenced Object just as you can for an Owner Object: select the Referenced Object and open the Ruby Console. Then, instead of typing owner.names, type referenced.names (or puts referenced.names).   Note: The name-value pairs for rooms cannot be used to create Referenced Object macros. They only work as Owner Object macros. A number of macros that describe rooms are available as Global Macros, which do work when placed in a Text object located inside a room. RELATED OBJECTS A given publisher may have NVPs that report information about objects associated with the publisher rather than about the publisher itself. For example, a base cabinet often has:   l An automatic countertop, which is a feature of the cabinet parametric object but is a publisher in its own right and has its own set of NVPs.   l Door and drawer panels, which are library symbols that are inserted into the cabinet. See Inserted Objects on page 973.   l Moldings, which are library items assigned to the cabinet.   l A room that the cabinet is located in.   These related objects are all publishers themselves and have their own NVPs.   To view an object’s related publishers 1. Use the Leader Line tool to create a Text Line with Arrow snapped to the object on the arrow end. See Leader Line on page 519.   2. In the Rich Text Specification dialog, type or insert the %object_properties% User Defined macro. See To insert a macro on page 541.   3. When you click OK, the text will report all NVPs, NVPublishers, and Collections associated with the object that the arrow is snapped to.   Note: The %object_properties% macro cannot be used with a Leader Line to view the related publishers of a room. Instead, place the Text object inside the room. To include a related object’s NVPs in a macro, use this format: related_publisher_name.nvp_name.   1388 Chief Architect Premier X15 Reference Manual - Working with Name-Value Pairs Related objects may also be nested more than one layer deep: related_publisher_name.related_publisher_ name.nvp_name.   COLLECTIONS Some objects can have more than one of a particular type of related object. For example, a cabinet may have multiple door or drawer panels. Each panel is an NVPublisher listed in a Collection. The layers of structural assemblies like walls are also listed in Collections.   There are two main ways to use Collections in a Ruby macro:   l Access elements at a specific index, like an Array: collection_name[index].nvp_name l Use a different Enumerable method with a Ruby block. Use this format, in which “parameter_name” can be replaced with any name/identifier:   collection_name.enumerable_method { |parameter_name| parameter_name.nvp_name } For more information, see: https://ruby-doc.org/core-2.4.0/Enumerable.html.   ROOMS Like other objects, rooms are publishers with related objects and collections associated with them. They are unusual, however, in that  if an otherwise independently placed object is positioned inside a room, that object will have NVPs that report information about the room.   This means that a text object placed inside a room can serve as a custom label, using a macro to report dynamic information about the room. l To add an NVP to a text object that reports information about the room the text is located in, use this format: room.nvp_name. See Working with NVPublishers on page 1387. l To create a custom macro to insert in a text object that reports information about the room the text is located in, use the Owner Object context and make sure "room" is defined as the publisher for all variables. See Owner Object Context on page 1391. It also means that architectural objects can report information about the room they are in in their labels, in schedules, and in the Materials List. Objects that are not located entirely inside one room - including doors, windows, and any other object that extends beyond the extents of a single room - do not have this ability.   Working with Name-Value Pairs NVP Names use all lower case characters and separate words using an underscore _ instead of a space. l Integer values are whole numbers. l Float values are numbers with decimal points. l Measurement values are a custom class that have numbers with decimal points and a unit of measurement. See Measurement Class on page 1393. l TrueClass reports that the publisher object has a particular attribute. l FalseClass reports that the publisher can have a particular attribute but does not. l NilClass reports that the publisher has a particular attribute, but that it doesn’t apply in the current instance. 1389 Chief Architect Premier X15 Reference Manual - Macros and Context l String values are composed of text. l Symbol values are similar to text. l NVPublishers identify related objects. l Collections identify collections of related objects. l Hash identifies a collection of user-specified Custom Object Fields and is only returned by the custom_fields NVP. There are two ways to view the NVPs associated with an object: l The Ruby Console can report all NVPs associated with a selected object. l The %object_information% macro can report all NVPs, NVPublishers, and Collections associated with an object. HASHES Ruby Hashes are collections of key-value pairs. In Chief Architect Premier, they can be used to access the information in Custom Object Fields. See Custom Object Fields on page 690. To include a Hash in a macro, use this format: custom_fields[“custom field name”]. NAME VALUE PAIRS AND DEFAULTS A number of NVPs for various objects end in ‘_is_default’. These NVPs will return either ‘true’ or ‘false’, depending on whether the object in question is set to use the dynamic default for that attribute. See Dynamic Defaults on page 79. Macros and Context Ruby macros can be used in different contexts, but in order for the Name-Value Pairs in a macro to report the correct information, the macro needs to identify the context it is designed to be used in.   NON-EVALUATED TEXT MACROS Non-evaluated text macros primarily act as shortcuts for strings of text that you use often in your work. They are dynamic, so if you need to modify a string, you can simply edit the associated macro instead of locating and changing every instance of the text in the plan or layout file.   Non-evaluated text macros cannot display dynamic information about a particular object or perform calculations, however.   To create a non-evaluated text macros 1. Open the Text Macro Management dialog and click the New button.   2. In the Edit Text Macro dialog:   l Type the desired text.   l Insert any Global text macros that you need. Non-evaluated User Defined macros can also be included.   l Inserted macros should use the format: %macro_name%.   l Leave the Evaluate check box unchecked.   3. Confirm that the macro is valid by checking its Expanded Macro Value in the Text Macro Management dialog.   The resulting macro can be inserted into a text object. Although it cannot not display dynamic information about a particular object or perform calculations, it can also be inserted into an object’s label or added to its Object Information.   1390 Chief Architect Premier X15 Reference Manual - Macros and Context OWNER OBJECT CONTEXT The Owner Object context allows a macro to perform calculations and dynamically report information about an object in its label and Object Information.   To create an Owner Object macro 1. Select an object for which you would like to create a custom macro.   2. With the object selected, open the Text Macro Management dialog and click the New button.   3. In the Edit Text Macro dialog:   l You can use any NVPs associated with the selected object in the macro. See Working with Name-Value Pairs on page 1389.   l NVPs do not require special formatting, but macros inserted using the %macro_name% format cannot be used.   l To include a Ruby macro within another Ruby macro, use this format: macros.macro_name. l When the intended owner is a text object reporting information about a room, use this format: room.nvp_name. See Working with NVPublishers on page 1387. l Check Evaluate and select “Owner Object” from the Context drop-down list.   4. Confirm that the macro is valid by checking its Expanded Macro Value in the Text Macro Management dialog.   The resulting macro can be inserted into the label for any object for which it is Valid.   REFERENCED OBJECT CONTEXT When a Ruby macro is assigned the Referenced Object context, it can be inserted into text with an arrow pointing to the object it refers to and then perform calculations or report information about that object.   To create a Referenced Object macro 1. Select a text object with an arrow that is snapped to an object for which you would like to create a custom macro.   2. Open the Text Macro Management dialog and click the New button.   3. In the Edit Text Macro dialog:   l You can use any NVPs associated with the object that the text arrow is pointed to.   l NVPs do not require special formatting, but macros inserted using the %macro_name% format cannot be used.   l To include a Ruby macro within another Ruby macro, use this format: macros.macro_name>.   l Check Evaluate and select “Referenced Object” from the Context drop-down list.   4. Confirm that the macro is valid by checking its Expanded Macro Value in the Text Macro Management dialog.   To use a Referenced Object macro 1. Insert the custom macros into a Text, Rich Text, Callout, or Marker object.   2. Draw a Text Line with Arrow between the text object and the object that your Referenced Object macro describes.   1391 Chief Architect Premier X15 Reference Manual - Macros and Context Note: Referenced Object macros cannot be used with a Leader Line to report information about a room. Instead, use the Owner Object context, place the Text object inside the room, and use a macro in which "room" is defined as the publisher for all variables. See Owner Object Context on page 1391, above. MATERIALS LIST LINE ITEM CONTEXT A Materials List Line Item macro can be inserted into a cell in a materials list.   To create a Materials List Line Item macro 1. Open the Text Macro Management dialog and click the New button.   2. In the Edit Text Macro dialog:   l You can use any Name-Value Pairs associated with the object that the macro is meant to describe.   l Name-Value Pairs do not require special formatting, but macros inserted using the %macro_name% format cannot be used.   l To include a Ruby macro within another Ruby macro, use this format: macros.macro_name.   l Check Evaluate and select “Materials List Line Item” from the Context drop-down list.   3. Unlike other types of macros, its validity cannot be confirmed in the Text Macro Management dialog.   To use a Materials List Line Item macro 1. Select an object and click the Open Object edit button.   2. On the COMPONENTS panel of the specification dialog, select a component or subcomponent associated with the object.   3. Click in a Formula cell to select it, then click a second time to edit the cell.   4. Select Apply Formula to Source Object .   5. Click the Insert Macro button and insert a macro.   Macros can also be inserted in the Materials List in a similar manner. See To insert a custom Materials List formula on page 1321.   CONTEXTLESS MACROS Select “None” as the Context for a Ruby macro if you would prefer to define the Context within the macro’s Value.   To do this, type the Context before each NVP in the macro using this format:   l owner.name_value l referenced.name_value l line_item.name_value 1392 Chief Architect Premier X15 Reference Manual - Measurement and NumberFormatter Classes Measurement and NumberFormatter Classes Chief Architect Premier uses two custom Ruby classes that clarify and allow control of the units and formatting used by measurements: Measurement and NumberFormatter. MEASUREMENT CLASS All Name-Value Pairs that return length, area, or volume values do so by reporting a Measurement. A Measurement includes both a numeric value and a unit. The program has a set of hard-coded default units that can be used, and Custom Unit Conversions are supported as well. See Add Unit Conversion Dialog on page 111. The default unit used by a Measurement depends on its category as well as whether the file uses U.S. (“Imperial”) or metric units: Category Default Units Linear Inches or millimeters Area Square feet or square meters Volume Cubic feet or cubic meters Unitless None Anything else Items without precedent are represented in a power of inches or cm. Although Measurements have a unit, it is not reported unless you create a custom format. See NumberFormatter Class on page 1394, below. MEASUREMENT-SPECIFIC METHODS The Measurement class is not derived from the Numeric class but has many of the same methods. It also has a small set of custom methods: Measurement-Specific Method Return Comments compatible_with?(other: Measurement) True  | False Returns True if other is compatible. to_s(unit: Symbol | String = "") String Converts into a formatted representation of a Measurement. If a unit is provided, it must be compatible with the Measurement's type (linear, area, volume). to_f(unit: Symbol | String = "") Float Converts into a float with optional unit argument. If a unit is not provided, the result is converted to the appropriate default unit. convert_to(unit: Symbol | String) Float Converts into the specified unit. Raises an exception if the unit is incompatible. new([value: Float] = 0.0, [unit: Symbol | String] = "") Measurement Creates a new Measurement. If unit is not an empty String, it must be a defined unit. 1393 Chief Architect Premier X15 Reference Manual - Measurement and NumberFormatter Classes Measurement-Specific Method Return Comments type() String The "category" of measurement: "Linear", "Area", "Volume", "Unitless", or "Derived".   unitless?() True | False Returns True if the Measurement is unitless. CONVERSION METHODS The following units in Chief Architect Premier have hard-coded methods to convert a Numeric to a Measurement and vice versa: l Linear: inch, in, foot, ft, yard, yd, mm, cm, dm, m l Area: Prefix “sq_” to any of the above l Volume: Prefix “cu_” to any of the above Conversion Method Return Comments to_measurement([unit: Symbol | String] = "") SHORTCUT: .(unit) Measurement Returns a Measurement equivalent to "self.to_ f unit". Omitting unit will produce a unitless Measurement. +, -, *, and / operators will coerce the Numeric into a unitless Measurement. convert_to(unit: Symbol | String) SHORTCUT: .to_(unit) Float Converts into the specified unit. NUMBERFORMATTER CLASS Chief Architect Premier’s default format for Measurements uses up to 6 decimal places, a leading zero, and no trailing zeroes. It does not include a unit. The NumberFormatter class allows you to create formatting for Measurements to meet your needs. NUMBERFORMATTER METHODS NumberFormatter Method Return Comments apply(value: Numeric | Measurement) String Formats the given value. If it is a Measurement of type Linear, Area, or Volume, it must have a compatible unit. inspect() String Lists the current settings of the formatter. unit() String The unit the formatter is currently using. unit=(unit: Symbol | String) Sets the unit the formatter will use. Mixed units ("ft-in") and undefined units are supported. show_unit() True | False Reports whether the formatter will include the unit in the output. show_unit=(True | False) Sets whether the formatter will include the unit in the output. 1394 Chief Architect Premier X15 Reference Manual - Measurement and NumberFormatter Classes NumberFormatter Method Return Comments show_leading_zero() True | False Reports whether the formatter will include a leading zero. show_leading_zero=(True | False) Sets whether the formatter will include trailing zeros. show_trailing_zeros() True | False Reports whether the formatter will include trailing zeros. show_trailing_zeros=(True | False) Sets whether the formatter will include trailing zeros. use_fractions() True | False Reports whether the formatter will display fractions (True) or decimals (False). use_fractions=(True | False) Sets whether the formatter will display fractions (True) or decimals (False). decimal_places() Fixnum Reports the maximum number of decimal places the formatter will use when not displaying fractions. decimal_places=(Fixnum) Sets the maximum number of decimal places the formatter will use when not displaying fractions. Must be >= 0. denominator() Fixnum Reports the denominator the formatter will use when displaying fractions. denominator=(Fixnum) Sets the denominator the formatter will use when displaying fractions. Must be >= 1. thousands_separator() String The thousands separator displayed for numbers greater than 999. An empty String represents no thousands separator. thousands_separator= (separator: String) Sets the thousands separator displayed for numbers greater than 999. An empty String represents no thousands separator. show_denominator() True | False Reports whether the denominator will be shown when displaying fractions. show_denominator=(True | False) Sets whether the denominator will be shown when displaying fractions. When the denominator is hidden, fractions are never reduced. reduce_fractions() String | False Reports the method used to reduce fractions, if any. Returns False if fractions aren't reduced. reduce_fractions=(method: :gcd | :closest | :none | "" | False) Sets the method used to reduce fractions. :gcd or "gcd" will use the greatest common divisor of the passed in value and the denominator. :closest or "closest" will ignore the set denominator and try to pick the closest equivalent fraction. :none, an empty String, or False will prevent fractions from being reduced and always use the set denominator. 1395 Chief Architect Premier X15 Reference Manual - Text Macro Management Dialog Text Macro Management Dialog A list of all user-defined text macros present in the current plan or layout file can be accessed by selecting CAD> Text> Text Macro Management. l If you wish to create a user defined macro for an object, or find out whether an existing macro is valid for an object, open this dialog while the object is selected. l To create a user-defined macro to be inserted into a text object that describes another object, or to find out whether such a macro is valid, select a text object with an arrow pointing to the object in question and then open this dialog. See Macros and Context on page 1390. An object-specific version of this dialog is also available for objects saved in an unlocked library. Right-click on a single object of a type able to display labels and select Text Macro Management from the contextual menu. See Using the Contextual Menu on page 951. l Any Owner Object macros assigned to the object’s label when it is added to the library are listed here. Note that objects in some manufacturer catalogs may include macros. See Manufacturer Catalogs on page 961. l Custom macros can be imported to and exported from a library object, and additional macros can be added to the object, but you cannot specify them as part of a label while it is in the library. l When the object is added to a plan, any macros associated with it are added to the plan, as well. User Defined Macros An alphabetical list of all User-Defined Macros present in the current file displays here.   l Click on the Name of a macro to select it.   l If a macro is Valid in the current context, a check mark will display to the right of its Name. See Macros and Context on page 1390.   l In legacy files, macros using deprecated behaviors may be present. When this is the case, an additional Info column will be present. See Migrating Legacy Ruby Code on page 1401.   l Information about a selected macro displays in the Macro Value and Expanded Macro Value fields to the right of the list. The Macro Value field shows the defined Value of the selected macro. The Expanded Macro Value shows the output of the macro in the current context. Buttons Edit or delete the selected text macro, create a new one, or import or export macros to and from other files. See Importing 1396 Chief Architect Premier X15 Reference Manual - Text Macro Management Dialog and Exporting Macros on page 1399, below.   l Click the Edit button to make changes to the selected macro in the Edit Text Macro dialog. Only available when an existing macro is selected.   l Click the New button to open the Edit Text Macro dialog and create a new macro.   l Click the Copy button to create a copy of the currently selected macro and open the Edit Text Macro dialog. Only available when an existing macro is selected.   l Click the Delete button to remove the selected macro from the list. Only available when an existing macro is selected.   l Click the Import button to open the Import Text Macros dialog and import macros exported from another file into the current file. See Importing Files on page 45.   l Click the Export button to open the Export Text Macros dialog and make the user-defined macros in this file available to be imported into another file. See Exporting Files on page 41.   l Click the Migrate button to migrate a legacy macro to the latest version. Only available when a legacy macro is selected. See Migrating Legacy Ruby Code on page 1401. Macro Value The Macro Value field displays the content, or text used to define the selected macro. Expanded Macro Value The Expanded Macro Value field displays the information that the macro reports. If the selected macro is not Valid in the current context,  “#Evaluation Error#” will display here, Show Evaluation Error If the selected macro is not Valid, click the Show Evaluation Error button to open an Information box with a description of the problem. See Macros and Context on page 1390. EDIT TEXT MACRO DIALOG The Edit Text Macro dialog can be accessed by clicking the Edit, New, or Copy button in the Text Macro Management dialog. 1397 Chief Architect Premier X15 Reference Manual - Text Macro Management Dialog Name Type a short, descriptive Name for the macro. Macro names must be unique within a given file, or library object.   To avoid unexpected results, a macro should not have the same name as an NVP Name, NVPublisher, or Collection.   Value Type a macro using the Ruby 2.4.0 programming language in the Value field. NVPs existing macros, and references to Ruby .rb files can be included. l You can also copy an NVP out of the Ruby Console or a definition from an .rb file and paste it here. See To Copy, Cut and Paste text on page 515.   l Click the Insert button above the Value field to insert an already existing macro into the selected macro. See To insert a macro on page 541. Note: Chief Architect Premier uses Ruby 2.4.0. Context To create a Ruby macro with a context, check the Evaluate box, then select a Context from the drop-down list. When unchecked, a text macro will be created. See Non-Evaluated Text Macros on page 1390. l Choose None if the macro performs a function but doesn’t refer to an object or if the macro’s context - or contexts - are stated in its Value. l Choose Owner Object to create a macro for use in an object label.   l Choose Referenced Object to create a macro for use in a Text object with an arrow that points at an object that the macro describes.   l Choose Materials List Line Item to create a macro for use in the Materials List.   If the selected macro is a legacy macro using deprecated behavior, additional options will be available. See Migrating Legacy Ruby Code on page 1401.   l Click the Migrate Formula button to open the Migrate Ruby dialog. 1398 Chief Architect Premier X15 Reference Manual - The Ruby Console l After migrating the macro but before clicking OK in this dialog, you can click the Revert to Legacy button. This button is only available until you exit out of the dialog. Results For comparison purposes, the Original Result and New Result fields report Data Type and Value information when the selected macro is valid, or Evaluation Error information when it is not.   l The Original Result field reports information about the macro as it was when the dialog was first opened. This field will be blank for a newly created macro.   l The New Result field reports information based on changes made since the dialog was opened. Click OK to return to the Text Macro Management dialog. IMPORTING AND EXPORTING MACROS User-defined text macros can be exported out of one plan file, layout file, or library object and imported into another file or object using the Text Macro Management dialog. If the program encounters macros with duplicate names when importing into a plan or layout file, the Text Macro Name Conflict dialog will display, allowing you to choose how to handle the name conflict. l Select Rename the imported macro to keep both the existing macro and the one being imported. Then, type a short, descriptive, unique New Macro Name. By default, the new name is simply the original name appended by a number. l Select Discard the imported macro to use the existing macro already present in the destination file or library object rather than import the new one. l Select Replace the existing macro with the imported macro to delete the existing macro and replace it with the one being imported. l Check Do this for all remaining macro conflicts to apply the same choice for any other macros with conflicting names in the current import operation. If the program encounters a macro name conflict when importing into a library object or when placing a library object in a plan, a Question message box will ask if you wish to  replace the existing macros. Click Yes to replace any existing macros with imported macros of the same name or click No to keep the existing macros and not import those of the same name. The Ruby Console The Ruby Console can be used to access information about a variety of objects in Chief Architect Premier: information which can then be used to create custom Ruby macros. It can also be used to evaluate custom Ruby 1399 Chief Architect Premier X15 Reference Manual - The Ruby Console macros to confirm that they are valid. See Creating User Defined Macros on page 1387. Select Tools> Ruby Console to open the Ruby Console window. The Ruby Console can be open while you work using other tools in the program. The Ruby Console interface is simple: at the bottom of the window is an Input field where you can type commands, and the results of your commands display in the Output field above. Command Input Type expressions, or commands, in the Input field at the bottom of the window. l Press Enter on your keyboard to enter your expressions and see the results.   Note: Chief Architect Premier uses Ruby 2.4.0.   Results The results of your expressions display in the larger Output field, above.   l > at the beginning of a line indicates that what follows is your expression.   l => at the beginning of a line indicates that what follows is a result. l As you type multiple expressions, they and the new results are added below the previous ones.   l Use the scrollbar on the right to scroll up and down the results field. Tutorial Click the Tutorial button to view an interactive written tutorial presented in the Ruby Console. See Viewing the Interactive Tutorial on page 1401. Resize Click the size grip and drag to resize the Ruby Console window as needed. USEFUL EXPRESSIONS The following are a few commonly used expressions that you can use to obtain the attributes of one or more selected objects. Macro Description owner Returns the selected publisher selected Returns an array of multiple selected publishers referenced Returns the publishers 1400 Chief Architect Premier X15 Reference Manual - Viewing the Interactive Tutorial Macro Description .names Preceded by owner, selected, or referenced, this returns an array of NVPs for the selected publisher (s). . Preceded by owner, selected, or referenced, this returns the value of the NVPs bounded by the brackets for the selected publishers(s). puts Returns a list instead of an array. $ Indicates a global variable rather than a local variable. Viewing the Interactive Tutorial An introductory tutorial is included with Chief Architect Premier and can be run in the Ruby Console. To run it, select Tools> Ruby Console , then click the Tutorial button at the bottom of the dialog or simply type show in the Input field. If you have previously run the tutorial during the current program session, the tutorial will open to the last topic shown. If you have not run the tutorial this session, its Table of Contents will open. To view the tutorial’s Table of Contents at any time, type toc in the Input field. Migrating Legacy Ruby Code In Chief Architect Premier X11 and prior, Name-Value Pairs returned length, area, and volume measurements as Floats (or Integers, if rounded) instead of Measurements. When legacy Ruby macros or materials list formulas are evaluated in Version X15, the program will automatically check their version and provide an opportunity to migrate any instances of legacy Ruby code that it finds. MATERIALS LIST FORMULAS A cell with a legacy formula is identified by an Information icon. When the cell is moused over, its tool tip indicates the presence of a legacy formula, as well. See Materials List Formulas on page 1320. l Select the cell and click the Migrate Formula button to migrate the formula to use updated formatting. l After migrating the formula but before deselecting the cell, you can also click the Revert to Legacy button to restore the original legacy formula. This button is only available until you click out of the cell. TEXT MACROS Legacy Ruby macros are also identified by an Information icon in the Text Macro Management dialog. When the icon is moused over, its tool tip indicates the presence of a legacy macro, as well. Select the macro and click the Edit button for further options. See Text Macro Management Dialog on page 1396. l In the Edit Text Macro dialog for a legacy macro, click the Migrate Formula button to migrate the macro to use updated formatting. l After migrating the macro but before clicking OK in the Edit Text Macro dialog, you can click the Revert to Legacy button. This button is only available until you exit out of the dialog. 1401 Chief Architect Premier X15 Reference Manual - Migrating Legacy Ruby Code Backwards migration for formulas and macros is not supported. RUBY MIGRATION DIALOG The Migrate Formula button is available in the Materials List when a cell with a legacy formula is selected. In the Edit Text Macro and Text Macro Management dialogs, it is available when a legacy macro is selected. Click this button to open the Ruby Migration dialog. Macro The legacy macro's name displays here for reference.   l The macro can be edited in the text field using the Ruby 2.4.0 programming language. NVP’s, existing macros, and references to Ruby .rb files can be included.   l Click the Insert button above the text field to insert an already existing macro into the selected macro. See To insert a macro on page 541.   Issue l The Issue that needs to be addressed by migration is described here for reference. l If you make changes to the macro above and do not like the New Result below, click the Revert Changes button to restore the original value. Results These fields report Data Type and Value information when the selected macro is valid, or Evaluation Error information when it is not, for comparison purposes.   l The Original Result field reports information about the macro as it was when the dialog was first opened.   l The New Result field reports information based on changes made since the dialog was opened.   Click OK to return to the Text Macro Management dialog.   1402 Chief Architect Premier X15 Reference Manual - Resources and Support Resources and Support Chapter 44 Chief Architect technical support, training, and other resources to help you be successful using our software. TOPICS Learning and Inspiration 1404 Training Services 1405 Contacting Technical Support 1405 Error Messages 1406 Program Paths Dialog 1407 1403