Unexpected behaviors in built-in functions

Question

Existence of this topic is discussed in this mathematica.meta post.

---

I'm sure I am not the only non-beginner in WL who from time to time finds themselves not being able to predict an outcome of a specific function or being surprised it returned something. E.g.:

FileExistsQ[""] (*unevaluated + message*)

I'm talking about cases which have in common that such problematic outcomes could be considered an exception from a convention/best practices, or even an apparent bug. Sometimes they are just that, and sometimes there is a deeper explanation, deep enough not to be obvious when a problem occurs.

Anyway, the time is wasted on debugging or guessing which exceptions to handle.

A cheat-sheet with those cases can facilitate better programming.

Points to be fulfilled by an on-topic answer:

• observed behavior deviates from the expected behavior

  based on either documentation or a pattern established by other functions, please provide links or explanation.

• documented/officially supported features

• features that in principle work correctly/as designed

What is NOT on topic:

• bug reports

  (we should consider allowing exposing bugs reported n versions earlier and still affecting poor programmers)

• backward incompatible changes

  there is a separate thread for this: Incompatible Changes since Mathematica Version 7?

• very localized/subjective report

  (need to think how to define them well as the line is blurred here)

An example is worth 1000 words so I will start with the case of ...Q functions. The whole thread is meant to be community wiki so feel free to suggest/make edits.

---

Index:

• ***Q functions

• Functions supporting for Directory[]

• Exceptions in the standard stylesheet/style inheritance stack

• Arguments conventions for export like functions

• Exceptions to "the first option's value wins" rule (the most recent update)

---

Related links:

• tutorial/SomeGeneralNotationsAndConventions

Answer 1

...Q functions that can return something else than True or False

TL;DR;

Those exceptions return unevaluated or $Failed which needs handling.

Or if you don't want to think about that and only True is what matters then use TrueQ[] along with these predicate functions, e.g. TrueQ[FileExistsQ[filename]].

It may not be a complete list yet, but here's a start:

• FileExistsQ
• DirectoryQ
• GeoWithinQ
• ImageInstanceQ
• SocketReadyQ

Following two just coincidentally have Q at the end but let's include it here even if they are clear as exceptions.

• EllipticNomeQ
• InverseEllipticNomeQ

Further reading:

One can be beaten by:

FileExistsQ[""] 

FileExistsQ::fstr: File specification is not a string of one or more characters.

FileExistsQ[""]

Why it can be surprising:

An important feature of all the Wolfram Language property-testing functions whose names end in Q is that they always return False if they cannot determine whether the expression you give has a particular property.

- tutorial/PuttingConstraintsOnPatterns

How to find them? One way is to investigate messages (except usage):

Select[
  {#, Column@
      DeleteCases[Messages@Evaluate@ToExpression[#], 
       HoldPattern[
         Verbatim[HoldPattern][MessageName[_, "usage"]]] :> _]} & /@ 
   Names["*Q"]
  , #[[2]] =!= Column[{}] &
  ] // Grid[#, Alignment -> {Left, Top}] &

It maybe makes sense to return $Failed in case of connection problems, but I'd say it is better not to name your function with ...Q if it needs e.g. internet connection.

Answer 2

Support for Directory[]

This was always puzzling me but I'm happy to delete this answer if I'm alone in this.

TL;DR;

Functions that do NOT respect Directory[]:

• NotebookOpen (*1*)
• NotebookLocate (*1*)

• NotebookSave (*2*)

• SystemDialogInput

1. Respects CurrentValue[NotebookPath] quick fix is to e.g. NotebookOpen @ AbsoluteFileName @ _

2. Respects the most recent notebook saving directory! You need to FileNameJoin + Directory[]

Functions that DO but one might not expect that knowing cases above:

• NotebookImport (*!*)
• CDFDeploy

Motivation

I came to this neighbourhood as of Mathematica V7 and I didn't have much experience with command line etc. In this context the border between the Kernel and the FrontEnd was very blurred at the beginning.

It took me quite a while to get used to that and even though I can explain it now, I am still claiming it is confusing.

The more that ref / NotebookPath:

This function has not been fully integrated into the long-term Wolfram Language, and is subject to change.

Answer 3

Exceptions in the standard stylesheet/style inheritance stack

Quick list of deviations

Feel free to add anything, try to make it short and if needed add examples or more explanation at the end of the answer.

• "DockedCell" style is inserted in every DockedCell before any explicit style.

  So either you overwrite "DockedCells" in your stylesheet or use explicit options in Cell, see "DockedCell" example.

• "InlineCell" same story but less problematic as "InlineCell" styles are less invasive. So keep that in mind when defining custom DefaultInlineCellStyle.

• "InlineCellEditing" as above if you want to adjust/switch of orange-ish background that appears during edition you need to modify this style even even for custom DefaultInlineCellStyle

• All style + FormatType issue, see topic linked below for full explanation. TL;DR;? better do not use All.

Points from above, with a little background, are mentioned in Order/Dependency of Styles in a Stylesheet.

• Button(Box)'s Appearance is inserted explicitly during typesetting

  which makes it impossible to set Button's appearance via a stylesheet or style with outer ButtonBoxOptions. You need to set Appearance -> Inherited to do so. See Button Appearance example.

• cell's top CellMargin behavior in presence of PageBreakAbove -> True in that cell.

  See: 154542. Quick fix is to add CellElementSpacings -> {"ClosedGroupTopMargin" -> 100} option.

• bug: notebook's WindowSize->All ignores the very bottom CellMargins

  see more in 112593

• bug DockedCell on Windows can't be White 160356

Motivation

The idea and scheme is quite simple see: tutorial / WorkingWithStylesheets / Inheritance

But there is no way to check where current setting for e.g. FontSize comes from. Which makes 'debugging' styles extremely painful. Any exception from the simple scheme makes it even worse, that is why one needs to know what to expect.

Examples

- "DockedCell"

CreateDocument[{},
 DockedCells -> Cell["test", "myDockedCell"],
 StyleDefinitions -> Notebook[{
    Cell[StyleData[StyleDefinitions -> "Default.nb"]],
    Cell[StyleData["myDockedCell"], Background -> Red, FontSize -> 30]
    }]
 ]

The docked cell is gray despite stylesheet Background spec for myDockedCell, FontSize works well. That is because "DockedCell" style has Background option.

So every Cell[content, style, opts] inside DockedCells effectively becomes Cell[content, "DockedCell, style, opts]...

- Button Appearance

Style[
 Button["LabeL", Print[1]],
 ButtonBoxOptions -> {ImageSize -> {200, 200}, Appearance -> "FramedPalette"}
]

ImageSize is respected but Appearance not, you need Button["LabeL", Print[1], Appearance -> Inherited] to make it work but then you ask yourself, why bother with nice setup and not create myButton function and put all stuff there?

Official classification of the issue: 116030#comment315233_116030

Answer 4

Arguments conventions for export like functions

It is not that tough yet I'm always confused, so again, if that is only me let me know and I will delete that answer.

Export[      "where", what, how]
CDFDeploy[   "where", what]
Write[       "where", what..]
WriteString[ "where", what..]
LinkWrite[   "where", what]
Save[        "where", what]
DumpSave[    "where", what]

Put[         what.., "where"]
PutAppend[   what.., "where"]    
CloudDeploy[ what, "where"]
CloudPut[    what, "where"]
CloudSave[   what, "where"]
CloudExport[ what, how, "where"]

So Put/PutAppend order and shuffled CloudExport are outliers one has to keep in mind.

Answer 5

Exceptions to "first option's value takes precedence" rule

One usually expects expr[opt1 -> a, opt1 -> b] to be equivalent to expr[opt1 -> a]. At the end this is how Replace* functions work: opt1 /. {opt1 -> a, opt1 ->b } returns a.

Thare are exceptions where the last one is chosen though, mostly related to a FrontEnd.

Many of them are related to controllers because of how they are implemented. They don't use OptionValue to extract options but something along those lines:

controller[_Dynamic, ___, specificOption -> specificValue, ___]:=...

See SaveDefinitions example, you can always lookup definitions with PrintDefinitions.

1. StyleDefinitions option for notebooks

2. SaveDefinitions -> False for DynamicModule

(* in construction *)

Code samples:

Ad 1.

CreateDocument[Pane["Test", 600],     
 StyleDefinitions -> "Dialog.nb", StyleDefinitions -> "Default.nb",     
 WindowTitle      -> "A dialog" , WindowTitle      -> "A notebook"
]

 (* Default.nb with "A dialog" title" *)

Ad 2.

 foo[]:=1;
 ToBoxes @ DynamicModule[{x}, Dynamic@foo[], SaveDefinitions -> False, SaveDefinitions -> True]

(* foo included! *)