(*********************************************************************** Mathematica-Compatible Notebook This notebook can be used on any computer system with Mathematica 3.0, MathReader 3.0, or any compatible application. The data for the notebook starts with the line of stars above. To get the notebook into a Mathematica-compatible application, do one of the following: * Save the data starting with the line of stars above into a file with a name ending in .nb, then open the file inside the application; * Copy the data starting with the line of stars above to the clipboard, then use the Paste menu command inside the application. Data for notebooks contains only printable 7-bit ASCII and can be sent directly in email or through ftp in text mode. Newlines can be CR, LF or CRLF (Unix, Macintosh or MS-DOS style). NOTE: If you modify the data for this notebook not in a Mathematica- compatible application, you must delete the line below containing the word CacheID, otherwise Mathematica-compatible applications may try to use invalid cache data. For more information on notebooks and Mathematica-compatible applications, contact Wolfram Research: web: http://www.wolfram.com email: info@wolfram.com phone: +1-217-398-0700 (U.S.) Notebook reader applications are available free of charge from Wolfram Research. ***********************************************************************) (*CacheID: 232*) (*NotebookFileLineBreakTest NotebookFileLineBreakTest*) (*NotebookOptionsPosition[ 30975, 1040]*) (*NotebookOutlinePosition[ 32029, 1076]*) (* CellTagsIndexPosition[ 31985, 1072]*) (*WindowFrame->Normal*) Notebook[{ Cell[CellGroupData[{Cell[TextData[ "Tools for Application Package Testing"], "Title", Evaluatable->False, AspectRatioFixed->True], Cell[TextData["E. C. Martin"], "Subtitle", Evaluatable->False, AspectRatioFixed->True], Cell[CellGroupData[{Cell[TextData[StyleBox["Introduction", Evaluatable->False, AspectRatioFixed->True, FontSize->16]], "Section", Evaluatable->False, AspectRatioFixed->True], Cell[CellGroupData[{Cell[TextData[{ StyleBox["MathSource", Evaluatable->False, AspectRatioFixed->True, FontFamily->"Times", FontSize->12, FontSlant->"Italic"], StyleBox[" includes some new tools to aid application developers.", Evaluatable->False, AspectRatioFixed->True, FontFamily->"Times", FontSize->12] }], "Text", Evaluatable->False, AspectRatioFixed->True, FontFamily->"Times", FontSize->12], Cell[TextData[{ StyleBox["Guidelines for ", Evaluatable->False, AspectRatioFixed->True, FontFamily->"Times", FontSize->12, FontWeight->"Plain", FontSlant->"Plain", FontTracking->"Plain", FontVariations->{"Underline"->False, "Outline"->False, "Shadow"->False}], StyleBox["Mathematica", Evaluatable->False, AspectRatioFixed->True, FontFamily->"Times", FontSize->12, FontWeight->"Plain", FontSlant->"Italic", FontTracking->"Plain", FontVariations->{"Underline"->False, "Outline"->False, "Shadow"->False}], StyleBox[" Documentation, Packages, and Notebooks", Evaluatable->False, AspectRatioFixed->True, FontFamily->"Times", FontSize->12, FontWeight->"Plain", FontSlant->"Plain", FontTracking->"Plain", FontVariations->{"Underline"->False, "Outline"->False, "Shadow"->False}] }], "Subsection", Evaluatable->False, AspectRatioFixed->True, FontFamily->"Times", FontSize->12, FontWeight->"Plain", FontSlant->"Plain", FontTracking->"Plain", FontVariations->{"Underline"->False, "Outline"->False, "Shadow"->False}], Cell[TextData["Package, Notebook, and test file templates"], "Subsection", Evaluatable->False, AspectRatioFixed->True, FontFamily->"Times", FontSize->12, FontWeight->"Plain", FontSlant->"Plain", FontTracking->"Plain", FontVariations->{"Underline"->False, "Outline"->False, "Shadow"->False}], Cell[TextData[{ StyleBox["Testing.m", Evaluatable->False, AspectRatioFixed->True, FontFamily->"Courier", FontSize->12, FontWeight->"Bold", FontSlant->"Plain", FontTracking->"Plain", FontVariations->{"Underline"->False, "Outline"->False, "Shadow"->False}], StyleBox[" for automating function testing and ", Evaluatable->False, AspectRatioFixed->True, FontFamily->"Times", FontSize->12, FontWeight->"Plain", FontSlant->"Plain", FontTracking->"Plain", FontVariations->{"Underline"->False, "Outline"->False, "Shadow"->False}], StyleBox["EscapingSymbols.m", Evaluatable->False, AspectRatioFixed->True, FontFamily->"Courier", FontSize->12, FontWeight->"Bold", FontSlant->"Plain", FontTracking->"Plain", FontVariations->{"Underline"->False, "Outline"->False, "Shadow"->False}], StyleBox[ " for detecting missing usage messages or spuriously exported symbols in \ packages. ", Evaluatable->False, AspectRatioFixed->True, FontFamily->"Times", FontSize->12, FontWeight->"Plain", FontSlant->"Plain", FontTracking->"Plain", FontVariations->{"Underline"->False, "Outline"->False, "Shadow"->False}] }], "Subsection", Evaluatable->False, AspectRatioFixed->True, FontFamily->"Times", FontSize->12, FontWeight->"Plain", FontSlant->"Plain", FontTracking->"Plain", FontVariations->{"Underline"->False, "Outline"->False, "Shadow"->False}]}, Open]], Cell[TextData[{ StyleBox["\nThis notebook describes the use of the packages ", Evaluatable->False, AspectRatioFixed->True, FontFamily->"Times", FontSize->12], StyleBox["Testing.m", Evaluatable->False, AspectRatioFixed->True, FontFamily->"Courier", FontSize->12, FontWeight->"Bold"], StyleBox[" and ", Evaluatable->False, AspectRatioFixed->True, FontFamily->"Times", FontSize->12], StyleBox["EscapingSymbols.m", Evaluatable->False, AspectRatioFixed->True, FontFamily->"Courier", FontSize->12, FontWeight->"Bold"], StyleBox[ ". Other packages used by the Software Quality Assurance (SQA) department \ at Wolfram Research, Inc. will be added to ", Evaluatable->False, AspectRatioFixed->True, FontFamily->"Times", FontSize->12], StyleBox["MathSource", Evaluatable->False, AspectRatioFixed->True, FontFamily->"Times", FontSize->12, FontSlant->"Italic"], StyleBox[" in the future, so developers are advised to query ", Evaluatable->False, AspectRatioFixed->True, FontFamily->"Times", FontSize->12], StyleBox["MathSource", Evaluatable->False, AspectRatioFixed->True, FontFamily->"Times", FontSize->12, FontSlant->"Italic"], StyleBox[" on a regular basis.", Evaluatable->False, AspectRatioFixed->True, FontFamily->"Times", FontSize->12] }], "Text", Evaluatable->False, AspectRatioFixed->True, FontFamily->"Times", FontSize->12]}, Open]], Cell[CellGroupData[{Cell[TextData["Testing packages"], "Section", Evaluatable->False, AspectRatioFixed->True, FontFamily->"Helvetica", FontSize->16], Cell[TextData[{ StyleBox["The package ", Evaluatable->False, AspectRatioFixed->True, FontFamily->"Times", FontSize->12], StyleBox["Testing.m", Evaluatable->False, AspectRatioFixed->True, FontFamily->"Courier", FontSize->12, FontWeight->"Bold"], StyleBox[ " is used by the SQA department to facilitate testing for correctness and \ regression testing (", Evaluatable->False, AspectRatioFixed->True, FontFamily->"Times", FontSize->12], StyleBox["i.e.", Evaluatable->False, AspectRatioFixed->True, FontFamily->"Times", FontSize->12, FontSlant->"Italic"], StyleBox[", testing whether the results obtained under one version of ", Evaluatable->False, AspectRatioFixed->True, FontFamily->"Times", FontSize->12], StyleBox["Mathematica", Evaluatable->False, AspectRatioFixed->True, FontFamily->"Times", FontSize->12, FontSlant->"Italic"], StyleBox[ " agree with those obtained under another). The package defines\nmany \ useful functions, only a few of which are described here. More information \ on the\npackage can be found in the ", Evaluatable->False, AspectRatioFixed->True, FontFamily->"Times", FontSize->12], StyleBox["Discussion", Evaluatable->False, AspectRatioFixed->True, FontFamily->"Courier", FontSize->12, FontWeight->"Bold"], StyleBox[" comment of ", Evaluatable->False, AspectRatioFixed->True, FontFamily->"Times", FontSize->12], StyleBox["Testing.m", Evaluatable->False, AspectRatioFixed->True, FontFamily->"Courier", FontSize->12, FontWeight->"Bold"], StyleBox[".", Evaluatable->False, AspectRatioFixed->True, FontFamily->"Times", FontSize->12] }], "Text", Evaluatable->False, AspectRatioFixed->True, FontFamily->"Times", FontSize->12], Cell[CellGroupData[{Cell[TextData["Testing your own packages"], "Subsection", Evaluatable->False, AspectRatioFixed->True, FontFamily->"Helvetica", FontSize->12], Cell[CellGroupData[{Cell[TextData[StyleBox["Running the tests in an existing test file", Evaluatable->False, AspectRatioFixed->True, FontSize->10]], "Subsubsection", Evaluatable->False, AspectRatioFixed->True], Cell[TextData[{ StyleBox[ "The \"Guidelines\" document gives an example package and an example test \ file for that package. In this example., the ", Evaluatable->False, AspectRatioFixed->True], StyleBox["NumberTheory`ContinuedFractions`", Evaluatable->False, AspectRatioFixed->True, FontFamily->"Courier", FontWeight->"Bold"], StyleBox[" package is loaded in the first test of the test file ", Evaluatable->False, AspectRatioFixed->True], StyleBox["ContinuedFractions1.mt", Evaluatable->False, AspectRatioFixed->True, FontFamily->"Courier", FontWeight->"Bold"], StyleBox[". (By convention, ", Evaluatable->False, AspectRatioFixed->True], StyleBox["Mathematica", Evaluatable->False, AspectRatioFixed->True, FontSlant->"Italic"], StyleBox[" test files have the suffix", Evaluatable->False, AspectRatioFixed->True], StyleBox[" ", Evaluatable->False, AspectRatioFixed->True, FontWeight->"Bold"], StyleBox[".mt", Evaluatable->False, AspectRatioFixed->True, FontFamily->"Courier", FontWeight->"Bold"], StyleBox[".)", Evaluatable->False, AspectRatioFixed->True], StyleBox[" ", Evaluatable->False, AspectRatioFixed->True, FontFamily->"Courier"], StyleBox[" The test file is \"run\" using the ", Evaluatable->False, AspectRatioFixed->True], StyleBox["TestRun", Evaluatable->False, AspectRatioFixed->True, FontFamily->"Courier", FontWeight->"Bold"], StyleBox[",", Evaluatable->False, AspectRatioFixed->True, FontFamily->"Courier"], StyleBox[" ", Evaluatable->False, AspectRatioFixed->True], StyleBox["RunFile", Evaluatable->False, AspectRatioFixed->True, FontFamily->"Courier", FontWeight->"Bold"], StyleBox[",", Evaluatable->False, AspectRatioFixed->True, FontFamily->"Courier"], StyleBox[" and ", Evaluatable->False, AspectRatioFixed->True], StyleBox["EndRun", Evaluatable->False, AspectRatioFixed->True, FontFamily->"Courier", FontWeight->"Bold"], StyleBox[" functions defined in ", Evaluatable->False, AspectRatioFixed->True], StyleBox["Testing.m", Evaluatable->False, AspectRatioFixed->True, FontFamily->"Courier", FontWeight->"Bold"], StyleBox[". The results of the run are written to ", Evaluatable->False, AspectRatioFixed->True], StyleBox["stdout", Evaluatable->False, AspectRatioFixed->True, FontFamily->"Courier", FontWeight->"Bold"], StyleBox[ " using a special notation. Note that all test numbers are enclosed in \ square brackets except for 4 which is enclosed in colons. This means that \ all six tests passed: tests 1-3, 5, 6 passed immediately and test 4 passed \ when the expected ouput was reevaluated. See the ", Evaluatable->False, AspectRatioFixed->True], StyleBox["Discussion", Evaluatable->False, AspectRatioFixed->True, FontFamily->"Courier", FontWeight->"Bold"], StyleBox[" comment of ", Evaluatable->False, AspectRatioFixed->True], StyleBox["Testing.m", Evaluatable->False, AspectRatioFixed->True, FontFamily->"Courier", FontWeight->"Bold"], StyleBox[" for details of this notation. ", Evaluatable->False, AspectRatioFixed->True] }], "Text", Evaluatable->False, AspectRatioFixed->True], Cell[CellGroupData[{Cell[TextData[ "<True], Cell[TextData[ "[1][2][3]:4:[5][6]\n\nTest Summary:\nTotal number of tests: 6\nNumber of \ tests passed completely: 6\nNumber of tests failed on messages: 0\nNumber of \ tests failed with caveats: 0\nNumber of tests failed completely: 0"], "Print",\ Evaluatable->False, AspectRatioFixed->True]}, Open]], Cell[TextData[{ StyleBox["Several files are created by the test run. ", Evaluatable->False, AspectRatioFixed->True], StyleBox["testfailure", Evaluatable->False, AspectRatioFixed->True, FontFamily->"Courier", FontWeight->"Bold"], StyleBox[" lists all failed tests. ", Evaluatable->False, AspectRatioFixed->True], StyleBox["testlog", Evaluatable->False, AspectRatioFixed->True, FontFamily->"Courier", FontWeight->"Bold"], StyleBox[" gives a complete log of the test run. ", Evaluatable->False, AspectRatioFixed->True], StyleBox[" ", Evaluatable->False, AspectRatioFixed->True, FontWeight->"Bold"], StyleBox["testrecord", Evaluatable->False, AspectRatioFixed->True, FontFamily->"Courier", FontWeight->"Bold"], StyleBox[ " maintains a record of all test runs; this is useful if you are running a \ number of test files at one time. ", Evaluatable->False, AspectRatioFixed->True], StyleBox["testtiming", Evaluatable->False, AspectRatioFixed->True, FontFamily->"Courier", FontWeight->"Bold"], StyleBox[" gives the timing for each step in the test run. \n\nHere the ", Evaluatable->False, AspectRatioFixed->True], StyleBox["testfailure", Evaluatable->False, AspectRatioFixed->True, FontFamily->"Courier", FontWeight->"Bold"], StyleBox[ " file is displayed . Recorded in the file are the time at which the tests \ started, the version of ", Evaluatable->False, AspectRatioFixed->True], StyleBox["Mathematica", Evaluatable->False, AspectRatioFixed->True, FontSlant->"Italic"], StyleBox[ " used in testing, the test file that was read, the time of test \ completion, CPU time, and information on each test failure, such as expected \ output and actual output.", Evaluatable->False, AspectRatioFixed->True] }], "Text", Evaluatable->False, AspectRatioFixed->True], Cell[CellGroupData[{Cell[TextData["!!testfailure"], "Input", AspectRatioFixed->True], Cell[TextData[ "Tests started at: {1993, 5, 6, 3, 51, 37}\nVersion: NeXT 2.2 (March 23, \ 1993)\n\n--------------------------------------------\n\nReading : \ ContinuedFractions1.mt at 3:51:37\n\n\n\ --------------------------------------------\nTests completed at {1993, 5, 6, \ 3, 51, 46}\n\nCPU time used: 8.594883 secs.\n\nTotal number of tests: 6.\n\ Number of tests passed completely: 6.\nNumber of tests failed on messages: 0.\ \nNumber of tests failed with caveats: 0.\nNumber of tests failed completely: \ 0."], "Print", Evaluatable->False, AspectRatioFixed->True]}, Open]]}, Open]], Cell[CellGroupData[{Cell[TextData[StyleBox["Creating a test file interactively", Evaluatable->False, AspectRatioFixed->True, FontSize->10]], "Subsubsection", Evaluatable->False, AspectRatioFixed->True], Cell[TextData[{ StyleBox[ "In the previous example, a test file was run that was created using a text \ editor ", Evaluatable->False, AspectRatioFixed->True], StyleBox["(", Evaluatable->False, AspectRatioFixed->True, FontFamily->"Courier", FontSize->8, FontWeight->"Bold"], StyleBox[ "perhaps the editor included in the Notebook front end). If you were \ testing a package that does series expansions and you had a math handbook \ with a table of such expansions, you might create a test file using the input \ and expected output as given in the table. This is testing for correctness. \ In contrast, if you have confidence in your package and would like to \ characterize its behavior before embarking on some new code development that \ may \"break\" your package, you might want to do regression testing. ", Evaluatable->False, AspectRatioFixed->True], StyleBox["Testing.m", Evaluatable->False, AspectRatioFixed->True, FontFamily->"Courier", FontWeight->"Bold"], StyleBox[ " provides functions for creating a test file interactively, so you do not \ have to use a text editor as you would for the previous example. Here a test \ file ", Evaluatable->False, AspectRatioFixed->True], StyleBox["ContinuedFractions2.mt", Evaluatable->False, AspectRatioFixed->True, FontFamily->"Courier", FontWeight->"Bold"], StyleBox[" is created using the functions ", Evaluatable->False, AspectRatioFixed->True], StyleBox["TestMake", Evaluatable->False, AspectRatioFixed->True, FontFamily->"Courier", FontWeight->"Bold"], StyleBox[" and ", Evaluatable->False, AspectRatioFixed->True], StyleBox["EndMake", Evaluatable->False, AspectRatioFixed->True, FontFamily->"Courier", FontWeight->"Bold"], StyleBox[".", Evaluatable->False, AspectRatioFixed->True] }], "Text", Evaluatable->False, AspectRatioFixed->True], Cell[CellGroupData[{Cell[TextData[ "<True], Cell[OutputFormData["\<\ ContinuedFractionForm[{5, 1, 1, 153}]\ \>", "\<\ ContinuedFractionForm[{5, 1, 1, 153}]\ \>"], "Output", Evaluatable->False, AspectRatioFixed->True]}, Open]], Cell[TextData[{ StyleBox[ "When the test file is displayed, you can see that the input and output of \ the ", Evaluatable->False, AspectRatioFixed->True], StyleBox["Mathematica", Evaluatable->False, AspectRatioFixed->True, FontSlant->"Italic"], StyleBox[" expressions evaluated between ", Evaluatable->False, AspectRatioFixed->True], StyleBox["TestMake", Evaluatable->False, AspectRatioFixed->True, FontFamily->"Courier", FontWeight->"Bold"], StyleBox[" and ", Evaluatable->False, AspectRatioFixed->True], StyleBox["EndMake", Evaluatable->False, AspectRatioFixed->True, FontFamily->"Courier", FontWeight->"Bold"], StyleBox[" were recorded using the ", Evaluatable->False, AspectRatioFixed->True], StyleBox["Test", Evaluatable->False, AspectRatioFixed->True, FontFamily->"Courier", FontWeight->"Bold"], StyleBox[" function syntax defined in ", Evaluatable->False, AspectRatioFixed->True], StyleBox["Testing.m", Evaluatable->False, AspectRatioFixed->True, FontFamily->"Courier", FontWeight->"Bold"], StyleBox[ ". The author of the test file and the date it was generated are included \ in a comment.", Evaluatable->False, AspectRatioFixed->True] }], "Text", Evaluatable->False, AspectRatioFixed->True], Cell[CellGroupData[{Cell[TextData["!!ContinuedFractions2.mt"], "Input", AspectRatioFixed->True], Cell[TextData[ "\n(** emily; Thu May 6 04:26:21 CDT 1993 **)\n\n\nTest[\n\ <False, AspectRatioFixed->True]}, Open]], Cell[TextData[{ StyleBox[ "The new test file can now be run. The square bracket notation of the \ report sent to ", Evaluatable->False, AspectRatioFixed->True], StyleBox["stdout", Evaluatable->False, AspectRatioFixed->True, FontFamily->"Courier", FontWeight->"Bold"], StyleBox[" indicates that both tests passed.", Evaluatable->False, AspectRatioFixed->True] }], "Text", Evaluatable->False, AspectRatioFixed->True], Cell[CellGroupData[{Cell[TextData[ "TestRun[]\nRunFile[\"ContinuedFractions2.mt\"]\nEndRun[]"], "Input", AspectRatioFixed->True], Cell[TextData[ "[1][2]\n\nTest Summary:\nTotal number of tests: 2\nNumber of tests passed \ completely: 2\nNumber of tests failed on messages: 0\nNumber of tests failed \ with caveats: 0\nNumber of tests failed completely: 0"], "Print", Evaluatable->False, AspectRatioFixed->True]}, Open]]}, Open]]}, Open]], Cell[CellGroupData[{Cell[TextData[ "Submitting your packages to Wolfram Research, Inc. for testing"], "Subsection", Evaluatable->False, AspectRatioFixed->True, FontFamily->"Helvetica", FontSize->12], Cell[TextData[{ StyleBox["With each revision of ", Evaluatable->False, AspectRatioFixed->True], StyleBox["Mathematica", Evaluatable->False, AspectRatioFixed->True, FontSlant->"Italic"], StyleBox[ ", a great effort is made to maintain backward-compatibility. However, it \ is not always possible to do this and take advantage of bug fixes and new \ functionality. If you are concerned about whether your package will be \ compatible with the version of ", Evaluatable->False, AspectRatioFixed->True], StyleBox["Mathematica", Evaluatable->False, AspectRatioFixed->True, FontSlant->"Italic"], StyleBox[" currently under development and are a heavy user of ", Evaluatable->False, AspectRatioFixed->True], StyleBox["Mathematica", Evaluatable->False, AspectRatioFixed->True, FontSlant->"Italic"], StyleBox[ ", one option is to volunteer for beta testing. Since only a limited \ number of developers can be beta testers, another option is to submit your \ package, together with test files characterizing package behavior, to ", Evaluatable->False, AspectRatioFixed->True], StyleBox["mathtest@wri.com", Evaluatable->False, AspectRatioFixed->True, FontFamily->"Courier", FontWeight->"Bold"], StyleBox[ ". This mailbox is regularly monitored; submissions will be added to the \ test suite run each evening, and failures will be reported to the submitter. \ Test files should be written using the functions provided in ", Evaluatable->False, AspectRatioFixed->True], StyleBox["Testing.m", Evaluatable->False, AspectRatioFixed->True, FontFamily->"Courier", FontWeight->"Bold"], StyleBox[" on ", Evaluatable->False, AspectRatioFixed->True], StyleBox["MathSource", Evaluatable->False, AspectRatioFixed->True, FontSlant->"Italic"], StyleBox[ ".\n\nNote that this is a way for a developer to do regression testing on a \ pre-beta version of ", Evaluatable->False, AspectRatioFixed->True], StyleBox["Mathematica", Evaluatable->False, AspectRatioFixed->True, FontSlant->"Italic"], StyleBox["; it is not a way to debug ", Evaluatable->False, AspectRatioFixed->True], StyleBox["Mathematica", Evaluatable->False, AspectRatioFixed->True, FontSlant->"Italic"], StyleBox[ " code. WRI welcomes the opportunity to learn of possible incompatiblities \ between a revision and outside packages early in the development cycle. ", Evaluatable->False, AspectRatioFixed->True] }], "Text", Evaluatable->False, AspectRatioFixed->True]}, Open]]}, Open]], Cell[CellGroupData[{Cell[TextData[StyleBox["Escaping symbols", Evaluatable->False, AspectRatioFixed->True, FontSize->16]], "Section", Evaluatable->False, AspectRatioFixed->True], Cell[TextData[{ StyleBox[ "It is generally considered poor programming practice to introduce symbols \ in a context visible to the user that do not have usage messages. The \ package ", Evaluatable->False, AspectRatioFixed->True, FontFamily->"Times", FontSize->12], StyleBox["EscapingSymbols.m ", Evaluatable->False, AspectRatioFixed->True, FontFamily->"Courier", FontSize->12, FontWeight->"Bold"], StyleBox[ "contains a utility function that will help you avoid this practice. \n\n\ The function ", Evaluatable->False, AspectRatioFixed->True, FontFamily->"Times", FontSize->12], StyleBox["EscapingSymbols", Evaluatable->False, AspectRatioFixed->True, FontFamily->"Courier", FontSize->12, FontWeight->"Bold"], StyleBox[ " compares the list of all symbols visible to the user prior to evaluating \ its argument to the list of symbols visible to the user after evaluating its \ argument. Any new symbols lacking usage messages are called ", Evaluatable->False, AspectRatioFixed->True, FontFamily->"Times", FontSize->12], StyleBox["escaping", Evaluatable->False, AspectRatioFixed->True, FontFamily->"Times", FontSize->12, FontSlant->"Italic"], StyleBox[" symbols.\n\nIf the argument to ", Evaluatable->False, AspectRatioFixed->True, FontFamily->"Times", FontSize->12], StyleBox["EscapingSymbols", Evaluatable->False, AspectRatioFixed->True, FontFamily->"Courier", FontSize->12, FontWeight->"Bold"], StyleBox[ " loads a package, this function can help the author determine which \ symbols need usage messages or which portions of code need to be changed to \ avoid introducing spurious symbols. Sometimes code located outside the \ private context can be rewritten without using \"index variables\". In other \ cases, the code can be relocated within the private context without any \ change in functionality.", Evaluatable->False, AspectRatioFixed->True, FontFamily->"Times", FontSize->12] }], "Text", Evaluatable->False, AspectRatioFixed->True, FontFamily->"Times", FontSize->12], Cell[CellGroupData[{Cell[TextData["A package with an escaping symbol"], "Subsection", Evaluatable->False, AspectRatioFixed->True, FontFamily->"Helvetica", FontSize->12], Cell[TextData[{ StyleBox[ "This is a package that exports symbols representing pitch/frequency \ equivalents. Since a similar usage message definition is needed for each \ combination of pitch class and octave, the definitions are made in a ", Evaluatable->False, AspectRatioFixed->True], StyleBox["Do", Evaluatable->False, AspectRatioFixed->True, FontFamily->"Courier", FontWeight->"Bold"], StyleBox[" loop. ", Evaluatable->False, AspectRatioFixed->True] }], "Text", Evaluatable->False, AspectRatioFixed->True], Cell[CellGroupData[{Cell[TextData["!!BadNotes.m\n"], "Input", AspectRatioFixed->True], Cell[TextData[ "BeginPackage[\"BadNotes`\"]\n\n\ Do[Scan[(MessageName[Evaluate[ToExpression[#<>ToString[k]]], \"usage\"] =\n\t\ #<>ToString[k]<>\" is the note \"<>#<>\n\t\" in octave \ \"<>ToString[k]<>\".\")&,\n\t{\"A\", \"Asharp\", \"B\", \"C\", \"Csharp\",\n\t\ \"D\", \"Dsharp\", \"E\", \"F\", \"Fsharp\", \"Gsharp\"}], {k, 0, 7}]\n\n\ Begin[\"`Private`\"]\n\n\tnotes = {\"A\", \"Asharp\", \"B\", \"C\", \ \"Csharp\", \"D\", \"Dsharp\",\n\t\t \"E\", \"F\", \"Fsharp\", \"G\", \ \"Gsharp\"};\n\tDo[Evaluate[ToExpression[notes[[Mod[k-1,12]+1]] <>\n\t \ ToString[Ceiling[k/12]-1]]] = 27.5 2.^((k-1)/12), {k, 96}]\n\nEnd[]\n\n\ EndPackage[]\n"], "Print", Evaluatable->False, AspectRatioFixed->True]}, Open]], Cell[TextData[{ StyleBox[ "To evaluate this package, the package is read in as an argument to ", Evaluatable->False, AspectRatioFixed->True], StyleBox["EscapingSymbols", Evaluatable->False, AspectRatioFixed->True, FontFamily->"Courier", FontWeight->"Bold"], StyleBox[ ". The spurious index variable introduced ouside the private context is \ detected and ", Evaluatable->False, AspectRatioFixed->True], StyleBox["EscapingSymbols", Evaluatable->False, AspectRatioFixed->True, FontFamily->"Courier", FontWeight->"Bold"], StyleBox[" returns the symbol in a list. ", Evaluatable->False, AspectRatioFixed->True] }], "Text", Evaluatable->False, AspectRatioFixed->True], Cell[CellGroupData[{Cell[TextData["<True], Cell[OutputFormData["\<\ {\"k\"}\ \>", "\<\ {k}\ \>"], "Output", Evaluatable->False, AspectRatioFixed->True]}, Open]]}, Open]], Cell[CellGroupData[{Cell[TextData["Rewriting the package to avoid escaping symbols"], "Subsection", Evaluatable->False, AspectRatioFixed->True, FontFamily->"Helvetica", FontSize->12], Cell[TextData[ "The defininition of usage messages can be rewritten without the use of an \ index variable. Usually code that makes use of indexing can be written more \ clearly using functional programming. "], "Text", Evaluatable->False, AspectRatioFixed->True], Cell[CellGroupData[{Cell[TextData["!!Notes.m\n"], "Input", AspectRatioFixed->True], Cell[TextData[ "BeginPackage[\"Notes`\"]\n\n\ Scan[(MessageName[Evaluate[ToExpression[#[[1]]<>#[[2]]]], \"usage\"] =\n\t\ #[[1]]<>#[[2]]<>\" is the note \"<>#[[1]]<>\" in octave \"<>#[[2]]<>\".\")&,\n\ Flatten[Outer[List,\n\t{\"A\", \"Asharp\", \"B\", \"C\", \"Csharp\", \n\t \ \"D\", \"Dsharp\", \"E\", \"F\", \"Fsharp\", \"Gsharp\"},\n\t ToString /@ \ Range[0, 7]], 1]]\n\nBegin[\"`Private`\"]\n\n\tnotes = {\"A\", \"Asharp\", \ \"B\", \"C\", \"Csharp\", \"D\", \"Dsharp\",\n\t\t \"E\", \"F\", \"Fsharp\", \ \"G\", \"Gsharp\"};\n\tDo[Evaluate[ToExpression[notes[[Mod[k-1,12]+1]] <>\n\t \ ToString[Ceiling[k/12]-1]]] = 27.5 2.^((k-1)/12), {k, 96}]\n\nEnd[]\n\n\ EndPackage[]\n"], "Print", Evaluatable->False, AspectRatioFixed->True]}, Open]], Cell[TextData[{ StyleBox["Now ", Evaluatable->False, AspectRatioFixed->True], StyleBox["EscapingSymbols", Evaluatable->False, AspectRatioFixed->True, FontFamily->"Courier", FontWeight->"Bold"], StyleBox[" returns an empty list. ", Evaluatable->False, AspectRatioFixed->True] }], "Text", Evaluatable->False, AspectRatioFixed->True], Cell[CellGroupData[{Cell[TextData["<True], Cell[OutputFormData["\<\ {}\ \>", "\<\ {}\ \>"], "Output", Evaluatable->False, AspectRatioFixed->True]}, Open]]}, Open]]}, Open]]}, Open]] }, FrontEndVersion->"Macintosh 3.0", ScreenRectangle->{{0, 640}, {0, 460}}, WindowToolbars->{}, CellGrouping->Manual, WindowSize->{520, 365}, WindowMargins->{{44, Automatic}, {Automatic, 1}}, PrivateNotebookOptions->{"ColorPalette"->{RGBColor, -1}}, ShowCellLabel->True, ShowCellTags->False, RenderingOptions->{"ObjectDithering"->True, "RasterDithering"->False}, MacintoshSystemPageSetup->"\<\ AVU/IFiQKFD000000W7D@09ag@0000000O=J`09FV" ] (*********************************************************************** Cached data follows. If you edit this Notebook file directly, not using Mathematica, you must remove the line containing CacheID at the top of the file. The cache data will then be recreated when you save this file from within Mathematica. ***********************************************************************) (*CellTagsOutline CellTagsIndex->{} *) (*CellTagsIndex CellTagsIndex->{} *) (*NotebookFileOutline Notebook[{ Cell[CellGroupData[{ Cell[1731, 51, 113, 3, 70, "Title", Evaluatable->False], Cell[1847, 56, 90, 2, 70, "Subtitle", Evaluatable->False], Cell[CellGroupData[{ Cell[1960, 60, 163, 5, 70, "Section", Evaluatable->False], Cell[CellGroupData[{ Cell[2146, 67, 425, 16, 70, "Text", Evaluatable->False], Cell[2574, 85, 1150, 44, 70, "Subsection", Evaluatable->False], Cell[3727, 131, 310, 10, 70, "Subsection", Evaluatable->False], Cell[4040, 143, 1508, 57, 70, "Subsection", Evaluatable->False] }, Closed]], Cell[5560, 202, 1508, 56, 70, "Text", Evaluatable->False] }, Closed]], Cell[CellGroupData[{ Cell[7100, 260, 136, 4, 70, "Section", Evaluatable->False], Cell[7239, 266, 1877, 70, 70, "Text", Evaluatable->False], Cell[CellGroupData[{ Cell[9139, 338, 148, 4, 70, "Subsection", Evaluatable->False], Cell[CellGroupData[{ Cell[9310, 344, 199, 5, 70, "Subsubsection", Evaluatable->False], Cell[9512, 351, 3398, 118, 70, "Text", Evaluatable->False], Cell[CellGroupData[{ Cell[12933, 471, 125, 3, 70, "Input"], Cell[13061, 476, 298, 6, 70, "Print", Evaluatable->False] }, Closed]], Cell[13371, 484, 1955, 64, 70, "Text", Evaluatable->False], Cell[CellGroupData[{ Cell[15349, 550, 66, 1, 70, "Input"], Cell[15418, 553, 580, 10, 70, "Print", Evaluatable->False] }, Closed]] }, Closed]], Cell[CellGroupData[{ Cell[16039, 565, 191, 5, 70, "Subsubsection", Evaluatable->False], Cell[16233, 572, 1963, 59, 70, "Text", Evaluatable->False], Cell[CellGroupData[{ Cell[18219, 633, 187, 4, 70, "Input"], Cell[18409, 639, 177, 7, 70, "Output", Evaluatable->False] }, Closed]], Cell[18598, 648, 1354, 49, 70, "Text", Evaluatable->False], Cell[CellGroupData[{ Cell[19975, 699, 77, 1, 70, "Input"], Cell[20055, 702, 273, 6, 70, "Print", Evaluatable->False] }, Closed]], Cell[20340, 710, 459, 16, 70, "Text", Evaluatable->False], Cell[CellGroupData[{ Cell[20822, 728, 110, 2, 70, "Input"], Cell[20935, 732, 284, 5, 70, "Print", Evaluatable->False] }, Closed]] }, Closed]] }, Closed]], Cell[CellGroupData[{ Cell[21269, 739, 189, 6, 70, "Subsection", Evaluatable->False], Cell[21461, 747, 2630, 78, 70, "Text", Evaluatable->False] }, Closed]] }, Closed]], Cell[CellGroupData[{ Cell[24132, 827, 167, 5, 70, "Section", Evaluatable->False], Cell[24302, 834, 2175, 68, 70, "Text", Evaluatable->False], Cell[CellGroupData[{ Cell[26500, 904, 156, 4, 70, "Subsection", Evaluatable->False], Cell[26659, 910, 556, 17, 70, "Text", Evaluatable->False], Cell[CellGroupData[{ Cell[27238, 929, 67, 1, 70, "Input"], Cell[27308, 932, 705, 12, 70, "Print", Evaluatable->False] }, Closed]], Cell[28025, 946, 738, 25, 70, "Text", Evaluatable->False], Cell[CellGroupData[{ Cell[28786, 973, 103, 1, 70, "Input"], Cell[28892, 976, 112, 6, 70, "Output", Evaluatable->False] }, Closed]] }, Closed]], Cell[CellGroupData[{ Cell[29045, 984, 170, 4, 70, "Subsection", Evaluatable->False], Cell[29218, 990, 269, 5, 70, "Text", Evaluatable->False], Cell[CellGroupData[{ Cell[29510, 997, 64, 1, 70, "Input"], Cell[29577, 1000, 742, 12, 70, "Print", Evaluatable->False] }, Closed]], Cell[30331, 1014, 373, 14, 70, "Text", Evaluatable->False], Cell[CellGroupData[{ Cell[30727, 1030, 100, 1, 70, "Input"], Cell[30830, 1033, 106, 6, 70, "Output", Evaluatable->False] }, Closed]] }, Closed]] }, Closed]] }, Open ]] } ] *) (*********************************************************************** End of Mathematica Notebook file. ***********************************************************************)